Introduction

Overview

The Enrichment Service API provides endpoints for searching French companies and executives, enriching data records, looking up individuals, and downloading enriched results. All endpoints live under the /enrichment-service prefix.

Base URL

https://search.leads-siren.com/enrichment-service

Authentication

All secured endpoints require an API key sent in the x-api-key header: To get your API key, go to your profile section in app.leads-siren.com

curl -H "x-api-key: YOUR_API_KEY" \
  https://search.leads-siren.com/enrichment-service/test

Invalid or missing keys return 401 Unauthorized.

Active subscription required

API-key requests also require an active, non-expired subscription on the account. A subscription is considered valid only when its status is active and its end date is in the future. If there is no subscription, or it is inactive/expired, every secured endpoint returns:

{
  "detail": "Subscription not valid or expired"
}

with a 403 Forbidden status (or "Subscription not found" if the account has no subscription at all). Renew/reactivate the subscription to restore access.

Credits

Most API operations consume credits from your account balance. The credit cost varies by endpoint:

Endpoint	Credit Cost
Search Companies	Fixed per request
Sniper Search	Flat 100 (phone) + 10 (email) per search, max 110, page 1 only
Search Executives	1 credit per company/SIREN queried
Enrich Single	1/SIREN + 100/phone + 10/email per person (contacts charged only for `score > 40`)
SIREN Enrich (LPR)	1/dirigeant + 100/phone + 10/email per person (contacts charged only for `score > 40`)
Enrich (Bulk)	1/SIREN + 100/phone + 10/email per person
Export Executives	Free (no contact lookup)

All endpoints that return executive data support role_types (filter by role group), status_filter ("current", "former", or "all"), and person_type ("physical", "legal", or "all"). If omitted, all filters default to "all" (no filtering). If your account has insufficient credits, the API returns a 402 Payment Required error with details about your current balance and the required amount.

Pagination & billing

For paginated endpoints (e.g. Sniper Search), a search is charged only on page 1. Requesting subsequent pages (page: 2, 3, …) of the same search re-runs it and costs 0 credits. Practically, this means a client should page through all results of one search freely rather than issuing a fresh search per page. Sniper Search responses expose this explicitly via credits_charged (what this request cost) and search_cost (the flat cost of the search).

Request Format

All POST endpoints expect a JSON body with a data key:

{
  "data": {
    "filters": { ... },
    "page": 1
  }
}

Error Handling

The API uses standard HTTP status codes:

Code	Meaning
`200`	Success
`400`	Bad request — missing or invalid parameters
`401`	Unauthorized — invalid or missing API key
`402`	Payment required — insufficient credits
`403`	Forbidden — subscription not valid/expired, a search type not enabled for the account (address/email/phone), or invalid file path
`404`	Not found — resource or file does not exist
`500`	Internal server error

Error responses include a detail field:

{
  "detail": "Insufficient credits (have 0, need 5)"
}

Getting Started

Search

Enrichment

Results & Downloads

Overview

Base URL

Authentication

Active subscription required

Credits

Request Format

Error Handling

​Overview

​Base URL

​Authentication

​Active subscription required

​Credits

​Pagination & billing

​Request Format

​Error Handling

Overview

Base URL

Authentication

Active subscription required

Credits

Pagination & billing

Request Format

Error Handling