# Dropcontact API and MCP documentation
URL: https://developer.dropcontact.com/en/
The Dropcontact REST API finds or verifies professional email addresses and enriches B2B contacts with LinkedIn profiles and company data. Use the hosted MCP server to access Dropcontact from a compatible AI assistant, or the Google Sheets add-on to enrich a spreadsheet without writing code.
## Get started with the REST API
1. [Create a Dropcontact account](https://app.dropcontact.com/).
2. [Create and copy your API key](https://app.dropcontact.com/api) in the app.
3. Send your first request: see [Quickstart](https://developer.dropcontact.com/en/quickstart/).
## Use Dropcontact without code
You can also use Dropcontact from an AI assistant such as Claude, ChatGPT or Cursor with the [MCP server](https://developer.dropcontact.com/en/mcp/), or directly in your spreadsheets with the [Google Sheets add-on](https://developer.dropcontact.com/en/google-sheets/). Both use the same Dropcontact account and credits as the API.
Need help? Contact support@dropcontact.com.
---
# Authenticate the Dropcontact API with your API key
URL: https://developer.dropcontact.com/en/authentication/
The Dropcontact REST API uses an API key in the `X-Access-Token` request header. Create your key in the Dropcontact app and send it with each API call. MCP connections use a different authentication flow: see the [MCP server](https://developer.dropcontact.com/en/mcp/).
## Create your API key
[Create and copy your API key](https://app.dropcontact.com/api) in the app.
## Use your API key
Add your key in the `X-Access-Token` header of every request:
**Python**
```python
import requests
r = requests.post(
"https://api.dropcontact.com/v1/enrich/all",
headers={"X-Access-Token": apiKey},
)
```
**Shell**
```shell
curl -X POST https://api.dropcontact.com/v1/enrich/all \
-H "X-Access-Token: apiKey"
```
Replace `apiKey` with your key.
> **Warning:** Your key gives access to your account and your credits: don't share it, and don't expose it in a browser or in a public code repository.
## Related guides
- [Quickstart](https://developer.dropcontact.com/en/quickstart/)
- [MCP](https://developer.dropcontact.com/en/mcp/)
- [Handling errors](https://developer.dropcontact.com/en/errors/)
---
# Enrich your first contact with the Dropcontact API
URL: https://developer.dropcontact.com/en/quickstart/
Contact enrichment is asynchronous. Send a contact with `POST /v1/enrich/all`, save the returned `request_id`, then retrieve the result with `GET /v1/enrich/all/{request_id}`. This guide includes Python and cURL examples for both steps.
This guide enriches one contact: Denis Cohen, from the company Dropcontact.
## Before you start
You need a [Dropcontact account](https://app.dropcontact.com/) and an API key.
1. [Create and copy your API key](https://app.dropcontact.com/api) in the app.
2. Set it once at the top of your script, it is reused in every request:
```python
apiKey = "YOUR_API_KEY"
```
In the Shell examples, replace `YOUR_API_KEY` with your API key.
## Step 1: send the contact
**Python**
```python
r = requests.post(
"https://api.dropcontact.com/v1/enrich/all",
json={
"data": [
{
"first_name": "Denis",
"last_name": "Cohen",
"website": "dropcontact.com",
"email": "dc@dropcontact.io",
}
],
"siren": True,
"language": "en",
},
headers={
"Content-Type": "application/json",
"X-Access-Token": apiKey,
},
)
print(r.json())
```
**Shell**
```shell
curl -X POST https://api.dropcontact.com/v1/enrich/all \
-H "X-Access-Token: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"data": [{"first_name": "Denis", "last_name": "Cohen", "website": "dropcontact.com", "email": "dc@dropcontact.io"}], "siren": true, "language": "en"}'
```
All the fields and options you can send are listed in [Input record](https://developer.dropcontact.com/en/reference/input-record/).
The API answers:
```json
{
"credits_left": 15277,
"request_id": "qzmxkpvlrtdnhwa",
"error": false,
"success": true
}
```
Keep the `request_id`: you need it in step 2.
## Step 2: fetch the result
The enrichment takes a few seconds. Replace `REQUEST_ID` with the `request_id` from step 1, then send the request.
**Python**
```python
r = requests.get(
"https://api.dropcontact.com/v1/enrich/all/REQUEST_ID",
headers={"X-Access-Token": apiKey},
)
print(r.json())
```
**Shell**
```shell
curl https://api.dropcontact.com/v1/enrich/all/REQUEST_ID \
-H "X-Access-Token: YOUR_API_KEY"
```
If the result is not ready yet, the API answers with `"success": false`. Send the same request again 30 seconds later.
```json
{
"error": false,
"reason": "Request not ready yet, try again in 30 seconds",
"success": false
}
```
Once the result is ready, the API returns one object per contact, in the order you sent them:
```json
{
"data": [
{
"first_name": "Denis",
"last_name": "Cohen",
"full_name": "Denis Cohen",
"civility": "Mr",
"linkedin": "www.linkedin.com/in/cohendenis",
"location": "Paris, Île-de-France, France",
"email": [
{
"email": "dc@dropcontact.io",
"qualification": "nominative@pro"
}
],
"company": "Dropcontact",
"website": "www.dropcontact.com",
"siret_address": "7 Place de l'Hôtel de Ville",
"siret_zip": "93600",
"siret_city": "Aulnay-sous-Bois",
"country": "France",
"company_linkedin": "www.linkedin.com/company/dropcontact-email-finder",
"phone": "+33 1 23 45 67 89",
"company_turnover": "",
"company_results": "",
"nb_employees": "10-19",
"siren": "823752647",
"siret": "82375264700029",
"naf5_code": "62.01Z",
"naf5_des": "Programmation informatique",
"vat": "FR11823752647",
"industry": "Technology, Information and Internet",
"employee_count": "15"
}
],
"credits_left": 15277,
"error": false,
"success": true
}
```
The `qualification` field tells you how reliable each email is. All the fields of the result are listed in [Enriched record](https://developer.dropcontact.com/en/reference/enriched-record/).
## Next steps
- [Webhooks](https://developer.dropcontact.com/en/webhooks/): get the result directly on your server, without sending the request again.
- [Errors](https://developer.dropcontact.com/en/errors/): what to do when a request fails.
- [Credits](https://developer.dropcontact.com/en/credits/): when a credit is used.
- [API Reference](https://developer.dropcontact.com/en/reference/): all the endpoints and fields.
- OpenAPI specification: the API contract, to generate a client or give it to an AI agent.
---
# Dropcontact REST API reference
URL: https://developer.dropcontact.com/en/reference/
Explore Dropcontact REST API endpoints for contact enrichment, results, webhooks and credits. Find request fields, response formats and HTTP errors.
Use this reference to submit contacts for enrichment, retrieve results, manage your default webhook and check your credit balance. All endpoints use the base URL `https://api.dropcontact.com` and API key authentication.
The OpenAPI specification of the Dropcontact API describes all its endpoints and fields.
## Enrich
- [Enrich a batch of records](https://developer.dropcontact.com/en/reference/enrich-a-batch-of-records/)
- [Fetch enrichment results](https://developer.dropcontact.com/en/reference/fetch-enrichment-results/)
## Webhooks
- [Set the default webhook callback URL](https://developer.dropcontact.com/en/reference/set-the-default-webhook-callback-url/)
- [Get the default webhook callback URL](https://developer.dropcontact.com/en/reference/get-the-default-webhook-callback-url/)
- [Delete the default webhook callback URL](https://developer.dropcontact.com/en/reference/delete-the-default-webhook-callback-url/)
## Credits
- [Get Credits](https://developer.dropcontact.com/en/reference/get-credits/)
## Data formats
- [Input record](https://developer.dropcontact.com/en/reference/input-record/)
- [Enriched record](https://developer.dropcontact.com/en/reference/enriched-record/)
---
# Enrich a batch of contacts
URL: https://developer.dropcontact.com/en/reference/enrich-a-batch-of-records/
`POST https://api.dropcontact.com/v1/enrich/all`
Submit up to 250 contacts with `POST /v1/enrich/all`. The response returns a `request_id`, not the completed enrichment results. Use it to fetch the results with `GET /v1/enrich/all/{request_id}`, or provide a `custom_callback_url` to receive them by webhook.
## Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `hashedInputs` | query | boolean \| null | no | Adds the `hashedInputs` field to the response. |
## Request body
Body of POST /v1/enrich/all.
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | array of InputRecord | yes | List of contacts to enrich, 250 max per request. |
| `data[].first_name` | string \| null | no | Contact first name. |
| `data[].last_name` | string \| null | no | Contact last name. |
| `data[].full_name` | string \| null | no | Contact full name. Use this when first and last name are not provided separately. |
| `data[].civility` | string \| null | no | Contact civility / title (e.g. Mr, Mrs). |
| `data[].email` | string \| null | no | Contact email address. Verified and qualified during enrichment. |
| `data[].linkedin` | string \| null | no | Contact LinkedIn profile URL. |
| `data[].job` | string \| null | no | Contact job title. |
| `data[].job_function` | string \| null | no | Contact job function (broad category of the role). |
| `data[].job_level` | string \| null | no | Contact seniority level (e.g. manager, executive). |
| `data[].mobile_phone` | string \| null | no | Contact mobile phone number. |
| `data[].location` | string \| null | no | Contact location (city, region or country). |
| `data[].company` | string \| null | no | Company name. |
| `data[].website` | string \| null | no | Company website URL. |
| `data[].siret_address` | string \| null | no | Company street address (from the French SIRET registry). |
| `data[].siret_zip` | string \| null | no | Company postal code (from the French SIRET registry). |
| `data[].siret_city` | string \| null | no | Company city (from the French SIRET registry). |
| `data[].country` | string \| null | no | Company country. |
| `data[].company_linkedin` | string \| null | no | Company LinkedIn URL. |
| `data[].phone` | string \| null | no | Company standard phone number. |
| `data[].company_turnover` | string \| null | no | Company annual revenue. |
| `data[].company_results` | string \| null | no | Company annual results. |
| `data[].nb_employees` | string \| null | no | Number of employees. |
| `data[].num_siren` | string \| null | no | French SIREN code (emitted as `siren` on output). |
| `data[].siret` | string \| null | no | French SIRET code. |
| `data[].naf5_code` | string \| null | no | NAF/APE code. |
| `data[].naf5_des` | string \| null | no | NAF/APE code description. |
| `data[].vat` | string \| null | no | VAT number. |
| `data[].industry` | string \| null | no | Industry (LinkedIn). Only available on the Free and Growth plans. |
| `data[].employee_count` | string \| null | no | Employee count (LinkedIn). Only available on the Free and Growth plans. |
| `data[].custom_fields` | object \| null | no | Arbitrary custom fields returned as-is in the enriched result. |
| `siren` | boolean | no | Adds the company's SIREN and SIRET numbers to the result. |
| `language` | string \| null | no | Language of the email qualification label: `fr` or `en`. Any other value gives `en`. |
| `custom_callback_url` | string \| null | no | Webhook URL for this request only, called when the result is ready. Replaces the default webhook URL for this request. |
## Responses
### 200 — Request accepted
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | boolean | no | Whether an error occurred. |
| `success` | boolean | no | Whether the request was accepted. |
| `credits_left` | integer | yes | Number of credits left on your account. |
| `request_id` | string | yes | Request ID, used to fetch the result. |
| `hashedInputs` | array of string \| null | no | One signed token (JWT) per contact sent, in the order sent. Each token holds the contact's input data. Only present with `hashedInputs=true`. |
| `data` | array of PostRecord \| null | no | Contacts sent that have an error or a warning. Missing when no contact has one. |
| `data[].index` | integer | yes | |
| `data[].errors` | RecordErrors \| null | no | |
| `data[].warnings` | RecordWarnings \| null | no | |
### 400 — Malformed request
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | boolean | no | Whether an error occurred. |
| `reason` | string | yes | Why the request failed, or why the result is not ready yet. |
| `success` | boolean | no | Always false. |
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `reason` | string | yes | |
| `status` | string | yes | |
| `data` | array of PostRecord | yes | |
| `data[].index` | integer | yes | |
| `data[].errors` | RecordErrors \| null | no | |
| `data[].warnings` | RecordWarnings \| null | no | |
| `error` | boolean | no | |
| `success` | boolean | no | |
### 401 — Missing or invalid API key
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | boolean | no | Whether an error occurred. |
| `reason` | string | yes | Why the request failed, or why the result is not ready yet. |
| `success` | boolean | no | Always false. |
### 403 — Access denied
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | boolean | no | Whether an error occurred. |
| `reason` | string | yes | Why the request failed, or why the result is not ready yet. |
| `success` | boolean | no | Always false. |
### 422 — Validation Error
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | array of ValidationError | no | |
| `detail[].loc` | array of string \| integer | yes | |
| `detail[].msg` | string | yes | |
| `detail[].type` | string | yes | |
### 429 — Too many requests, or temporary error on our side: try again in a few seconds
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | boolean | no | Whether an error occurred. |
| `reason` | string | yes | Why the request failed, or why the result is not ready yet. |
| `success` | boolean | no | Always false. |
### 500 — Error on Dropcontact's side
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | yes | |
## Related guides
- [Quickstart](https://developer.dropcontact.com/en/quickstart/)
- [Rate Limits](https://developer.dropcontact.com/en/rate-limits/)
- [Webhooks](https://developer.dropcontact.com/en/webhooks/)
---
# Fetch enriched contacts by request_id
URL: https://developer.dropcontact.com/en/reference/fetch-enrichment-results/
`GET https://api.dropcontact.com/v1/enrich/all/{request_id}`
Use `GET /v1/enrich/all/{request_id}` to retrieve the results of a previously submitted batch. Check `success` even when the HTTP response is `200`. If results are not ready, wait 30 seconds before polling again, or use `forceResults=true` for records already processed.
## Parameters
| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `request_id` | path | string | yes | |
| `forceResults` | query | boolean \| null | no | Return the records already enriched instead of waiting for the whole batch. When true, the endpoint responds even while processing is still in progress (instead of asking you to retry) and adds a `status` field (`ready` or `in_progress`) telling you whether the batch is complete. |
## Responses
### 200 — Result ready, or not ready yet (`success: false` with a `reason`)
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | array of EnrichedRecord | yes | The enriched records, ordered by input index. |
| `data[].first_name` | string \| null | no | Contact first name. |
| `data[].last_name` | string \| null | no | Contact last name. |
| `data[].full_name` | string \| null | no | Contact full name. Use this when first and last name are not provided separately. |
| `data[].civility` | string \| null | no | Contact civility: `Monsieur` or `Madame` with `language: fr`, `Mr` or `Mrs` otherwise. |
| `data[].email` | array of EmailResult \| null | no | Found emails with their qualification. |
| `data[].linkedin` | string \| null | no | Contact LinkedIn profile URL. |
| `data[].job` | string \| null | no | Contact job title. |
| `data[].job_function` | string \| null | no | Contact job function (broad category of the role). |
| `data[].job_level` | string \| null | no | Contact seniority level (e.g. manager, executive). |
| `data[].mobile_phone` | string \| null | no | Contact mobile phone number. |
| `data[].location` | string \| null | no | Contact location (city, region or country). |
| `data[].company` | string \| null | no | Company name. |
| `data[].website` | string \| null | no | Company website URL. |
| `data[].siret_address` | string \| null | no | Company street address (from the French SIRET registry). |
| `data[].siret_zip` | string \| null | no | Company postal code (from the French SIRET registry). |
| `data[].siret_city` | string \| null | no | Company city (from the French SIRET registry). |
| `data[].country` | string \| null | no | Company country. |
| `data[].company_linkedin` | string \| null | no | Company LinkedIn URL. |
| `data[].phone` | string \| null | no | Company standard phone number. |
| `data[].company_turnover` | string \| null | no | Company annual revenue. |
| `data[].company_results` | string \| null | no | Company annual results. |
| `data[].nb_employees` | string \| null | no | Number of employees of the company, as a range (e.g. `10-19`). |
| `data[].siren` | string \| null | no | French SIREN code (input field is `num_siren`). |
| `data[].siret` | string \| null | no | French SIRET code. |
| `data[].naf5_code` | string \| null | no | NAF/APE code. |
| `data[].naf5_des` | string \| null | no | NAF/APE code description. |
| `data[].vat` | string \| null | no | VAT number. |
| `data[].industry` | string \| null | no | Industry (LinkedIn). Only available on the Free and Growth plans. |
| `data[].employee_count` | string \| null | no | Number of LinkedIn profiles linked to the company. Only available on the Free and Growth plans. |
| `data[].custom_fields` | object \| null | no | Custom fields echoed from the input. |
| `data[].company_change` | string \| null | no | Previous company name when a company change is detected. |
| `data[].errors` | RecordErrors \| null | no | |
| `data[].warnings` | RecordWarnings \| null | no | |
| `data[].status` | string \| null | no | `ready` or `in_progress`, only when forceResults=true. |
| `credits_left` | integer | yes | Credits remaining on the account. |
| `status` | string \| null | no | Global batch status (`ready`/`in_progress`), only when forceResults=true. |
| `error` | boolean | no | |
| `success` | boolean | no | |
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | boolean | no | Whether an error occurred. |
| `reason` | string | yes | Why the request failed, or why the result is not ready yet. |
| `success` | boolean | no | Always false. |
### 401 — Missing or invalid API key
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | boolean | no | Whether an error occurred. |
| `reason` | string | yes | Why the request failed, or why the result is not ready yet. |
| `success` | boolean | no | Always false. |
### 403 — Unknown account, or `request_id` sent by another account
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | boolean | no | Whether an error occurred. |
| `reason` | string | yes | Why the request failed, or why the result is not ready yet. |
| `success` | boolean | no | Always false. |
### 422 — Validation Error
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | array of ValidationError | no | |
| `detail[].loc` | array of string \| integer | yes | |
| `detail[].msg` | string | yes | |
| `detail[].type` | string | yes | |
### 500 — Internal Server Error
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | yes | |
## Related guides
- [Webhooks](https://developer.dropcontact.com/en/webhooks/)
- [Handling errors](https://developer.dropcontact.com/en/errors/)
- [Enriched record](https://developer.dropcontact.com/en/reference/enriched-record/)
---
# Set the default webhook callback URL
URL: https://developer.dropcontact.com/en/reference/set-the-default-webhook-callback-url/
`PUT https://api.dropcontact.com/v1/enrich/webhook`
Set a default callback URL for your account with `PUT /v1/enrich/webhook` and the `callback_url` field. Dropcontact uses this URL when an enrichment request does not provide its own `custom_callback_url`.
## Request body
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `callback_url` | string | yes | |
## Responses
### 200 — Successful Response
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | boolean | no | Whether an error occurred. |
| `success` | boolean | no | Whether the request was accepted. |
| `callback_url` | string | yes | |
### 401 — Missing or invalid API key
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | boolean | no | Whether an error occurred. |
| `reason` | string | yes | Why the request failed, or why the result is not ready yet. |
| `success` | boolean | no | Always false. |
### 403 — Unknown account
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | boolean | no | Whether an error occurred. |
| `reason` | string | yes | Why the request failed, or why the result is not ready yet. |
| `success` | boolean | no | Always false. |
### 422 — Validation Error
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | array of ValidationError | no | |
| `detail[].loc` | array of string \| integer | yes | |
| `detail[].msg` | string | yes | |
| `detail[].type` | string | yes | |
### 429 — Too many requests, or temporary error on our side: try again in a few seconds
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | boolean | no | Whether an error occurred. |
| `reason` | string | yes | Why the request failed, or why the result is not ready yet. |
| `success` | boolean | no | Always false. |
### 500 — Error on Dropcontact's side
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | yes | |
See the [Webhooks](https://developer.dropcontact.com/en/webhooks/) guide to receive the results on your server.
---
# Get the default webhook callback URL
URL: https://developer.dropcontact.com/en/reference/get-the-default-webhook-callback-url/
`GET https://api.dropcontact.com/v1/enrich/webhook`
Use `GET /v1/enrich/webhook` to read the default callback URL configured for your account.
## Responses
### 200 — Successful Response
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | boolean | no | Whether an error occurred. |
| `success` | boolean | no | Whether the request was accepted. |
| `callback_url` | string \| null | no | |
### 401 — Missing or invalid API key
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | boolean | no | Whether an error occurred. |
| `reason` | string | yes | Why the request failed, or why the result is not ready yet. |
| `success` | boolean | no | Always false. |
### 403 — Unknown account
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | boolean | no | Whether an error occurred. |
| `reason` | string | yes | Why the request failed, or why the result is not ready yet. |
| `success` | boolean | no | Always false. |
### 429 — Too many requests, or temporary error on our side: try again in a few seconds
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | boolean | no | Whether an error occurred. |
| `reason` | string | yes | Why the request failed, or why the result is not ready yet. |
| `success` | boolean | no | Always false. |
### 500 — Error on Dropcontact's side
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | yes | |
See the [Webhooks](https://developer.dropcontact.com/en/webhooks/) guide to receive the results on your server.
---
# Delete the default webhook callback URL
URL: https://developer.dropcontact.com/en/reference/delete-the-default-webhook-callback-url/
`DELETE https://api.dropcontact.com/v1/enrich/webhook`
Use `DELETE /v1/enrich/webhook` to remove the default callback URL for your account. Requests that include their own `custom_callback_url` still trigger webhooks. If there is no default URL to remove, the endpoint returns `404`.
## Responses
### 200 — Successful Response
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | yes | |
### 401 — Missing or invalid API key
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | boolean | no | Whether an error occurred. |
| `reason` | string | yes | Why the request failed, or why the result is not ready yet. |
| `success` | boolean | no | Always false. |
### 403 — Unknown account
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | boolean | no | Whether an error occurred. |
| `reason` | string | yes | Why the request failed, or why the result is not ready yet. |
| `success` | boolean | no | Always false. |
### 404 — No default webhook URL to delete
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | boolean | no | Whether an error occurred. |
| `reason` | string | yes | Why the request failed, or why the result is not ready yet. |
| `success` | boolean | no | Always false. |
### 429 — Too many requests, or temporary error on our side: try again in a few seconds
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `error` | boolean | no | Whether an error occurred. |
| `reason` | string | yes | Why the request failed, or why the result is not ready yet. |
| `success` | boolean | no | Always false. |
### 500 — Error on Dropcontact's side
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | yes | |
See the [Webhooks](https://developer.dropcontact.com/en/webhooks/) guide to receive the results on your server.
---
# Check your Dropcontact API credit balance
URL: https://developer.dropcontact.com/en/reference/get-credits/
`GET https://api.dropcontact.com/v1/account/credits`
Use `GET /v1/account/credits` to check your remaining Dropcontact credits. The response returns the balance in `credits`. This call does not consume a credit; enrichment responses use a separate field named `credits_left`.
## Responses
### 200 — Successful Response
| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `credits` | integer | yes | Total number of credits left on your account, free credits included. |
### 401 — Missing or invalid API key
## Related guides
- [Credits Policy](https://developer.dropcontact.com/en/credits/)
- [Authentication](https://developer.dropcontact.com/en/authentication/)
---
# Contact input fields for the Dropcontact API
URL: https://developer.dropcontact.com/en/reference/input-record/
A single record submitted to POST /enrich/all.
A record needs at least one company identifier (company, website, company_linkedin, num_siren
or siret), an email, or the person's LinkedIn profile. A record can hold up to 15 kB of data,
``custom_fields`` included. Unrecognized keys are reported as ``unexpected_field``.
| Field | Type | Description |
| --- | --- | --- |
| `first_name` | string \| null | Contact first name. |
| `last_name` | string \| null | Contact last name. |
| `full_name` | string \| null | Contact full name. Use this when first and last name are not provided separately. |
| `civility` | string \| null | Contact civility / title (e.g. Mr, Mrs). |
| `email` | string \| null | Contact email address. Verified and qualified during enrichment. |
| `linkedin` | string \| null | Contact LinkedIn profile URL. |
| `job` | string \| null | Contact job title. |
| `job_function` | string \| null | Contact job function (broad category of the role). |
| `job_level` | string \| null | Contact seniority level (e.g. manager, executive). |
| `mobile_phone` | string \| null | Contact mobile phone number. |
| `location` | string \| null | Contact location (city, region or country). |
| `company` | string \| null | Company name. |
| `website` | string \| null | Company website URL. |
| `siret_address` | string \| null | Company street address (from the French SIRET registry). |
| `siret_zip` | string \| null | Company postal code (from the French SIRET registry). |
| `siret_city` | string \| null | Company city (from the French SIRET registry). |
| `country` | string \| null | Company country. |
| `company_linkedin` | string \| null | Company LinkedIn URL. |
| `phone` | string \| null | Company standard phone number. |
| `company_turnover` | string \| null | Company annual revenue. |
| `company_results` | string \| null | Company annual results. |
| `nb_employees` | string \| null | Number of employees. |
| `num_siren` | string \| null | French SIREN code (emitted as `siren` on output). |
| `siret` | string \| null | French SIRET code. |
| `naf5_code` | string \| null | NAF/APE code. |
| `naf5_des` | string \| null | NAF/APE code description. |
| `vat` | string \| null | VAT number. |
| `industry` | string \| null | Industry (LinkedIn). Only available on the Free and Growth plans. |
| `employee_count` | string \| null | Employee count (LinkedIn). Only available on the Free and Growth plans. |
| `custom_fields` | object \| null | Arbitrary custom fields returned as-is in the enriched result. |
## Related guides
- [Enrich a batch of records](https://developer.dropcontact.com/en/reference/enrich-a-batch-of-records/)
- [Enriched record](https://developer.dropcontact.com/en/reference/enriched-record/)
---
# Enriched contact fields and email qualifications
URL: https://developer.dropcontact.com/en/reference/enriched-record/
A single enriched record returned by GET /enrich/all/{request_id}.
Only populated attributes are present (nothing is forced to null). Note the input/output
asymmetry: ``num_siren`` is returned as ``siren`` and ``email`` is a list of objects.
Dropcontact cleans the data it returns: first and last names get the right capital letters (a full
name is split into first and last name), LinkedIn URLs become ``www.linkedin.com/in/...``, the
website is reduced to its domain with ``www.``, and the company name, SIREN, SIRET and NAF code
are put in a standard format.
| Field | Type | Description |
| --- | --- | --- |
| `first_name` | string \| null | Contact first name. |
| `last_name` | string \| null | Contact last name. |
| `full_name` | string \| null | Contact full name. Use this when first and last name are not provided separately. |
| `civility` | string \| null | Contact civility: `Monsieur` or `Madame` with `language: fr`, `Mr` or `Mrs` otherwise. |
| `email` | array of EmailResult \| null | Found emails with their qualification. |
| `email[].email` | string | The email address. |
| `email[].qualification` | string | Composite `localpart@domain` qualification, localized via the request language. Localpart: nominatif/nominative, catch-all, generique/generic, Ne_Pas_Contacter/Do_Not_Contact, non_validé/non_validated, invalide/invalid. Domain: pro, perso, school, jetable/disposable, domaine invalide/invalid domain. Example: `nominatif@pro`. |
| `linkedin` | string \| null | Contact LinkedIn profile URL. |
| `job` | string \| null | Contact job title. |
| `job_function` | string \| null | Contact job function (broad category of the role). |
| `job_level` | string \| null | Contact seniority level (e.g. manager, executive). |
| `mobile_phone` | string \| null | Contact mobile phone number. |
| `location` | string \| null | Contact location (city, region or country). |
| `company` | string \| null | Company name. |
| `website` | string \| null | Company website URL. |
| `siret_address` | string \| null | Company street address (from the French SIRET registry). |
| `siret_zip` | string \| null | Company postal code (from the French SIRET registry). |
| `siret_city` | string \| null | Company city (from the French SIRET registry). |
| `country` | string \| null | Company country. |
| `company_linkedin` | string \| null | Company LinkedIn URL. |
| `phone` | string \| null | Company standard phone number. |
| `company_turnover` | string \| null | Company annual revenue. |
| `company_results` | string \| null | Company annual results. |
| `nb_employees` | string \| null | Number of employees of the company, as a range (e.g. `10-19`). |
| `siren` | string \| null | French SIREN code (input field is `num_siren`). |
| `siret` | string \| null | French SIRET code. |
| `naf5_code` | string \| null | NAF/APE code. |
| `naf5_des` | string \| null | NAF/APE code description. |
| `vat` | string \| null | VAT number. |
| `industry` | string \| null | Industry (LinkedIn). Only available on the Free and Growth plans. |
| `employee_count` | string \| null | Number of LinkedIn profiles linked to the company. Only available on the Free and Growth plans. |
| `custom_fields` | object \| null | Custom fields echoed from the input. |
| `company_change` | string \| null | Previous company name when a company change is detected. |
| `errors` | RecordErrors \| null | |
| `errors.unexpected_field` | array of string \| null | Submitted keys that are not recognized. |
| `errors.only_contact_data` | boolean \| null | True when the record has contact data but no usable organization data. |
| `warnings` | RecordWarnings \| null | |
| `warnings.empty_field` | array of string \| null | Submitted keys with an empty value. |
| `warnings.only_organization_data` | boolean \| null | True when the record has organization data but no contact data. |
| `status` | string \| null | `ready` or `in_progress`, only when forceResults=true. |
## Related guides
- [Fetch enrichment results](https://developer.dropcontact.com/en/reference/fetch-enrichment-results/)
- [Handling errors](https://developer.dropcontact.com/en/errors/)
---
# Receive Dropcontact enrichment results with webhooks
URL: https://developer.dropcontact.com/en/webhooks/
Dropcontact sends enrichment results to your callback URL once a batch has finished processing. Use a request-specific `custom_callback_url` or an account-level default webhook. Respond within 5 seconds and use `request_id` to handle repeated deliveries.
## What is a webhook?
A webhook is a URL on your side that Dropcontact calls when your results are ready. Instead of checking with the API from time to time whether your data is ready, you give us a URL and we send the results to it as soon as the enrichment is done.
There are two ways to receive webhooks:
1. The recommended way: with a custom callback URL.
2. With a default webhook URL.
You can only have one default webhook URL per account. If a `custom_callback_url` is provided in the POST request, it takes precedence over the default URL.
Your URL can start with `http://` or `https://`.
## Custom callback URL
Add the `custom_callback_url` field to your [Enrich a batch of records](https://developer.dropcontact.com/en/reference/enrich-a-batch-of-records/) request body. When the enrichment is complete, the results are sent to this URL. This is the easiest way to use webhooks and requires no prior setup.
**Python**
```python
import requests
r = requests.post(
"https://api.dropcontact.com/v1/enrich/all",
json={
"data": [
{
"first_name": "Denis",
"last_name": "Cohen",
"website": "dropcontact.com",
"email": "dc@dropcontact.io",
}
],
"siren": True,
"language": "en",
"custom_callback_url": "https://your-domain.com/callback",
},
headers={
"Content-Type": "application/json",
"X-Access-Token": apiKey,
},
)
```
**Shell**
```shell
curl -X POST https://api.dropcontact.com/v1/enrich/all \
-H "X-Access-Token: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"data": [{"first_name": "Denis", "last_name": "Cohen", "website": "dropcontact.com", "email": "dc@dropcontact.io"}], "siren": true, "language": "en", "custom_callback_url": "https://your-domain.com/callback"}'
```
## Default webhook URL
You can optionally set a default webhook URL that is used for all your enrichment requests that don't include a `custom_callback_url`.
Manage it with the dedicated endpoints:
- Set or update it: [Set the default webhook callback URL](https://developer.dropcontact.com/en/reference/set-the-default-webhook-callback-url/)
- See its current value: [Get the default webhook callback URL](https://developer.dropcontact.com/en/reference/get-the-default-webhook-callback-url/)
- Delete it: [Delete the default webhook callback URL](https://developer.dropcontact.com/en/reference/delete-the-default-webhook-callback-url/)
After deletion, only requests with a `custom_callback_url` trigger webhooks.
## Receive a webhook
Dropcontact sends a `POST` request to your URL once all the contacts of the request are processed, even if you already fetched part of the results with `forceResults`. Its body is a JSON list of webhooks. Each webhook contains the following fields:
| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Unique ID of the webhook. |
| `version` | integer | Version of the webhook format. Currently `1`. |
| `event_type` | string | Type of event. Always `enrich_api_result` for enrichment results. |
| `occurred_at` | integer | Date of the event, in seconds since January 1, 1970 (Unix timestamp). |
| `data` | object | The results: `request_id` (the request ID returned by your POST request) and `data` (the enriched records, in the same format as [Fetch enrichment results](https://developer.dropcontact.com/en/reference/fetch-enrichment-results/)). |
```json
[
{
"id": "",
"version": 1,
"event_type": "enrich_api_result",
"occurred_at": 1623153600,
"data": {
"request_id": "",
"data": [{
"first_name": "Peter",
"last_name": "Jackson"
}]
}
}
]
```
> **Note:** The `data` field does not contain the `credits_left` field. Use the [Get Credits](https://developer.dropcontact.com/en/reference/get-credits/) endpoint to retrieve it.
> **Note:** A request is always sent from one of these IP addresses: `18.202.84.106`, `52.48.65.147` or `54.74.141.102`.
> **Warning:** We don't guarantee the order of the webhooks. You must use the `request_id` to match the webhooks with the corresponding request. Furthermore, in rare scenarios, you may receive the same `request_id` in multiple webhooks.
## Respond to a webhook
Your server must answer with an HTTP code below `400` (for example `200`) within 5 seconds. A code of `400` or more, no answer within 5 seconds or a connection error counts as a failure.
If it fails, we try again:
1. First, up to 4 tries within a few seconds.
2. Then, up to 10 later tries, waiting longer each time: 16 seconds, then 32 seconds, and so on, up to about 2 hours 15 minutes between two tries.
After these 14 tries, the webhook is dropped. You can still get the results with [Fetch enrichment results](https://developer.dropcontact.com/en/reference/fetch-enrichment-results/).
Because of these new tries, you may receive the same webhook more than once. Use the `request_id` to ignore the ones you have already processed.
---
# How Dropcontact API credits are consumed
URL: https://developer.dropcontact.com/en/credits/
The Dropcontact API distinguishes email enrichment from verification of an email you submit. The rules below explain when a credit is consumed, when it is returned and where to read your remaining balance.
## Credits Count
Dropcontact operates on a **Pay on Success** model: you only pay for results.
A credit is consumed in two cases:
- **Email enrichment**: a credit is consumed only if the API returns a verified email address. Verification is included in that same credit. The credit is taken when the request is sent, then given back automatically if no email is found.
- **Email verification only**: if you pass an email address in the `"email"` field of the request, 1 credit is consumed for that verification. It is only 1 credit, even if another email is found, and it is not given back, even if the email sent turns out to be invalid.
If you don't have enough credits for all the records of the request, the whole request is refused with a `403` error. See [Errors](https://developer.dropcontact.com/en/errors/).
## Credits Roll Over / Carry Over option
Your unused credits roll over to the next billing period if this option is enabled for your current subscription.
## Credits Left
The `credits_left` field is returned in the responses of [Enrich a batch of records](https://developer.dropcontact.com/en/reference/enrich-a-batch-of-records/) and [Fetch enrichment results](https://developer.dropcontact.com/en/reference/fetch-enrichment-results/). It is not in webhooks.
To check your credits at any time, use the [Get Credits](https://developer.dropcontact.com/en/reference/get-credits/) endpoint. It returns the same balance, in the `credits` field.
---
# Dropcontact API rate limits and batch size limits
URL: https://developer.dropcontact.com/en/rate-limits/
The Dropcontact API limit is 60 requests per second. Each enrichment request accepts up to 250 contacts, with up to 15 kB of data per record. If you receive HTTP `429`, wait before retrying and increase the delay between attempts.
If you hit the API with too many requests in a given amount of time, subsequent requests will temporarily fail.
If your client gets rate-limited, you will start receiving `429 Too Many Requests` HTTP errors in response to your requests.
## Batch and record size limits
- Up to 250 records per request.
- Up to 15 kB of data per record, `custom_fields` included.
## Fetching results
To fetch a result, send the same request again every 30 seconds until it is ready. To make fewer calls, use [webhooks](https://developer.dropcontact.com/en/webhooks/): the result is sent to your server as soon as it is ready.
See [Errors](https://developer.dropcontact.com/en/errors/) for what to do when you receive a `429` error.
---
# Dropcontact API errors and how to handle them
URL: https://developer.dropcontact.com/en/errors/
Check both the HTTP status and the response body when handling Dropcontact API errors. An HTTP `200` can contain `success: false`. Read `reason` or `detail`, and distinguish request failures from errors and warnings affecting individual records.
## Check `success` for enrichment requests
For enrichment requests, a `200` status does not always mean your request succeeded. Always read the `success` field of the response.
While your batch is still processing, `GET /v1/enrich/all/{request_id}` answers `200` with `"success": false` and the reason `Request not ready yet, try again in 30 seconds`. It answers the same way when the `request_id` is unknown, or when we have a temporary problem on our side.
Fetch your results within 30 days: after that, they may no longer be available.
**What to do:** wait 30 seconds and try again. To avoid polling, use a [webhook](https://developer.dropcontact.com/en/webhooks/), or add `forceResults=true` to get the records that are already enriched.
## Where to read the error message
Most errors look like this. The message is in `reason`:
```json
{
"error": true,
"reason": "Too many records, you can only submit up to 250 records",
"success": false
}
```
Some errors (`404`, `422`, `500`, and errors from `GET /v1/account/credits`) put the message in `detail` instead:
```json
{
"detail": "Not Found"
}
```
## Errors by status code
### 400 Bad Request
Your request is not valid. Returned by `POST /v1/enrich/all`.
| Message | What to do |
| --- | --- |
| `Missing data in JSON` | Send at least one record in `data`. |
| `Too many records, you can only submit up to 250 records` | Split your records into batches of 250 or less. |
| `Data size is too big, you can only submit up to 15 kB of data in a single record` | Make the record smaller. Large `custom_fields` are the usual cause. See [Input record](https://developer.dropcontact.com/en/reference/input-record/). |
| `Request contains invalid input` | Every record is in error. Read `data[].errors` for each record. |
### 401 Unauthorized
Your API key is missing or not valid. Returned by every endpoint.
| Message | What to do |
| --- | --- |
| `No api key received. Please set 'X-Access-Token' header with your api key as value.` or `no-credentials` | Add the `X-Access-Token` header to your request. See [Authentication](https://developer.dropcontact.com/en/authentication/). |
| `Unknown account` or `invalid-api-key` | Your API key is wrong or disabled. Check it in the [Dropcontact app](https://app.dropcontact.com/api). |
### 403 Forbidden
Your API key is valid, but the action is refused.
| Message | Endpoints | What to do |
| --- | --- | --- |
| `Sorry, you must contact the support to enable your API access!` | `POST /v1/enrich/all` | Contact support@dropcontact.com to enable API access. |
| `You submitted X valid items but only have Y credits left` | `POST /v1/enrich/all` | [Buy credits](https://app.dropcontact.com/pricing), or send fewer records. See [Credits Policy](https://developer.dropcontact.com/en/credits/). |
| `Unknown account` | All except `GET /v1/account/credits` | Your account is not set up for the API yet. Sign in once to the [Dropcontact app](https://app.dropcontact.com), then contact support if it keeps happening. |
| `This request id was not sent by you` | `GET /v1/enrich/all/{request_id}` | This `request_id` belongs to another account. Check that you use the right API key. |
### 404 Not Found
| Message | Endpoints | What to do |
| --- | --- | --- |
| `No webhook callback found` | `DELETE /v1/enrich/webhook` | There is no default webhook URL to delete. Nothing to do. See [Webhooks](https://developer.dropcontact.com/en/webhooks/). |
| `Not Found` | Any | The URL you called does not exist. Check it, for example `/v1/enrich/all` and not `/v1/all`. |
### 422 Validation Error
The request body or a parameter does not have the right format.
`detail` lists each field in error. Fix your request using the [API Reference](https://developer.dropcontact.com/en/reference/).
This is also the case when `custom_callback_url` or the default webhook URL is not a valid URL, or is longer than 2,083 characters. See [Webhooks](https://developer.dropcontact.com/en/webhooks/).
### 429 Too Many Requests
You sent too many requests in a short time (see [Rate limits](https://developer.dropcontact.com/en/rate-limits/)), or we have a temporary problem on our side. The message is `please retry in a few seconds`.
**What to do:** wait a few seconds and try again, leaving more time between each try.
### 500 Internal Server Error
Something went wrong on our side, and we are notified automatically. The message is `An error occurred. Please retry later.`
**What to do:** try again later. If it keeps happening, contact support@dropcontact.com.
### 502, 503, 504
These errors come from our network, in front of the API: maintenance or time limit exceeded.
**What to do:** try again later.
## Record errors and warnings
Some problems only affect one record. The request still succeeds, and the problem is listed under `data[].errors` or `data[].warnings` for that record.
| Key | Type | Meaning | What to do |
| --- | --- | --- | --- |
| `unexpected_field` | Error | Some fields are not recognized and are ignored. The record is still processed. | Fix the field names listed. See [Input record](https://developer.dropcontact.com/en/reference/input-record/). |
| `only_contact_data` | Error | The record has a person but no company identifier (company, website, company_linkedin, num_siren, siret), no email and no LinkedIn profile of the person. | Add at least one of them so we can find the email. See [Input record](https://developer.dropcontact.com/en/reference/input-record/). |
| `empty_field` | Warning | Some fields were sent empty. | Fill them in, or don't send them. |
| `only_organization_data` | Warning | The record has a company but no person, so only the company is enriched. | Nothing to do if this is what you want. |
If every record of the request has an error, the API answers with a `400` error instead, for accounts that have the `API_ERROR` option. This option is on by default for accounts created since June 1, 2026.
---
# Dropcontact MCP server for Claude, ChatGPT and Cursor
URL: https://developer.dropcontact.com/en/mcp/
The hosted Dropcontact MCP (Model Context Protocol) server connects compatible AI assistants to B2B contact enrichment, email validation and credit balance tools. Connect to `https://mcp.dropcontact.com/mcp` using OAuth, or an API key in the `Authorization: Bearer ` header. The REST API uses the `X-Access-Token` header instead (see [Authentication](https://developer.dropcontact.com/en/authentication/)).
You can connect to our MCP server natively like Claude Desktop or by using compatible clients such as Cursor, Windsurf, Visual Studio Code, and others. There is nothing to install: the server is hosted by Dropcontact.
## Available MCP tools
It provides tools to:
- Enrich a contact from:
- First name + last name + company
- Full name + company
- LinkedIn URL
- Validate an email address
- Check your remaining credits
## How it works
An enrichment or email validation runs in two steps:
1. A first tool submits the request and returns a request ID. This step uses 1 credit. For an enrichment, the credit is given back if no email is found. An email validation always uses 1 credit, even if the email is invalid (see [Credits Policy](https://developer.dropcontact.com/en/credits/)).
2. A second tool uses this request ID to retrieve the result. It usually takes 10 to 60 seconds, and up to 3 minutes.
Your AI assistant chains both steps for you: you only need to ask in plain language.
## Example prompts
- "Find the professional email of Marie Dupont, who works at Dropcontact."
- "Enrich this LinkedIn profile: https://www.linkedin.com/in/mariedupont"
- "Is contact@example.com a valid email address?"
- "How many Dropcontact credits do I have left?"
## Setup instructions
> **Note:** Remote MCP connections are still early and the connection may fail or require multiple attempts. If you experience issues, try restarting your client or disabling and re-enabling the Dropcontact MCP server.
To connect to the Dropcontact MCP server, use the following configuration in your compatible client:
- Server URL: https://mcp.dropcontact.com/mcp
- Authentication: Handled automatically via OAuth (recommended), but we offer other ways (see below). With an API key, use the same key as for the API, in the `Authorization: Bearer ` header instead of `X-Access-Token`.
## Claude
### Individual (Claude Desktop)
1. Go to Settings > Connectors and click Add connector
2. Enter the URL: https://mcp.dropcontact.com/mcp
3. Complete the OAuth flow in the browser that opens
### Team, Enterprise
1. Go to Settings > Integrations and click Add more
2. Enter:
- Integration name: Dropcontact
- Integration URL: https://mcp.dropcontact.com/mcp
3. Enable the tools in your chats
## Cursor
Cursor supports multiple connection methods. Choose the one that fits your setup:
1. CTRL/CMD P and search for View: Open MCP Settings
2. Click on New MCP Server
3. Add the Dropcontact configuration to the json configuration file
### OAuth (recommended)
Authentication is handled automatically in the browser.
```json title="~/.cursor/mcp.json"
{
"mcpServers": {
"dropcontact-oauth": {
"url": "https://mcp.dropcontact.com/mcp"
}
}
}
```
### API key (direct URL)
Replace `` with your Dropcontact API key, available in the [Dropcontact app](https://app.dropcontact.com/api).
```json title="~/.cursor/mcp.json"
{
"mcpServers": {
"dropcontact-token": {
"url": "https://mcp.dropcontact.com/mcp",
"headers": {
"Authorization": "Bearer "
}
}
}
}
```
### OAuth via npx mcp-remote
Use this if your Cursor version does not support native remote MCP.
```json title="~/.cursor/mcp.json"
{
"mcpServers": {
"dropcontact-npx-oauth": {
"command": "npx",
"args": [
"mcp-remote",
"https://mcp.dropcontact.com/mcp"
]
}
}
}
```
### API key via npx mcp-remote
Replace `` with your Dropcontact API key, available in the [Dropcontact app](https://app.dropcontact.com/api).
```json title="~/.cursor/mcp.json"
{
"mcpServers": {
"dropcontact-npx-token": {
"command": "npx",
"args": [
"mcp-remote",
"https://mcp.dropcontact.com/mcp",
"--header",
"Authorization: Bearer ${API_TOKEN}"
],
"env": {
"API_TOKEN": ""
}
}
}
}
```
## ChatGPT
MCP servers can be added via the web app and are then available across all ChatGPT clients.
1. Go to Settings > Apps > Create app
2. Enter the following:
- MCP Server URL: https://mcp.dropcontact.com/mcp
- Authentication: OAuth
3. Click Create and complete the OAuth flow in the browser that opens
4. Once authenticated, the Dropcontact tools are available in your chats
## Others
Many other tools now support MCP servers. You can configure them to use Dropcontact's MCP server with the following settings:
### OAuth (recommended)
Authentication is handled automatically in the browser.
```json
{
"mcpServers": {
"dropcontact-oauth": {
"url": "https://mcp.dropcontact.com/mcp"
}
}
}
```
### API key (direct URL)
Replace `` with your Dropcontact API key, available in the [Dropcontact app](https://app.dropcontact.com/api).
```json
{
"mcpServers": {
"dropcontact-token": {
"url": "https://mcp.dropcontact.com/mcp",
"headers": {
"Authorization": "Bearer "
}
}
}
}
```
### OAuth via npx mcp-remote
Use this if your client does not support native remote MCP.
```json
{
"mcpServers": {
"dropcontact-npx-oauth": {
"command": "npx",
"args": [
"mcp-remote",
"https://mcp.dropcontact.com/mcp"
]
}
}
}
```
### API key via npx mcp-remote
Replace `` with your Dropcontact API key, available in the [Dropcontact app](https://app.dropcontact.com/api).
```json
{
"mcpServers": {
"dropcontact-npx-token": {
"command": "npx",
"args": [
"mcp-remote",
"https://mcp.dropcontact.com/mcp",
"--header",
"Authorization: Bearer ${API_TOKEN}"
],
"env": {
"API_TOKEN": ""
}
}
}
}
```
## Troubleshooting
| Problem or message | What to do |
| --- | --- |
| The connection fails or the OAuth window does not open | Restart your client, or disable and re-enable the Dropcontact MCP server, then connect again. |
| `The Dropcontact session has ended` | Reconnect the Dropcontact connector in your client and sign in again. |
| `Dropcontact rejected this API key` | Check that your API key is still active in the [Dropcontact app](https://app.dropcontact.com/api). |
| `Your Dropcontact account is not yet set up for MCP` | Sign in once to the [Dropcontact app](https://app.dropcontact.com) to activate your account, then try again. |
| `You have no remaining enrichment credits` | [Add credits](https://app.dropcontact.com/pricing) to your account. If you still have credits, contact support@dropcontact.com: your API access may not be enabled. |
| `Timeout while waiting for enrich contact response` | The result was not ready after 3 minutes. Ask your AI assistant to retrieve the result again with the same request ID, or retrieve it via the API once processing is complete. No extra credit is used. |
| `Dropcontact could not authenticate this request right now` | Try again in a moment. |
| `Too many requests. Please wait a moment before trying again.` | Wait a few seconds and try again. |
| `Dropcontact request failed`, `Dropcontact could not process this request` or `Dropcontact enrich request failed` | Something went wrong on our side. Try again later. If it keeps happening, contact support@dropcontact.com. |
| `Failed to retrieve credits` | Try again later. |
Still stuck? Contact us at support@dropcontact.com.
---
# Enrich Google Sheets contacts with the Dropcontact add-on
URL: https://developer.dropcontact.com/en/google-sheets/
The Dropcontact Google Sheets add-on enriches spreadsheet contacts without code. Install it from Google Workspace Marketplace, connect your Google account or API key, and process up to 10,000 rows using your Dropcontact account credits.
## What is the Google Sheets add-on?
The Dropcontact add-on lets you enrich the contacts of a Google Sheets file without writing any code. It reads the rows of your sheet, sends them to Dropcontact, and writes the results back into your file.
It finds or verifies:
- Professional email addresses
- Phone numbers
- LinkedIn profiles
- Company details (website, SIREN/SIRET, address, headcount…)
The add-on detects your columns automatically (first name, last name, company, email, LinkedIn…). You choose where the results go: in the existing columns, in new columns, or in a new sheet. It can enrich up to 10,000 rows at a time, and uses the credits of your Dropcontact account, as described in the [Credits Policy](https://developer.dropcontact.com/en/credits/).
## Install the add-on
1. Open the [Dropcontact page on the Google Workspace Marketplace](https://workspace.google.com/marketplace/app/dropcontact/557472153363) and click **Install**.
2. In a Google Sheets file, go to **Extensions > Dropcontact > Open Sidebar**.
## Connect to your Dropcontact account
You need a Dropcontact account. If you don't have one yet, [create one for free](https://app.dropcontact.com/signup).
In the sidebar, open **Authentication** and choose one of the two methods.
### With your Google account (recommended)
Use this method if you sign in to Dropcontact with the same Google account as the one you use in Google Sheets.
1. Select the **Google Account** tab.
2. Click **Check my account**.
3. The add-on finds your Dropcontact account and shows **Account found!**
If you see `No Dropcontact account linked to this Google account.`, your Google account is not linked to a Dropcontact account. Create an account with this Google account, or use the API key method below.
### With your API key
Use this method if your Dropcontact account uses another email address.
1. Copy your API key from the [Dropcontact app](https://app.dropcontact.com/api).
2. In the sidebar, select the **API Token** tab.
3. Paste your API key and click **Save & test token**.
4. The add-on shows **Token saved and validated**.
Once connected, click **Start enriching data**.
---
# Documentation API et MCP Dropcontact
URL: https://developer.dropcontact.com/fr/
L'API REST Dropcontact trouve ou vérifie les adresses email professionnelles et enrichit les contacts B2B avec leurs profils LinkedIn et les données de leur entreprise. Utilisez le serveur MCP hébergé pour accéder à Dropcontact depuis un assistant IA compatible, ou l'add-on Google Sheets pour enrichir un tableur sans écrire de code.
## Commencer avec l'API REST
1. [Créez un compte Dropcontact](https://app.dropcontact.com/).
2. [Créez et copiez votre clé API](https://app.dropcontact.com/api) dans l'app.
3. Envoyez votre première requête : voir [Démarrage rapide](https://developer.dropcontact.com/fr/quickstart/).
## Utiliser Dropcontact sans écrire de code
Vous pouvez aussi utiliser Dropcontact depuis un assistant IA comme Claude, ChatGPT ou Cursor avec le [serveur MCP](https://developer.dropcontact.com/fr/mcp/), ou directement dans vos tableurs avec l'[add-on Google Sheets](https://developer.dropcontact.com/fr/google-sheets/). Les deux utilisent le même compte et les mêmes crédits Dropcontact que l'API.
Besoin d'aide ? Contactez support@dropcontact.com.
---
# Authentifier l'API Dropcontact avec une clé API
URL: https://developer.dropcontact.com/fr/authentication/
L'API REST Dropcontact utilise une clé API dans l'en-tête `X-Access-Token`. Créez cette clé dans l'app Dropcontact et transmettez-la à chaque appel. Les connexions MCP utilisent une autre méthode d'authentification : consultez le [serveur MCP](https://developer.dropcontact.com/fr/mcp/).
## Créer votre clé API
[Créez et copiez votre clé API](https://app.dropcontact.com/api) dans l'app.
## Utiliser votre clé API
Ajoutez votre clé dans l'en-tête `X-Access-Token` de chaque requête :
**Python**
```python
import requests
r = requests.post(
"https://api.dropcontact.com/v1/enrich/all",
headers={"X-Access-Token": apiKey},
)
```
**Shell**
```shell
curl -X POST https://api.dropcontact.com/v1/enrich/all \
-H "X-Access-Token: apiKey"
```
Remplacez `apiKey` par votre clé.
> **Attention:** Votre clé donne accès à votre compte et à vos crédits : ne la partagez pas et ne l'exposez pas côté navigateur ou dans un dépôt de code public.
## Guides associés
- [Démarrage rapide](https://developer.dropcontact.com/fr/quickstart/)
- [MCP](https://developer.dropcontact.com/fr/mcp/)
- [Gérer les erreurs](https://developer.dropcontact.com/fr/errors/)
---
# Enrichir un premier contact avec l'API Dropcontact
URL: https://developer.dropcontact.com/fr/quickstart/
L'enrichissement est asynchrone. Envoyez un contact avec `POST /v1/enrich/all`, conservez le `request_id` retourné, puis récupérez le résultat avec `GET /v1/enrich/all/{request_id}`. Ce guide fournit les exemples Python et cURL pour les deux étapes.
Ce guide enrichit un contact : Denis Cohen, de l'entreprise Dropcontact.
## Avant de commencer
Vous avez besoin d'un [compte Dropcontact](https://app.dropcontact.com/) et d'une clé API.
1. [Créez et copiez votre clé API](https://app.dropcontact.com/api) dans l'app.
2. Renseignez-la une fois en début de script, elle sera réutilisée dans toutes les requêtes :
```python
apiKey = "VOTRE_CLE_API"
```
Dans les exemples Shell, remplacez `VOTRE_CLE_API` par votre clé API.
## Étape 1 : envoyer le contact
**Python**
```python
r = requests.post(
"https://api.dropcontact.com/v1/enrich/all",
json={
"data": [
{
"first_name": "Denis",
"last_name": "Cohen",
"website": "dropcontact.com",
"email": "dc@dropcontact.io",
}
],
"siren": True,
},
headers={
"Content-Type": "application/json",
"X-Access-Token": apiKey,
},
)
print(r.json())
```
**Shell**
```shell
curl -X POST https://api.dropcontact.com/v1/enrich/all \
-H "X-Access-Token: VOTRE_CLE_API" \
-H "Content-Type: application/json" \
-d '{"data": [{"first_name": "Denis", "last_name": "Cohen", "website": "dropcontact.com", "email": "dc@dropcontact.io"}], "siren": true}'
```
Retrouvez tous les champs et options que vous pouvez envoyer dans [Contact envoyé](https://developer.dropcontact.com/fr/reference/input-record/).
L'API répond :
```json
{
"credits_left": 15279,
"request_id": "qzmxkpvlrtdnhwa",
"error": false,
"success": true
}
```
Conservez le `request_id` : il vous servira à l'étape 2.
## Étape 2 : récupérer le résultat
L'enrichissement prend quelques secondes. Remplacez `REQUEST_ID` par le `request_id` obtenu à l'étape 1, puis lancez la requête.
**Python**
```python
r = requests.get(
"https://api.dropcontact.com/v1/enrich/all/REQUEST_ID",
headers={"X-Access-Token": apiKey},
)
print(r.json())
```
**Shell**
```shell
curl https://api.dropcontact.com/v1/enrich/all/REQUEST_ID \
-H "X-Access-Token: VOTRE_CLE_API"
```
Si le résultat n'est pas encore prêt, l'API renvoie `"success": false`. Relancez la même requête 30 secondes plus tard.
```json
{
"error": false,
"reason": "Request not ready yet, try again in 30 seconds",
"success": false
}
```
Une fois le résultat prêt, l'API renvoie un objet par contact, dans l'ordre d'envoi :
```json
{
"data": [
{
"first_name": "Denis",
"last_name": "Cohen",
"full_name": "Denis Cohen",
"civility": "Monsieur",
"linkedin": "www.linkedin.com/in/cohendenis",
"location": "Paris, Île-de-France, France",
"email": [
{
"email": "dc@dropcontact.io",
"qualification": "nominatif@pro"
}
],
"company": "Dropcontact",
"website": "www.dropcontact.com",
"siret_address": "7 Place de l'Hôtel de Ville",
"siret_zip": "93600",
"siret_city": "Aulnay-sous-Bois",
"country": "France",
"company_linkedin": "www.linkedin.com/company/dropcontact-email-finder",
"phone": "+33 1 23 45 67 89",
"company_turnover": "",
"company_results": "",
"nb_employees": "10-19",
"siren": "823752647",
"siret": "82375264700029",
"naf5_code": "62.01Z",
"naf5_des": "Programmation informatique",
"vat": "FR11823752647",
"industry": "Technology, Information and Internet",
"employee_count": "15"
}
],
"credits_left": 15279,
"error": false,
"success": true
}
```
Le champ `qualification` indique le niveau de fiabilité de chaque email. Retrouvez tous les champs du résultat dans [Contact enrichi](https://developer.dropcontact.com/fr/reference/enriched-record/).
## Étapes suivantes
- [Webhooks](https://developer.dropcontact.com/fr/webhooks/) : recevez le résultat directement sur votre serveur, sans relancer la requête.
- [Erreurs](https://developer.dropcontact.com/fr/errors/) : que faire quand une requête échoue.
- [Crédits](https://developer.dropcontact.com/fr/credits/) : à quel moment un crédit est utilisé.
- [Référence de l'API](https://developer.dropcontact.com/fr/reference/) : tous les endpoints et tous les champs.
- Spécification OpenAPI : le contrat de l'API, pour générer un client ou le donner à un agent IA.
---
# Référence de l'API REST Dropcontact
URL: https://developer.dropcontact.com/fr/reference/
Consultez les endpoints de l'API REST Dropcontact : enrichissement, résultats, webhooks et crédits. Champs, formats de réponse et erreurs HTTP.
Cette référence décrit les endpoints pour enrichir vos contacts, récupérer les résultats, gérer votre webhook par défaut et consulter vos crédits. Tous utilisent l'URL de base `https://api.dropcontact.com` et une authentification par clé API.
La spécification OpenAPI de l'API Dropcontact décrit tous ses endpoints et champs.
## Enrichissement
- [Enrichir des contacts](https://developer.dropcontact.com/fr/reference/enrich-a-batch-of-records/)
- [Récupérer le résultat](https://developer.dropcontact.com/fr/reference/fetch-enrichment-results/)
## Webhooks
- [Définir l'URL de webhook par défaut](https://developer.dropcontact.com/fr/reference/set-the-default-webhook-callback-url/)
- [Consulter l'URL de webhook par défaut](https://developer.dropcontact.com/fr/reference/get-the-default-webhook-callback-url/)
- [Supprimer l'URL de webhook par défaut](https://developer.dropcontact.com/fr/reference/delete-the-default-webhook-callback-url/)
## Crédits
- [Consulter vos crédits](https://developer.dropcontact.com/fr/reference/get-credits/)
## Formats de données
- [Contact envoyé](https://developer.dropcontact.com/fr/reference/input-record/)
- [Contact enrichi](https://developer.dropcontact.com/fr/reference/enriched-record/)
---
# Enrichir un lot de contacts
URL: https://developer.dropcontact.com/fr/reference/enrich-a-batch-of-records/
`POST https://api.dropcontact.com/v1/enrich/all`
Envoyez jusqu'à 250 contacts avec `POST /v1/enrich/all`. La réponse contient un `request_id`, pas les résultats enrichis. Utilisez cet identifiant pour récupérer les résultats avec `GET /v1/enrich/all/{request_id}`, ou renseignez `custom_callback_url` pour les recevoir par webhook.
## Paramètres
| Nom | Emplacement | Type | Obligatoire | Description |
| --- | --- | --- | --- | --- |
| `hashedInputs` | query | boolean \| null | non | Ajoute le champ `hashedInputs` à la réponse. |
## Corps de la requête
Corps de la requête POST /v1/enrich/all.
| Champ | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `data` | liste de InputRecord | oui | Liste des contacts à enrichir, 250 maximum par requête. Retrouvez tous les champs possibles dans [Contact envoyé](/fr/reference/input-record/). |
| `data[].first_name` | string \| null | non | Prénom du contact. |
| `data[].last_name` | string \| null | non | Nom du contact. |
| `data[].full_name` | string \| null | non | Nom complet du contact. À utiliser quand le prénom et le nom ne sont pas fournis séparément. |
| `data[].civility` | string \| null | non | Civilité du contact (ex. M., Mme). |
| `data[].email` | string \| null | non | Adresse email du contact. Vérifiée et qualifiée pendant l'enrichissement. |
| `data[].linkedin` | string \| null | non | URL du profil LinkedIn du contact. |
| `data[].job` | string \| null | non | Intitulé de poste du contact. |
| `data[].job_function` | string \| null | non | Fonction du contact (grande catégorie du poste). |
| `data[].job_level` | string \| null | non | Niveau hiérarchique du contact (ex. manager, dirigeant). |
| `data[].mobile_phone` | string \| null | non | Numéro de téléphone mobile du contact. |
| `data[].location` | string \| null | non | Localisation du contact (ville, région ou pays). |
| `data[].company` | string \| null | non | Nom de l'entreprise. |
| `data[].website` | string \| null | non | URL du site web de l'entreprise. |
| `data[].siret_address` | string \| null | non | Adresse de l'entreprise (issue du registre SIRET français). |
| `data[].siret_zip` | string \| null | non | Code postal de l'entreprise (issu du registre SIRET français). |
| `data[].siret_city` | string \| null | non | Ville de l'entreprise (issue du registre SIRET français). |
| `data[].country` | string \| null | non | Pays de l'entreprise. |
| `data[].company_linkedin` | string \| null | non | URL LinkedIn de l'entreprise. |
| `data[].phone` | string \| null | non | Numéro de téléphone standard de l'entreprise. |
| `data[].company_turnover` | string \| null | non | Chiffre d'affaires annuel de l'entreprise. |
| `data[].company_results` | string \| null | non | Résultat annuel de l'entreprise. |
| `data[].nb_employees` | string \| null | non | Nombre de salariés. |
| `data[].num_siren` | string \| null | non | Code SIREN français (retourné sous le nom `siren` en sortie). |
| `data[].siret` | string \| null | non | Code SIRET français. |
| `data[].naf5_code` | string \| null | non | Code NAF/APE. |
| `data[].naf5_des` | string \| null | non | Libellé du code NAF/APE. |
| `data[].vat` | string \| null | non | Numéro de TVA. |
| `data[].industry` | string \| null | non | Secteur d'activité (LinkedIn). Disponible uniquement sur les plans Free et Growth. |
| `data[].employee_count` | string \| null | non | Nombre de salariés (LinkedIn). Disponible uniquement sur les plans Free et Growth. |
| `data[].custom_fields` | object \| null | non | Champs personnalisés libres, retournés tels quels dans le résultat enrichi. |
| `siren` | boolean | non | Ajoute le numéro SIREN et SIRET de l'entreprise au résultat. |
| `language` | string \| null | non | Langue du libellé de qualification des emails : `fr` ou `en`. Toute autre valeur donne `en`. |
| `custom_callback_url` | string \| null | non | URL de webhook propre à cette requête, appelée quand le résultat est prêt. Remplace l'URL de webhook par défaut pour cette requête. |
## Réponses
### 200 — Requête prise en compte
| Champ | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `error` | boolean | non | Indique si une erreur s'est produite. |
| `success` | boolean | non | Indique si la requête a été prise en compte. |
| `credits_left` | integer | oui | Nombre de crédits restants sur votre compte. |
| `request_id` | string | oui | Identifiant de la requête, à utiliser pour récupérer le résultat. |
| `hashedInputs` | liste de string \| null | non | Un jeton signé (JWT) par contact envoyé, dans l'ordre d'envoi. Chaque jeton contient les données d'entrée du contact. Présent seulement avec `hashedInputs=true`. |
| `data` | liste de PostRecord \| null | non | Contacts envoyés qui ont une erreur ou une alerte. Absent si aucun contact n'en a. |
| `data[].index` | integer | oui | |
| `data[].errors` | RecordErrors \| null | non | |
| `data[].warnings` | RecordWarnings \| null | non | |
### 400 — Requête mal formée
| Champ | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `error` | boolean | non | Indique si une erreur s'est produite. |
| `reason` | string | oui | Raison de l'échec de la requête, ou pourquoi le résultat n'est pas encore prêt. |
| `success` | boolean | non | Toujours false. |
| Champ | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `reason` | string | oui | |
| `status` | string | oui | |
| `data` | liste de PostRecord | oui | |
| `data[].index` | integer | oui | |
| `data[].errors` | RecordErrors \| null | non | |
| `data[].warnings` | RecordWarnings \| null | non | |
| `error` | boolean | non | |
| `success` | boolean | non | |
### 401 — Clé API absente ou invalide
| Champ | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `error` | boolean | non | Indique si une erreur s'est produite. |
| `reason` | string | oui | Raison de l'échec de la requête, ou pourquoi le résultat n'est pas encore prêt. |
| `success` | boolean | non | Toujours false. |
### 403 — Accès refusé
| Champ | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `error` | boolean | non | Indique si une erreur s'est produite. |
| `reason` | string | oui | Raison de l'échec de la requête, ou pourquoi le résultat n'est pas encore prêt. |
| `success` | boolean | non | Toujours false. |
### 422 — Erreur de validation
| Champ | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `detail` | liste de ValidationError | non | |
| `detail[].loc` | liste de string \| integer | oui | |
| `detail[].msg` | string | oui | |
| `detail[].type` | string | oui | |
### 429 — Trop de requêtes, ou erreur temporaire de notre côté : réessayez dans quelques secondes
| Champ | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `error` | boolean | non | Indique si une erreur s'est produite. |
| `reason` | string | oui | Raison de l'échec de la requête, ou pourquoi le résultat n'est pas encore prêt. |
| `success` | boolean | non | Toujours false. |
### 500 — Erreur côté Dropcontact
| Champ | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `detail` | string | oui | |
## Guides associés
- [Démarrage rapide](https://developer.dropcontact.com/fr/quickstart/)
- [Limites de requêtes](https://developer.dropcontact.com/fr/rate-limits/)
- [Webhooks](https://developer.dropcontact.com/fr/webhooks/)
---
# Récupérer les contacts enrichis par request_id
URL: https://developer.dropcontact.com/fr/reference/fetch-enrichment-results/
`GET https://api.dropcontact.com/v1/enrich/all/{request_id}`
Utilisez `GET /v1/enrich/all/{request_id}` pour récupérer un lot déjà envoyé. Vérifiez `success` même avec un code HTTP `200`. Si les résultats ne sont pas prêts, attendez 30 secondes avant de réessayer, ou utilisez `forceResults=true` pour obtenir les contacts déjà traités.
## Paramètres
| Nom | Emplacement | Type | Obligatoire | Description |
| --- | --- | --- | --- | --- |
| `request_id` | path | string | oui | |
| `forceResults` | query | boolean \| null | non | Retourne les contacts déjà enrichis sans attendre la fin du lot. Avec true, l'endpoint répond même si le traitement est encore en cours (au lieu de vous demander de réessayer) et ajoute un champ `status` (`ready` ou `in_progress`) qui indique si le lot est terminé. |
## Réponses
### 200 — Résultat prêt, ou pas encore prêt (`success: false` avec un `reason`)
| Champ | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `data` | liste de EnrichedRecord | oui | Les contacts enrichis, dans l'ordre de l'entrée. |
| `data[].first_name` | string \| null | non | Prénom du contact. |
| `data[].last_name` | string \| null | non | Nom du contact. |
| `data[].full_name` | string \| null | non | Nom complet du contact. À utiliser quand le prénom et le nom ne sont pas fournis séparément. |
| `data[].civility` | string \| null | non | Civilité du contact : `Monsieur` ou `Madame` avec `language: fr`, `Mr` ou `Mrs` sinon. |
| `data[].email` | liste de EmailResult \| null | non | Emails trouvés, avec leur qualification. |
| `data[].linkedin` | string \| null | non | URL du profil LinkedIn du contact. |
| `data[].job` | string \| null | non | Intitulé de poste du contact. |
| `data[].job_function` | string \| null | non | Fonction du contact (grande catégorie du poste). |
| `data[].job_level` | string \| null | non | Niveau hiérarchique du contact (ex. manager, dirigeant). |
| `data[].mobile_phone` | string \| null | non | Numéro de téléphone mobile du contact. |
| `data[].location` | string \| null | non | Localisation du contact (ville, région ou pays). |
| `data[].company` | string \| null | non | Nom de l'entreprise. |
| `data[].website` | string \| null | non | URL du site web de l'entreprise. |
| `data[].siret_address` | string \| null | non | Adresse de l'entreprise (issue du registre SIRET français). |
| `data[].siret_zip` | string \| null | non | Code postal de l'entreprise (issu du registre SIRET français). |
| `data[].siret_city` | string \| null | non | Ville de l'entreprise (issue du registre SIRET français). |
| `data[].country` | string \| null | non | Pays de l'entreprise. |
| `data[].company_linkedin` | string \| null | non | URL LinkedIn de l'entreprise. |
| `data[].phone` | string \| null | non | Numéro de téléphone standard de l'entreprise. |
| `data[].company_turnover` | string \| null | non | Chiffre d'affaires annuel de l'entreprise. |
| `data[].company_results` | string \| null | non | Résultat annuel de l'entreprise. |
| `data[].nb_employees` | string \| null | non | Nombre de salariés de l'entreprise, sous forme de tranche (ex. `10-19`). |
| `data[].siren` | string \| null | non | Code SIREN français (le champ en entrée est `num_siren`). |
| `data[].siret` | string \| null | non | Code SIRET français. |
| `data[].naf5_code` | string \| null | non | Code NAF/APE. |
| `data[].naf5_des` | string \| null | non | Libellé du code NAF/APE. |
| `data[].vat` | string \| null | non | Numéro de TVA. |
| `data[].industry` | string \| null | non | Secteur d'activité (LinkedIn). Disponible uniquement sur les plans Free et Growth. |
| `data[].employee_count` | string \| null | non | Nombre de profils LinkedIn liés à l'entreprise. Disponible uniquement sur les plans Free et Growth. |
| `data[].custom_fields` | object \| null | non | Champs personnalisés repris de l'entrée. |
| `data[].company_change` | string \| null | non | Nom de l'entreprise précédente quand un changement d'entreprise est détecté. |
| `data[].errors` | RecordErrors \| null | non | |
| `data[].warnings` | RecordWarnings \| null | non | |
| `data[].status` | string \| null | non | `ready` ou `in_progress`, uniquement avec forceResults=true. |
| `credits_left` | integer | oui | Crédits restants sur le compte. |
| `status` | string \| null | non | Statut global du lot (`ready`/`in_progress`), uniquement avec forceResults=true. |
| `error` | boolean | non | |
| `success` | boolean | non | |
| Champ | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `error` | boolean | non | Indique si une erreur s'est produite. |
| `reason` | string | oui | Raison de l'échec de la requête, ou pourquoi le résultat n'est pas encore prêt. |
| `success` | boolean | non | Toujours false. |
### 401 — Clé API absente ou invalide
| Champ | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `error` | boolean | non | Indique si une erreur s'est produite. |
| `reason` | string | oui | Raison de l'échec de la requête, ou pourquoi le résultat n'est pas encore prêt. |
| `success` | boolean | non | Toujours false. |
### 403 — Compte inconnu, ou `request_id` envoyé par un autre compte
| Champ | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `error` | boolean | non | Indique si une erreur s'est produite. |
| `reason` | string | oui | Raison de l'échec de la requête, ou pourquoi le résultat n'est pas encore prêt. |
| `success` | boolean | non | Toujours false. |
### 422 — Erreur de validation
| Champ | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `detail` | liste de ValidationError | non | |
| `detail[].loc` | liste de string \| integer | oui | |
| `detail[].msg` | string | oui | |
| `detail[].type` | string | oui | |
### 500 — Erreur interne du serveur
| Champ | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `detail` | string | oui | |
## Guides associés
- [Webhooks](https://developer.dropcontact.com/fr/webhooks/)
- [Gérer les erreurs](https://developer.dropcontact.com/fr/errors/)
- [Contact enrichi](https://developer.dropcontact.com/fr/reference/enriched-record/)
---
# Définir l'URL de webhook par défaut
URL: https://developer.dropcontact.com/fr/reference/set-the-default-webhook-callback-url/
`PUT https://api.dropcontact.com/v1/enrich/webhook`
Définissez l'URL de callback par défaut de votre compte avec `PUT /v1/enrich/webhook` et le champ `callback_url`. Dropcontact utilise cette URL lorsqu'une requête d'enrichissement ne contient pas de `custom_callback_url`.
## Corps de la requête
| Champ | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `callback_url` | string | oui | |
## Réponses
### 200 — Réponse réussie
| Champ | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `error` | boolean | non | Indique si une erreur s'est produite. |
| `success` | boolean | non | Indique si la requête a été prise en compte. |
| `callback_url` | string | oui | |
### 401 — Clé API absente ou invalide
| Champ | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `error` | boolean | non | Indique si une erreur s'est produite. |
| `reason` | string | oui | Raison de l'échec de la requête, ou pourquoi le résultat n'est pas encore prêt. |
| `success` | boolean | non | Toujours false. |
### 403 — Compte inconnu
| Champ | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `error` | boolean | non | Indique si une erreur s'est produite. |
| `reason` | string | oui | Raison de l'échec de la requête, ou pourquoi le résultat n'est pas encore prêt. |
| `success` | boolean | non | Toujours false. |
### 422 — Erreur de validation
| Champ | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `detail` | liste de ValidationError | non | |
| `detail[].loc` | liste de string \| integer | oui | |
| `detail[].msg` | string | oui | |
| `detail[].type` | string | oui | |
### 429 — Trop de requêtes, ou erreur temporaire de notre côté : réessayez dans quelques secondes
| Champ | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `error` | boolean | non | Indique si une erreur s'est produite. |
| `reason` | string | oui | Raison de l'échec de la requête, ou pourquoi le résultat n'est pas encore prêt. |
| `success` | boolean | non | Toujours false. |
### 500 — Erreur côté Dropcontact
| Champ | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `detail` | string | oui | |
Consultez le guide [Webhooks](https://developer.dropcontact.com/fr/webhooks/) pour recevoir les résultats sur votre serveur.
---
# Consulter l'URL de webhook par défaut
URL: https://developer.dropcontact.com/fr/reference/get-the-default-webhook-callback-url/
`GET https://api.dropcontact.com/v1/enrich/webhook`
Utilisez `GET /v1/enrich/webhook` pour consulter l'URL de callback par défaut de votre compte.
## Réponses
### 200 — Réponse réussie
| Champ | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `error` | boolean | non | Indique si une erreur s'est produite. |
| `success` | boolean | non | Indique si la requête a été prise en compte. |
| `callback_url` | string \| null | non | |
### 401 — Clé API absente ou invalide
| Champ | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `error` | boolean | non | Indique si une erreur s'est produite. |
| `reason` | string | oui | Raison de l'échec de la requête, ou pourquoi le résultat n'est pas encore prêt. |
| `success` | boolean | non | Toujours false. |
### 403 — Compte inconnu
| Champ | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `error` | boolean | non | Indique si une erreur s'est produite. |
| `reason` | string | oui | Raison de l'échec de la requête, ou pourquoi le résultat n'est pas encore prêt. |
| `success` | boolean | non | Toujours false. |
### 429 — Trop de requêtes, ou erreur temporaire de notre côté : réessayez dans quelques secondes
| Champ | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `error` | boolean | non | Indique si une erreur s'est produite. |
| `reason` | string | oui | Raison de l'échec de la requête, ou pourquoi le résultat n'est pas encore prêt. |
| `success` | boolean | non | Toujours false. |
### 500 — Erreur côté Dropcontact
| Champ | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `detail` | string | oui | |
Consultez le guide [Webhooks](https://developer.dropcontact.com/fr/webhooks/) pour recevoir les résultats sur votre serveur.
---
# Supprimer l'URL de webhook par défaut
URL: https://developer.dropcontact.com/fr/reference/delete-the-default-webhook-callback-url/
`DELETE https://api.dropcontact.com/v1/enrich/webhook`
Utilisez `DELETE /v1/enrich/webhook` pour supprimer l'URL de callback par défaut du compte. Les requêtes dotées de leur propre `custom_callback_url` continuent à déclencher des webhooks. En l'absence d'URL par défaut à supprimer, l'endpoint renvoie `404`.
## Réponses
### 200 — Réponse réussie
| Champ | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `detail` | string | oui | |
### 401 — Clé API absente ou invalide
| Champ | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `error` | boolean | non | Indique si une erreur s'est produite. |
| `reason` | string | oui | Raison de l'échec de la requête, ou pourquoi le résultat n'est pas encore prêt. |
| `success` | boolean | non | Toujours false. |
### 403 — Compte inconnu
| Champ | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `error` | boolean | non | Indique si une erreur s'est produite. |
| `reason` | string | oui | Raison de l'échec de la requête, ou pourquoi le résultat n'est pas encore prêt. |
| `success` | boolean | non | Toujours false. |
### 404 — Aucune URL de webhook par défaut à supprimer
| Champ | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `error` | boolean | non | Indique si une erreur s'est produite. |
| `reason` | string | oui | Raison de l'échec de la requête, ou pourquoi le résultat n'est pas encore prêt. |
| `success` | boolean | non | Toujours false. |
### 429 — Trop de requêtes, ou erreur temporaire de notre côté : réessayez dans quelques secondes
| Champ | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `error` | boolean | non | Indique si une erreur s'est produite. |
| `reason` | string | oui | Raison de l'échec de la requête, ou pourquoi le résultat n'est pas encore prêt. |
| `success` | boolean | non | Toujours false. |
### 500 — Erreur côté Dropcontact
| Champ | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `detail` | string | oui | |
Consultez le guide [Webhooks](https://developer.dropcontact.com/fr/webhooks/) pour recevoir les résultats sur votre serveur.
---
# Consulter le solde de crédits de l'API Dropcontact
URL: https://developer.dropcontact.com/fr/reference/get-credits/
`GET https://api.dropcontact.com/v1/account/credits`
Utilisez `GET /v1/account/credits` pour consulter vos crédits Dropcontact restants. La réponse renvoie le solde dans `credits`. Cet appel ne consomme aucun crédit ; les réponses d'enrichissement utilisent le champ distinct `credits_left`.
## Réponses
### 200 — Réponse réussie
| Champ | Type | Obligatoire | Description |
| --- | --- | --- | --- |
| `credits` | integer | oui | Nombre total de crédits restants sur votre compte, crédits gratuits compris. |
### 401 — Clé API absente ou invalide
## Guides associés
- [Politique de crédits](https://developer.dropcontact.com/fr/credits/)
- [Authentification](https://developer.dropcontact.com/fr/authentication/)
---
# Champs d'entrée d'un contact pour l'API Dropcontact
URL: https://developer.dropcontact.com/fr/reference/input-record/
Un contact envoyé à POST /enrich/all.
Un contact a besoin d'au moins un identifiant d'entreprise (company, website, company_linkedin, num_siren
ou siret), d'un email ou du profil LinkedIn de la personne. Un contact peut contenir jusqu'à 15 ko de données,
``custom_fields`` compris. Les clés non reconnues sont signalées par ``unexpected_field``.
| Champ | Type | Description |
| --- | --- | --- |
| `first_name` | string \| null | Prénom du contact. |
| `last_name` | string \| null | Nom du contact. |
| `full_name` | string \| null | Nom complet du contact. À utiliser quand le prénom et le nom ne sont pas fournis séparément. |
| `civility` | string \| null | Civilité du contact (ex. M., Mme). |
| `email` | string \| null | Adresse email du contact. Vérifiée et qualifiée pendant l'enrichissement. |
| `linkedin` | string \| null | URL du profil LinkedIn du contact. |
| `job` | string \| null | Intitulé de poste du contact. |
| `job_function` | string \| null | Fonction du contact (grande catégorie du poste). |
| `job_level` | string \| null | Niveau hiérarchique du contact (ex. manager, dirigeant). |
| `mobile_phone` | string \| null | Numéro de téléphone mobile du contact. |
| `location` | string \| null | Localisation du contact (ville, région ou pays). |
| `company` | string \| null | Nom de l'entreprise. |
| `website` | string \| null | URL du site web de l'entreprise. |
| `siret_address` | string \| null | Adresse de l'entreprise (issue du registre SIRET français). |
| `siret_zip` | string \| null | Code postal de l'entreprise (issu du registre SIRET français). |
| `siret_city` | string \| null | Ville de l'entreprise (issue du registre SIRET français). |
| `country` | string \| null | Pays de l'entreprise. |
| `company_linkedin` | string \| null | URL LinkedIn de l'entreprise. |
| `phone` | string \| null | Numéro de téléphone standard de l'entreprise. |
| `company_turnover` | string \| null | Chiffre d'affaires annuel de l'entreprise. |
| `company_results` | string \| null | Résultat annuel de l'entreprise. |
| `nb_employees` | string \| null | Nombre de salariés. |
| `num_siren` | string \| null | Code SIREN français (retourné sous le nom `siren` en sortie). |
| `siret` | string \| null | Code SIRET français. |
| `naf5_code` | string \| null | Code NAF/APE. |
| `naf5_des` | string \| null | Libellé du code NAF/APE. |
| `vat` | string \| null | Numéro de TVA. |
| `industry` | string \| null | Secteur d'activité (LinkedIn). Disponible uniquement sur les plans Free et Growth. |
| `employee_count` | string \| null | Nombre de salariés (LinkedIn). Disponible uniquement sur les plans Free et Growth. |
| `custom_fields` | object \| null | Champs personnalisés libres, retournés tels quels dans le résultat enrichi. |
## Guides associés
- [Enrichir des contacts](https://developer.dropcontact.com/fr/reference/enrich-a-batch-of-records/)
- [Contact enrichi](https://developer.dropcontact.com/fr/reference/enriched-record/)
---
# Champs du contact enrichi et qualification des emails
URL: https://developer.dropcontact.com/fr/reference/enriched-record/
Un contact enrichi retourné par GET /enrich/all/{request_id}.
Seules les informations trouvées sont présentes (rien n'est forcé à null). Attention, l'entrée et la sortie
diffèrent : ``num_siren`` est retourné sous le nom ``siren``, et ``email`` est une liste d'objets.
Dropcontact nettoie les données qu'il renvoie : le prénom et le nom reçoivent les bonnes majuscules (un nom
complet est découpé en prénom et nom), les URL LinkedIn deviennent ``www.linkedin.com/in/...``, le site web
est réduit à son domaine avec ``www.``, et le nom d'entreprise, le SIREN, le SIRET et le code NAF sont mis
dans un format standard.
| Champ | Type | Description |
| --- | --- | --- |
| `first_name` | string \| null | Prénom du contact. |
| `last_name` | string \| null | Nom du contact. |
| `full_name` | string \| null | Nom complet du contact. À utiliser quand le prénom et le nom ne sont pas fournis séparément. |
| `civility` | string \| null | Civilité du contact : `Monsieur` ou `Madame` avec `language: fr`, `Mr` ou `Mrs` sinon. |
| `email` | liste de EmailResult \| null | Emails trouvés, avec leur qualification. |
| `email[].email` | string | L'adresse email. |
| `email[].qualification` | string | Qualification au format `partielocale@domaine`, traduite selon la langue de la requête. Partie locale : nominatif/nominative, catch-all, generique/generic, Ne_Pas_Contacter/Do_Not_Contact, non_validé/non_validated, invalide/invalid. Domaine : pro, perso, school, jetable/disposable, domaine invalide/invalid domain. Exemple : `nominatif@pro`. |
| `linkedin` | string \| null | URL du profil LinkedIn du contact. |
| `job` | string \| null | Intitulé de poste du contact. |
| `job_function` | string \| null | Fonction du contact (grande catégorie du poste). |
| `job_level` | string \| null | Niveau hiérarchique du contact (ex. manager, dirigeant). |
| `mobile_phone` | string \| null | Numéro de téléphone mobile du contact. |
| `location` | string \| null | Localisation du contact (ville, région ou pays). |
| `company` | string \| null | Nom de l'entreprise. |
| `website` | string \| null | URL du site web de l'entreprise. |
| `siret_address` | string \| null | Adresse de l'entreprise (issue du registre SIRET français). |
| `siret_zip` | string \| null | Code postal de l'entreprise (issu du registre SIRET français). |
| `siret_city` | string \| null | Ville de l'entreprise (issue du registre SIRET français). |
| `country` | string \| null | Pays de l'entreprise. |
| `company_linkedin` | string \| null | URL LinkedIn de l'entreprise. |
| `phone` | string \| null | Numéro de téléphone standard de l'entreprise. |
| `company_turnover` | string \| null | Chiffre d'affaires annuel de l'entreprise. |
| `company_results` | string \| null | Résultat annuel de l'entreprise. |
| `nb_employees` | string \| null | Nombre de salariés de l'entreprise, sous forme de tranche (ex. `10-19`). |
| `siren` | string \| null | Code SIREN français (le champ en entrée est `num_siren`). |
| `siret` | string \| null | Code SIRET français. |
| `naf5_code` | string \| null | Code NAF/APE. |
| `naf5_des` | string \| null | Libellé du code NAF/APE. |
| `vat` | string \| null | Numéro de TVA. |
| `industry` | string \| null | Secteur d'activité (LinkedIn). Disponible uniquement sur les plans Free et Growth. |
| `employee_count` | string \| null | Nombre de profils LinkedIn liés à l'entreprise. Disponible uniquement sur les plans Free et Growth. |
| `custom_fields` | object \| null | Champs personnalisés repris de l'entrée. |
| `company_change` | string \| null | Nom de l'entreprise précédente quand un changement d'entreprise est détecté. |
| `errors` | RecordErrors \| null | |
| `errors.unexpected_field` | liste de string \| null | Clés envoyées qui ne sont pas reconnues. |
| `errors.only_contact_data` | boolean \| null | Vrai quand le contact a des données de personne, mais aucune donnée d'entreprise utilisable. |
| `warnings` | RecordWarnings \| null | |
| `warnings.empty_field` | liste de string \| null | Clés envoyées avec une valeur vide. |
| `warnings.only_organization_data` | boolean \| null | Vrai quand le contact a des données d'entreprise, mais aucune donnée de personne. |
| `status` | string \| null | `ready` ou `in_progress`, uniquement avec forceResults=true. |
## Guides associés
- [Récupérer le résultat](https://developer.dropcontact.com/fr/reference/fetch-enrichment-results/)
- [Gérer les erreurs](https://developer.dropcontact.com/fr/errors/)
---
# Recevoir les résultats d'enrichissement par webhook
URL: https://developer.dropcontact.com/fr/webhooks/
Dropcontact envoie les résultats d'enrichissement à votre URL de callback une fois le lot traité. Utilisez une `custom_callback_url` propre à la requête ou un webhook par défaut du compte. Répondez en moins de 5 secondes et utilisez `request_id` pour gérer les livraisons répétées.
## Qu'est-ce qu'un webhook ?
Un webhook est une URL de votre côté que Dropcontact appelle quand vos résultats sont prêts. Au lieu de demander plusieurs fois à l'API si vos données sont prêtes, vous nous donnez une URL et nous y envoyons les résultats dès que l'enrichissement est terminé.
Il y a deux façons de recevoir des webhooks :
1. La façon recommandée : avec une custom callback URL.
2. Avec une URL de webhook par défaut.
Vous ne pouvez avoir qu'une seule URL de webhook par défaut par compte. Si une `custom_callback_url` est indiquée dans la requête POST, elle est prioritaire sur l'URL par défaut.
Votre URL peut commencer par `http://` ou `https://`.
## Custom callback URL
Ajoutez le champ `custom_callback_url` dans le corps de votre requête [Enrichir un lot de contacts](https://developer.dropcontact.com/fr/reference/enrich-a-batch-of-records/). Une fois l'enrichissement terminé, les résultats sont envoyés à cette URL. C'est la façon la plus simple d'utiliser les webhooks, sans aucune configuration préalable.
**Python**
```python
import requests
r = requests.post(
"https://api.dropcontact.com/v1/enrich/all",
json={
"data": [
{
"first_name": "Denis",
"last_name": "Cohen",
"website": "dropcontact.com",
"email": "dc@dropcontact.io",
}
],
"siren": True,
"custom_callback_url": "https://votre-domaine.com/callback",
},
headers={
"Content-Type": "application/json",
"X-Access-Token": apiKey,
},
)
```
**Shell**
```shell
curl -X POST https://api.dropcontact.com/v1/enrich/all \
-H "X-Access-Token: VOTRE_CLE_API" \
-H "Content-Type: application/json" \
-d '{"data": [{"first_name": "Denis", "last_name": "Cohen", "website": "dropcontact.com", "email": "dc@dropcontact.io"}], "siren": true, "custom_callback_url": "https://votre-domaine.com/callback"}'
```
## URL de webhook par défaut
Vous pouvez, si vous le souhaitez, définir une URL de webhook par défaut, utilisée pour toutes vos requêtes d'enrichissement qui n'indiquent pas de `custom_callback_url`.
Gérez-la avec les endpoints dédiés :
- La définir ou la modifier : [Définir l'URL de webhook par défaut](https://developer.dropcontact.com/fr/reference/set-the-default-webhook-callback-url/)
- Voir sa valeur actuelle : [Consulter l'URL de webhook par défaut](https://developer.dropcontact.com/fr/reference/get-the-default-webhook-callback-url/)
- La supprimer : [Supprimer l'URL de webhook par défaut](https://developer.dropcontact.com/fr/reference/delete-the-default-webhook-callback-url/)
Après suppression, seules les requêtes avec une `custom_callback_url` déclenchent des webhooks.
## Recevoir un webhook
Dropcontact envoie une requête `POST` à votre URL une fois tous les contacts de la requête traités, même si vous avez déjà récupéré une partie des résultats avec `forceResults`. Son corps est une liste de webhooks au format JSON. Chaque webhook contient les champs suivants :
| Champ | Type | Description |
| --- | --- | --- |
| `id` | string | Identifiant unique du webhook. |
| `version` | integer | Version du format du webhook. Actuellement `1`. |
| `event_type` | string | Type d'événement. Toujours `enrich_api_result` pour les résultats d'enrichissement. |
| `occurred_at` | integer | Date de l'événement, en secondes depuis le 1er janvier 1970 (timestamp Unix). |
| `data` | object | Les résultats : `request_id` (l'ID de requête retourné par votre requête POST) et `data` (les contacts enrichis, au même format que [Récupérer les résultats d'enrichissement](https://developer.dropcontact.com/fr/reference/fetch-enrichment-results/)). |
```json
[
{
"id": "",
"version": 1,
"event_type": "enrich_api_result",
"occurred_at": 1623153600,
"data": {
"request_id": "",
"data": [{
"first_name": "Peter",
"last_name": "Jackson"
}]
}
}
]
```
> **Remarque:** Le champ `data` ne contient pas le champ `credits_left`. Utilisez l'endpoint [Consulter les crédits](https://developer.dropcontact.com/fr/reference/get-credits/) pour l'obtenir.
> **Remarque:** Une requête est toujours envoyée depuis l'une de ces adresses IP : `18.202.84.106`, `52.48.65.147` ou `54.74.141.102`.
> **Attention:** Nous ne garantissons pas l'ordre des webhooks. Utilisez le `request_id` pour associer chaque webhook à la requête correspondante. De plus, dans de rares cas, vous pouvez recevoir le même `request_id` dans plusieurs webhooks.
## Répondre à un webhook
Votre serveur doit répondre avec un code HTTP inférieur à `400` (par exemple `200`) en moins de 5 secondes. Un code de `400` ou plus, une absence de réponse en 5 secondes ou une erreur de connexion compte comme un échec.
En cas d'échec, nous réessayons :
1. D'abord, jusqu'à 4 essais en quelques secondes.
2. Ensuite, jusqu'à 10 nouveaux essais plus tard, en attendant un peu plus à chaque fois : 16 secondes, puis 32 secondes, et ainsi de suite, jusqu'à environ 2 heures 15 entre deux essais.
Après ces 14 essais, le webhook est abandonné. Vous pouvez toujours récupérer les résultats avec [Récupérer les résultats d'enrichissement](https://developer.dropcontact.com/fr/reference/fetch-enrichment-results/).
À cause de ces nouveaux essais, vous pouvez recevoir le même webhook plusieurs fois. Utilisez le `request_id` pour ignorer ceux que vous avez déjà traités.
---
# Comment les crédits de l'API Dropcontact sont consommés
URL: https://developer.dropcontact.com/fr/credits/
L'API Dropcontact distingue l'enrichissement d'email de la vérification d'une adresse envoyée. Les règles ci-dessous expliquent quand un crédit est consommé, quand il est restitué et où consulter votre solde.
## Consommation des crédits
Dropcontact fonctionne sur un modèle **Pay on Success** : vous ne payez que pour les résultats.
Un crédit est consommé dans deux cas :
- **Enrichissement d'email** : un crédit n'est consommé que si l'API retourne une adresse email vérifiée. La vérification est comprise dans ce même crédit. Le crédit est retiré à l'envoi de la requête, puis rendu automatiquement si aucun email n'est trouvé.
- **Vérification d'email seule** : si vous envoyez une adresse email dans le champ `"email"` de la requête, 1 crédit est consommé pour cette vérification. C'est 1 seul crédit, même si un autre email est trouvé, et il n'est pas rendu, même si l'email envoyé ressort invalide.
Si vous n'avez pas assez de crédits pour tous les contacts de la requête, elle est refusée en entier avec une erreur `403`. Voir [Erreurs](https://developer.dropcontact.com/fr/errors/).
## Option de report des crédits
Vos crédits non utilisés sont reportés sur la période de facturation suivante si cette option est activée sur votre abonnement actuel.
## Crédits restants
Le champ `credits_left` est retourné dans les réponses de [Enrichir des contacts](https://developer.dropcontact.com/fr/reference/enrich-a-batch-of-records/) et [Récupérer le résultat](https://developer.dropcontact.com/fr/reference/fetch-enrichment-results/). Il n'est pas dans les webhooks.
Pour consulter vos crédits à tout moment, utilisez l'endpoint [Consulter les crédits](https://developer.dropcontact.com/fr/reference/get-credits/). Il renvoie le même solde, dans le champ `credits`.
---
# Limites de requêtes et taille des lots de l'API Dropcontact
URL: https://developer.dropcontact.com/fr/rate-limits/
La limite de l'API Dropcontact est de 60 requêtes par seconde. Chaque requête d'enrichissement accepte jusqu'à 250 contacts, avec 15 ko de données maximum par contact. En cas d'erreur HTTP `429`, attendez avant de réessayer et augmentez le délai entre les tentatives.
Si vous envoyez trop de requêtes à l'API en peu de temps, les requêtes suivantes échoueront temporairement.
Si votre client est limité, vous recevrez des erreurs HTTP `429 Too Many Requests` en réponse à vos requêtes.
## Taille des lots et des contacts
- Jusqu'à 250 contacts par requête.
- Jusqu'à 15 ko de données par contact, `custom_fields` compris.
## Récupérer les résultats
Pour récupérer un résultat, renvoyez la même requête toutes les 30 secondes jusqu'à ce qu'il soit prêt. Pour faire moins d'appels, utilisez les [webhooks](https://developer.dropcontact.com/fr/webhooks/) : le résultat est envoyé à votre serveur dès qu'il est prêt.
Consultez [Erreurs](https://developer.dropcontact.com/fr/errors/) pour savoir quoi faire quand vous recevez une erreur `429`.
---
# Erreurs de l'API Dropcontact et solutions
URL: https://developer.dropcontact.com/fr/errors/
Pour gérer les erreurs de l'API Dropcontact, vérifiez le code HTTP et le corps de la réponse. Un code `200` peut contenir `success: false`. Lisez `reason` ou `detail` et distinguez les échecs de requête des erreurs et alertes propres à chaque contact.
## Vérifiez `success` pour les requêtes d'enrichissement
Pour les requêtes d'enrichissement, un code `200` ne veut pas toujours dire que votre requête a réussi. Lisez toujours le champ `success` de la réponse.
Tant que votre lot est en cours de traitement, `GET /v1/enrich/all/{request_id}` répond `200` avec `"success": false` et le message `Request not ready yet, try again in 30 seconds`. Il répond de la même façon quand le `request_id` est inconnu, ou quand nous avons un problème temporaire de notre côté.
Récupérez vos résultats dans les 30 jours : passé ce délai, ils peuvent ne plus être disponibles.
**Quoi faire :** attendez 30 secondes et réessayez. Pour ne pas interroger l'API en boucle, utilisez un [webhook](https://developer.dropcontact.com/fr/webhooks/), ou ajoutez `forceResults=true` pour récupérer les contacts déjà enrichis.
## Où lire le message d'erreur
La plupart des erreurs ressemblent à ceci. Le message est dans `reason` :
```json
{
"error": true,
"reason": "Too many records, you can only submit up to 250 records",
"success": false
}
```
Certaines erreurs (`404`, `422`, `500`, et les erreurs de `GET /v1/account/credits`) mettent le message dans `detail` :
```json
{
"detail": "Not Found"
}
```
Les messages sont toujours en anglais.
## Erreurs par code
### 400 Bad Request
Votre requête n'est pas valide. Retournée par `POST /v1/enrich/all`.
| Message | Quoi faire |
| --- | --- |
| `Missing data in JSON` | Envoyez au moins un contact dans `data`. |
| `Too many records, you can only submit up to 250 records` | Découpez vos contacts en lots de 250 maximum. |
| `Data size is too big, you can only submit up to 15 kB of data in a single record` | Allégez le contact. Des `custom_fields` trop gros en sont souvent la cause. Voir [Contact envoyé](https://developer.dropcontact.com/fr/reference/input-record/). |
| `Request contains invalid input` | Tous les contacts sont en erreur. Lisez `data[].errors` pour chaque contact. |
### 401 Unauthorized
Votre clé API est absente ou n'est pas valide. Retournée par tous les endpoints.
| Message | Quoi faire |
| --- | --- |
| `No api key received. Please set 'X-Access-Token' header with your api key as value.` ou `no-credentials` | Ajoutez l'en-tête `X-Access-Token` à votre requête. Voir [Authentification](https://developer.dropcontact.com/fr/authentication/). |
| `Unknown account` ou `invalid-api-key` | Votre clé API est fausse ou désactivée. Vérifiez-la dans l'[app Dropcontact](https://app.dropcontact.com/api). |
### 403 Forbidden
Votre clé API est valide, mais l'action est refusée.
| Message | Endpoints | Quoi faire |
| --- | --- | --- |
| `Sorry, you must contact the support to enable your API access!` | `POST /v1/enrich/all` | Contactez support@dropcontact.com pour activer l'accès à l'API. |
| `You submitted X valid items but only have Y credits left` | `POST /v1/enrich/all` | [Achetez des crédits](https://app.dropcontact.com/pricing), ou envoyez moins de contacts. Voir [Politique de crédits](https://developer.dropcontact.com/fr/credits/). |
| `Unknown account` | Tous sauf `GET /v1/account/credits` | Votre compte n'est pas encore prêt pour l'API. Connectez-vous une fois à l'[app Dropcontact](https://app.dropcontact.com), puis contactez le support si le problème continue. |
| `This request id was not sent by you` | `GET /v1/enrich/all/{request_id}` | Ce `request_id` appartient à un autre compte. Vérifiez que vous utilisez la bonne clé API. |
### 404 Not Found
| Message | Endpoints | Quoi faire |
| --- | --- | --- |
| `No webhook callback found` | `DELETE /v1/enrich/webhook` | Il n'y a pas d'URL de webhook par défaut à supprimer. Rien à faire. Voir [Webhooks](https://developer.dropcontact.com/fr/webhooks/). |
| `Not Found` | Tous | L'URL appelée n'existe pas. Vérifiez-la, par exemple `/v1/enrich/all` et non `/v1/all`. |
### 422 Validation Error
Le corps de la requête ou un paramètre n'a pas le bon format.
`detail` liste chaque champ en erreur. Corrigez votre requête à l'aide de la [référence de l'API](https://developer.dropcontact.com/fr/reference/).
C'est aussi le cas quand `custom_callback_url` ou l'URL de webhook par défaut n'est pas une URL valide, ou fait plus de 2 083 caractères. Voir [Webhooks](https://developer.dropcontact.com/fr/webhooks/).
### 429 Too Many Requests
Vous avez envoyé trop de requêtes en peu de temps (voir [Limites de requêtes](https://developer.dropcontact.com/fr/rate-limits/)), ou nous avons un problème temporaire de notre côté. Le message est `please retry in a few seconds`.
**Quoi faire :** attendez quelques secondes et réessayez, en laissant plus de temps entre chaque essai.
### 500 Internal Server Error
Une erreur s'est produite de notre côté, et nous sommes prévenus automatiquement. Le message est `An error occurred. Please retry later.`
**Quoi faire :** réessayez plus tard. Si le problème continue, contactez support@dropcontact.com.
### 502, 503, 504
Ces erreurs viennent de notre réseau, devant l'API : maintenance ou délai dépassé.
**Quoi faire :** réessayez plus tard.
## Erreurs et avertissements par contact
Certains problèmes ne concernent qu'un seul contact. La requête réussit quand même, et le problème est indiqué dans `data[].errors` ou `data[].warnings` pour ce contact.
| Clé | Type | Ce que ça veut dire | Quoi faire |
| --- | --- | --- | --- |
| `unexpected_field` | Erreur | Certains champs ne sont pas reconnus et sont ignorés. Le contact est quand même traité. | Corrigez les noms des champs indiqués. Voir [Contact envoyé](https://developer.dropcontact.com/fr/reference/input-record/). |
| `only_contact_data` | Erreur | Le contact a une personne, mais aucun identifiant d'entreprise (company, website, company_linkedin, num_siren, siret), aucun email et aucun profil LinkedIn de la personne. | Ajoutez au moins l'une de ces informations pour que nous puissions trouver l'email. Voir [Contact envoyé](https://developer.dropcontact.com/fr/reference/input-record/). |
| `empty_field` | Avertissement | Certains champs ont été envoyés vides. | Remplissez-les, ou ne les envoyez pas. |
| `only_organization_data` | Avertissement | Le contact a une entreprise, mais pas de personne : seule l'entreprise est enrichie. | Rien à faire si c'est voulu. |
Si tous les contacts de la requête ont une erreur, l'API répond à la place par une erreur `400`, pour les comptes qui ont l'option `API_ERROR`. Cette option est activée par défaut pour les comptes créés depuis le 1er juin 2026.
---
# Serveur MCP Dropcontact pour Claude, ChatGPT et Cursor
URL: https://developer.dropcontact.com/fr/mcp/
Le serveur MCP (Model Context Protocol) hébergé par Dropcontact donne aux assistants IA compatibles accès à l'enrichissement de contacts B2B, à la validation d'email et au solde de crédits. Connectez-vous à `https://mcp.dropcontact.com/mcp` via OAuth ou avec une clé API dans l'en-tête `Authorization: Bearer `. L'API REST utilise à la place l'en-tête `X-Access-Token` (voir [Authentification](https://developer.dropcontact.com/fr/authentication/)).
Vous pouvez vous connecter à notre serveur MCP nativement, comme avec Claude Desktop, ou via des clients compatibles comme Cursor, Windsurf, Visual Studio Code, et d'autres. Rien à installer : le serveur est hébergé par Dropcontact.
## Outils MCP disponibles
Il fournit des outils pour :
- Enrichir un contact à partir de :
- Prénom + nom + entreprise
- Nom complet + entreprise
- URL LinkedIn
- Valider une adresse email
- Consulter vos crédits restants
## Comment ça marche
Un enrichissement ou une validation d'email se fait en deux étapes :
1. Un premier outil envoie la demande et retourne un ID de requête. Cette étape consomme 1 crédit. Pour un enrichissement, le crédit est rendu si aucun email n'est trouvé. Une validation d'email consomme toujours 1 crédit, même si l'email est invalide (voir [Politique de crédits](https://developer.dropcontact.com/fr/credits/)).
2. Un second outil utilise cet identifiant pour récupérer le résultat. Cela prend en général 10 à 60 secondes, et jusqu'à 3 minutes.
Votre assistant IA enchaîne les deux étapes pour vous : il vous suffit de demander en langage courant.
## Exemples de prompts
- « Trouve l'email professionnel de Marie Dupont, qui travaille chez Dropcontact. »
- « Enrichis ce profil LinkedIn : https://www.linkedin.com/in/mariedupont »
- « contact@example.com est-elle une adresse email valide ? »
- « Combien de crédits Dropcontact me reste-t-il ? »
## Instructions d'installation
> **Remarque:** Les connexions MCP à distance sont encore récentes : la connexion peut échouer ou demander plusieurs essais. En cas de problème, redémarrez votre client, ou désactivez puis réactivez le serveur MCP Dropcontact.
Pour vous connecter au serveur MCP Dropcontact, utilisez la configuration suivante dans votre client compatible :
- URL du serveur : https://mcp.dropcontact.com/mcp
- Authentification : gérée automatiquement via OAuth (recommandé), mais d'autres méthodes existent (voir ci-dessous). Avec une clé API, utilisez la même clé que pour l'API, dans l'en-tête `Authorization: Bearer ` au lieu de `X-Access-Token`.
## Claude
### Particulier (Claude Desktop)
1. Allez dans Settings > Connectors et cliquez sur Add connector
2. Saisissez l'URL : https://mcp.dropcontact.com/mcp
3. Terminez la connexion OAuth dans le navigateur qui s'ouvre
### Team, Enterprise
1. Allez dans Settings > Integrations et cliquez sur Add more
2. Saisissez :
- Integration name : Dropcontact
- Integration URL : https://mcp.dropcontact.com/mcp
3. Activez les outils dans vos conversations
## Cursor
Cursor propose plusieurs méthodes de connexion. Choisissez celle qui correspond à votre installation :
1. Faites CTRL/CMD P et cherchez View: Open MCP Settings
2. Cliquez sur New MCP Server
3. Ajoutez la configuration Dropcontact au fichier de configuration json
### OAuth (recommandé)
L'authentification se fait automatiquement dans le navigateur.
```json title="~/.cursor/mcp.json"
{
"mcpServers": {
"dropcontact-oauth": {
"url": "https://mcp.dropcontact.com/mcp"
}
}
}
```
### Clé API (URL directe)
Remplacez `` par votre clé API Dropcontact, disponible dans l'[app Dropcontact](https://app.dropcontact.com/api).
```json title="~/.cursor/mcp.json"
{
"mcpServers": {
"dropcontact-token": {
"url": "https://mcp.dropcontact.com/mcp",
"headers": {
"Authorization": "Bearer "
}
}
}
}
```
### OAuth via npx mcp-remote
À utiliser si votre version de Cursor ne gère pas le MCP à distance nativement.
```json title="~/.cursor/mcp.json"
{
"mcpServers": {
"dropcontact-npx-oauth": {
"command": "npx",
"args": [
"mcp-remote",
"https://mcp.dropcontact.com/mcp"
]
}
}
}
```
### Clé API via npx mcp-remote
Remplacez `` par votre clé API Dropcontact, disponible dans l'[app Dropcontact](https://app.dropcontact.com/api).
```json title="~/.cursor/mcp.json"
{
"mcpServers": {
"dropcontact-npx-token": {
"command": "npx",
"args": [
"mcp-remote",
"https://mcp.dropcontact.com/mcp",
"--header",
"Authorization: Bearer ${API_TOKEN}"
],
"env": {
"API_TOKEN": ""
}
}
}
}
```
## ChatGPT
Les serveurs MCP s'ajoutent depuis l'application web et sont ensuite disponibles sur tous les clients ChatGPT.
1. Allez dans Settings > Apps > Create app
2. Saisissez :
- MCP Server URL : https://mcp.dropcontact.com/mcp
- Authentication : OAuth
3. Cliquez sur Create et terminez la connexion OAuth dans le navigateur qui s'ouvre
4. Une fois authentifié, les outils Dropcontact sont disponibles dans vos conversations
## Autres
De nombreux autres outils gèrent maintenant les serveurs MCP. Vous pouvez les configurer pour utiliser le serveur MCP de Dropcontact avec les réglages suivants :
### OAuth (recommandé)
L'authentification se fait automatiquement dans le navigateur.
```json
{
"mcpServers": {
"dropcontact-oauth": {
"url": "https://mcp.dropcontact.com/mcp"
}
}
}
```
### Clé API (URL directe)
Remplacez `` par votre clé API Dropcontact, disponible dans l'[app Dropcontact](https://app.dropcontact.com/api).
```json
{
"mcpServers": {
"dropcontact-token": {
"url": "https://mcp.dropcontact.com/mcp",
"headers": {
"Authorization": "Bearer "
}
}
}
}
```
### OAuth via npx mcp-remote
À utiliser si votre client ne gère pas le MCP à distance nativement.
```json
{
"mcpServers": {
"dropcontact-npx-oauth": {
"command": "npx",
"args": [
"mcp-remote",
"https://mcp.dropcontact.com/mcp"
]
}
}
}
```
### Clé API via npx mcp-remote
Remplacez `` par votre clé API Dropcontact, disponible dans l'[app Dropcontact](https://app.dropcontact.com/api).
```json
{
"mcpServers": {
"dropcontact-npx-token": {
"command": "npx",
"args": [
"mcp-remote",
"https://mcp.dropcontact.com/mcp",
"--header",
"Authorization: Bearer ${API_TOKEN}"
],
"env": {
"API_TOKEN": ""
}
}
}
}
```
## Dépannage
| Problème ou message | Quoi faire |
| --- | --- |
| La connexion échoue ou la fenêtre OAuth ne s'ouvre pas | Redémarrez votre client, ou désactivez puis réactivez le serveur MCP Dropcontact, puis reconnectez-vous. |
| `The Dropcontact session has ended` | Reconnectez le connecteur Dropcontact dans votre client et identifiez-vous à nouveau. |
| `Dropcontact rejected this API key` | Vérifiez que votre clé API est toujours active dans l'[app Dropcontact](https://app.dropcontact.com/api). |
| `Your Dropcontact account is not yet set up for MCP` | Connectez-vous une fois à l'[app Dropcontact](https://app.dropcontact.com) pour activer votre compte, puis réessayez. |
| `You have no remaining enrichment credits` | [Ajoutez des crédits](https://app.dropcontact.com/pricing) à votre compte. S'il vous reste des crédits, contactez support@dropcontact.com : votre accès à l'API n'est peut-être pas activé. |
| `Timeout while waiting for enrich contact response` | Le résultat n'était pas prêt après 3 minutes. Demandez à votre assistant IA de récupérer à nouveau le résultat avec le même ID de requête, ou récupérez-le via l'API une fois le traitement terminé. Aucun crédit supplémentaire n'est consommé. |
| `Dropcontact could not authenticate this request right now` | Réessayez dans un moment. |
| `Too many requests. Please wait a moment before trying again.` | Attendez quelques secondes et réessayez. |
| `Dropcontact request failed`, `Dropcontact could not process this request` ou `Dropcontact enrich request failed` | Une erreur s'est produite de notre côté. Réessayez plus tard. Si le problème continue, contactez support@dropcontact.com. |
| `Failed to retrieve credits` | Réessayez plus tard. |
Toujours bloqué ? Contactez-nous à support@dropcontact.com.
---
# Enrichir des contacts Google Sheets avec Dropcontact
URL: https://developer.dropcontact.com/fr/google-sheets/
L'add-on Google Sheets Dropcontact enrichit vos contacts dans un tableur sans écrire de code. Installez-le depuis Google Workspace Marketplace, connectez votre compte Google ou votre clé API, puis traitez jusqu'à 10 000 lignes avec vos crédits Dropcontact.
## Qu'est-ce que l'add-on Google Sheets ?
L'add-on Dropcontact permet d'enrichir les contacts d'un fichier Google Sheets sans écrire de code. Il lit les lignes de votre feuille, les envoie à Dropcontact, puis écrit les résultats dans votre fichier.
Il trouve ou vérifie :
- Les adresses email professionnelles
- Les numéros de téléphone
- Les profils LinkedIn
- Les informations sur l'entreprise (site web, SIREN/SIRET, adresse, effectif…)
L'add-on reconnaît vos colonnes automatiquement (prénom, nom, entreprise, email, LinkedIn…). Vous choisissez où écrire les résultats : dans les colonnes existantes, dans de nouvelles colonnes ou dans une nouvelle feuille. Il peut enrichir jusqu'à 10 000 lignes à la fois, et utilise les crédits de votre compte Dropcontact, comme expliqué dans la [Politique de crédits](https://developer.dropcontact.com/fr/credits/).
## Installer l'add-on
1. Ouvrez la [page Dropcontact sur le Google Workspace Marketplace](https://workspace.google.com/marketplace/app/dropcontact/557472153363) et cliquez sur **Installer**.
2. Dans un fichier Google Sheets, allez dans **Extensions > Dropcontact > Open Sidebar**.
## Se connecter à votre compte Dropcontact
Vous avez besoin d'un compte Dropcontact. Si vous n'en avez pas encore, [créez-en un gratuitement](https://app.dropcontact.com/signup).
Dans le panneau latéral, ouvrez **Authentification** et choisissez l'une des deux méthodes.
### Avec votre compte Google (recommandé)
Utilisez cette méthode si vous vous connectez à Dropcontact avec le même compte Google que celui que vous utilisez dans Google Sheets.
1. Sélectionnez l'onglet **Compte Google**.
2. Cliquez sur **Vérifier mon compte**.
3. L'add-on trouve votre compte Dropcontact et affiche **Compte trouvé !**
Si vous voyez `Aucun compte Dropcontact lié à ce compte Google.`, votre compte Google n'est pas lié à un compte Dropcontact. Créez un compte avec ce compte Google, ou utilisez la méthode par clé API ci-dessous.
### Avec votre clé API
Utilisez cette méthode si votre compte Dropcontact utilise une autre adresse email.
1. Copiez votre clé API depuis l'[app Dropcontact](https://app.dropcontact.com/api).
2. Dans le panneau latéral, sélectionnez l'onglet **Token API**.
3. Collez votre clé API et cliquez sur **Enregistrer et tester**.
4. L'add-on affiche **Token sauvegardé et validé**.
Une fois connecté, cliquez sur **Commencer l'enrichissement**.