Enrich a lead
Look up the email or the phone number of a lead.
Starts a lookup for the email, the phone number, or both, of one lead. The lookup runs in the background: the answer only says what was started. Read the result later with Get a lead or Query leads.
Route
Access modes
Use a workspace API key. The workspace is inferred from the key.
Authorization: Bearer sk_live_...Path parameters
| Parameter | Type | Description |
|---|---|---|
| lead_id | integer | ID of the lead. |
Body parameters
| Parameter | Type | Description |
|---|---|---|
| fields | array of strings | What to look up: email, phone, or both. At least one is required and a value cannot be repeated. |
Example request
curl -X POST "https://api.getsillage.com/api/v3/leads/123/enrich" \
-H "Authorization: Bearer $SILLAGE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"fields": ["email", "phone"]
}'Success response
Status: 202 Accepted
{
"data": {
"id": 123,
"email": { "status": "pending" },
"phone": { "status": "completed" }
}
}Response fields
| Field | Type | Description |
|---|---|---|
| data.id | integer | ID of the lead. |
| data.email | object or null | Always present. null when email was not requested; otherwise its status is pending or completed. |
| data.phone | object or null | Always present. null when phone was not requested; otherwise its status is pending or completed. |
A field is completed at once when the lead already has that value, or when Sillage could fill it in without a new lookup. A field is pending when a lookup is running, including one you started earlier. Sending the same request again never starts a second lookup nor takes more credits while a lookup is pending or done. A field whose last lookup failed can be asked for again: that starts a new lookup.
Credits
Credits for the enrichment are taken from your workspace balance when you start it. See Credit balance for what you can spend. Each enrichment is billed at your workspace's current price and shown in Credit usage with scope email_enrichment or phone_enrichment.
Credits are only taken for the lookups that find something. When a lookup finds nothing, the credits are given back. When you ask for both fields, the request is all or nothing: if your balance cannot cover both, nothing is started or charged and the answer is 402. Read GET /v3/credits/balance to see what you can spend. It is also all or nothing if a lookup cannot be started for one field: nothing is charged for any field of the request.
Check the result
Poll Get a lead (or Query leads for many leads at once) until enrichment_status leaves pending; some lookups can take hours. The email and phone fields hold the values found, and enrichment_status says where each lookup stands. pending means the lookup is still running. completed means the value was found and is on the lead. failed means nothing was found or the lookup ended in an error; nothing is charged. Stop polling once the field is no longer pending.
Errors
| Status | Meaning |
|---|---|
| 401 | The API key is missing or invalid. |
| 402 | Code insufficient_credits, title "Insufficient credits". detail reads "Your credit balance cannot pay for these lookups. Add credits, then try again. Nothing was started." Read your balance with Credit balance. |
| 404 | The lead does not exist. |
| 422 | The lead_id is not valid, fields is missing, empty, repeats a value or holds a value other than email or phone, or the body contains a key other than fields. |
| 429 | Rate limit exceeded. |
| 500 | An unexpected server error occurred. |
Error responses use RFC 9457 problem documents with Content-Type: application/problem+json. type is always about:blank; code tells one problem from another, detail says what went wrong this time, and errors names the field at fault.