Primavera API

Rules for agents

• Authenticate with Authorization: Bearer $PRIMAVERA_API_KEY. Never print, log or repeat the key.
• For any target, call POST /categories/suggest first (100 credits). Never invent category ids.
• Lookups, counts, figures, previews and estimates are free: use them before paying.
• Every paid call needs an Idempotency-Key header (a new UUID per operation) and maxCredits in the JSON body. Send the cost of the estimate as maxCredits.
• On a refusal, read error.code and do what error.hint says. Never retry in a loop; wait for Retry-After.
• When a figure comes with exact: false, say "≈ N", never N.
• Email addresses, phone numbers and websites only come with a list: previews show whether they exist, not what they are.
• Deleting a list is final and refunds nothing: ask the user first.
• Some text fields come from the product in French (selection.message, question, reasons, area notes, the fair use sentence): translate them for the user when needed.

Authentication

The account owner creates a key at https://primaverapp.com/dashboard/api. The key reads pv_live_ followed by 32 letters and digits; it is shown once, at creation. An account has at most 5 active keys; a revoked key is refused at once. A key can carry a monthly credit cap: a paid call whose maxCredits would exceed what the cap still allows this month is refused with key_budget_exceeded.

Keep the key in the environment variable PRIMAVERA_API_KEY and send it in the Authorization header of every call:

curl -s https://primaverapp.com/api/v1/account \
  -H "Authorization: Bearer $PRIMAVERA_API_KEY"

Bodies are JSON (Content-Type: application/json, 1 MB at most), field names in camelCase. Responses are JSON and never cached.

Access

The API is open to accounts with an active Pro or Agency subscription (named starter and agency in GET /account; the legacy pro plan too). A trial, free or cancelled account gets 403 plan_required: stop and tell the user that the API needs a Pro or Agency subscription (https://primaverapp.com/dashboard/billing). An account on hold gets 403 account_frozen: stop and tell the user to contact Primavera support.

The API spends the same balance as the web app, at the same prices: what the API spends, the app shows, and the other way round.

Limits

Search reads count the catalog queries a call makes: /search/count 1, /search/metrics 5, /search/preview 1, /search/estimate 1 (2 with excludeDelivered: false). Lookups: /areas 1 or more (a written place can need several), /categories 1 (2 outside France). Reuse the figures you already have instead of counting the same search twice.

Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (Unix time, seconds). Over a limit: 429 rate_limited with a Retry-After header in seconds; wait that long, then send the same request once. GET /account returns the limits of the account (rateLimits).

A list holds at most 50,000 rows, and one list export runs at a time per account; at most three jobs run at a time on the lists of an account; a preview returns at most 25 rows.

Errors

Every refusal has the same shape:

{
  "error": {
    "code": "target_unresolved",
    "message": "categories.request is set but no category ids, groups or concepts are given: the search would match every place of the area.",
    "hint": "Call POST /categories/suggest with this request and use the search it returns. To search every category on purpose, send no categories at all."
  }
}

• code is stable: branch on it.
• message says what went wrong.
• hint says what to do next, in one sentence written for you: follow it.
• details (sometimes): one entry per invalid field (path, message) for invalid_request; the question and its options for clarification_needed.

A refusal that comes from the product keeps the product's code (for example too_many_active_jobs, not_in_france); its hint still says what to do.

Money: paid calls and prices

Prices

A place already delivered to the account is never billed again: searches leave such places out by default (excludeDelivered: true). Deleting a list or removing rows refunds nothing.

Paid calls

Every paid call needs:

• an Idempotency-Key header holding a UUID: a new one per operation (uuidgen, or python3 -c "import uuid; print(uuid.uuid4())"). Keep it until the operation succeeds;
• maxCredits in the JSON body: an integer from 0 to 1,000,000,000, the most credits the call may spend. It is never exceeded. Send the cost returned by the matching estimate. Missing: 400 max_credits_required, nothing runs.

Retrying is safe:

• the same request with the same Idempotency-Key returns the saved result (header Idempotent-Replayed: true) and charges nothing more: after a timeout or a lost response, always retry with the SAME key;
• the same key with a different request: 409 idempotency_conflict;
• the same request still running: 409 idempotency_conflict with Retry-After: 5; a request interrupted on our side is taken up again after 10 minutes;
• a refused or failed call can be sent again with the same key, except a refunded suggestion: its hint asks for a NEW key.

Paid responses carry credits: bound (your maxCredits), charged (what the call debited: 0 on a refund; on a replay, flagged by the header Idempotent-Replayed: true, the body is the original response, so charged repeats what the ORIGINAL call debited, and nothing is debited again) and balance (after the call). Not enough credits: 402 insufficient_credits, nothing is charged.

The search object

POST /categories/suggest returns a ready search in its search field. Send it as is to /search/* and POST /lists; edit it only to narrow it.

{
  "country": "fr",
  "categories": {
    "request": "independent car repair shops",
    "groups": [
      { "label": "Garages automobiles", "ids": [9592, 9593] },
      { "label": "Carrosserie et pneus", "ids": [9601] }
    ]
  },
  "excludedCategoryIds": [],
  "area": { "type": "commune", "codes": ["69123"] },
  "filters": { "excludeServicePoints": true, "networks": { "mode": "exclude" } },
  "sort": "default",
  "excludeDelivered": true
}

Two refusals protect you from paying for the wrong places:

• categories.request without any category (no groups, no ids): 400 target_unresolved. Call /categories/suggest.
• Exclusions that remove every category of the target: 400 target_excluded.

A search with no categories at all means every category of the area: send that only on purpose.

Filters

Walkthrough

The full path, from a target to a downloaded list. The examples use curl and jq; responses are shortened.

1. Check the account

curl -s https://primaverapp.com/api/v1/account \
  -H "Authorization: Bearer $PRIMAVERA_API_KEY"

{
  "plan": "starter",
  "planName": "Pro",
  "credits": { "balance": 9400 },
  "exportsIncluded": false,
  "rateLimits": { "requestsPerMinute": 60, "suggestionsPerHour": 30, "searchReadsPerHour": 2500, "lookupsPerHour": 3000 }
}

2. Find the area

curl -s -G https://primaverapp.com/api/v1/areas \
  -H "Authorization: Bearer $PRIMAVERA_API_KEY" \
  --data-urlencode "q=Lyon"

{
  "areas": [
    { "level": "commune", "code": "69123", "name": "Lyon", "country": "fr", "population": 522250, "parentCode": "69", "area": { "type": "commune", "codes": ["69123"] } }
  ],
  "usual": null,
  "match": { "status": "resolved", "area": { "type": "commune", "codes": ["69123"] }, "label": "Lyon", "country": "fr" }
}

Use match.area when match.status is resolved; when it is ambiguous or elsewhere, ask the user which candidate they mean.

3. Turn the target into categories (100 credits)

KEY=$(uuidgen)
curl -s https://primaverapp.com/api/v1/categories/suggest \
  -H "Authorization: Bearer $PRIMAVERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -d '{"request": "independent car repair shops", "area": {"type": "commune", "codes": ["69123"]}, "maxCredits": 100}' > suggestion.json
jq '.search' suggestion.json > search.json

{
  "selection": {
    "groups": [
      { "label": "Garages automobiles", "kind": "coeur", "ids": [9592, 9593], "count": 412, "exact": true }
    ],
    "excluded": [{ "id": 9610, "label": "Concessionnaire automobile", "reason": "vend des véhicules" }],
    "cannotKnow": [],
    "message": "J'ai retenu les garages automobiles, sans les enseignes.",
    "question": null,
    "addable": [{ "label": "Carrosserie", "ids": [9601], "reason": null, "count": 58, "exact": true }]
  },
  "search": { "country": "fr", "categories": { "request": "independent car repair shops", "groups": [ … ] }, "area": { … }, "filters": { … }, "excludeDelivered": true },
  "count": { "count": 412, "exact": true },
  "networksExcluded": true,
  "credits": { "bound": 100, "charged": 100, "balance": 9300 }
}

Tell the user what was chosen (selection.message, groups and their counts). addable lists close categories left out: add one to search.categories.groups if the user wants it. If the response was lost, send the same request with the same $KEY: you get the saved selection without paying twice.

A request too vague to choose categories is refused and refunded:

{
  "error": {
    "code": "clarification_needed",
    "message": "The request needs a clarification before categories can be chosen: \"Quels laboratoires ?\" (options: Laboratoires d'analyses médicales | Laboratoires de recherche). You were not charged.",
    "hint": "Ask the user this question (details: \"question\" and \"question.options\"), then send the request again, made more precise with the answer, under a NEW Idempotency-Key.",
    "details": [
      { "path": "question", "message": "Quels laboratoires ?" },
      { "path": "question.options.0", "message": "Laboratoires d'analyses médicales" },
      { "path": "question.options.1", "message": "Laboratoires de recherche" }
    ]
  }
}

4. Figures and estimate (free)

curl -s https://primaverapp.com/api/v1/search/metrics \
  -H "Authorization: Bearer $PRIMAVERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --slurpfile s search.json '{search: $s[0]}')"

curl -s https://primaverapp.com/api/v1/search/estimate \
  -H "Authorization: Bearer $PRIMAVERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --slurpfile s search.json '{search: $s[0], rows: 300}')"

{ "total": { "count": 412, "exact": true }, "withEmail": { "count": 236, "exact": true }, "withPhone": { "count": 398, "exact": true }, "withWebsite": { "count": 301, "exact": true }, "emailCandidates": { "count": 41, "exact": true }, "estimatedEmails": { "count": 248, "exact": true, "rate": 0.3 }, "excludedDelivered": 0 }

{ "kind": "export", "rows": 300, "available": 412, "exact": true, "cost": 300, "billable": 412, "credits": 9300, "after": 9000, "enough": true, "emailOnly": false, "included": false }

cost is the most the list can cost: send it as maxCredits. With "withEmail": true, the estimate is that of a list "with email" (rows are email addresses, the verification is included in cost). In a rarely searched area, the estimate has kind: "zone": figures are approximate (say "≈"), and the list fills after its creation.

5. Preview (free)

curl -s https://primaverapp.com/api/v1/search/preview \
  -H "Authorization: Bearer $PRIMAVERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --slurpfile s search.json '{search: $s[0], limit: 10}')"

{ "rows": [ { "id": 18234567, "name": "Garage du Rhône", "city": "Lyon", "postalCode": "69007", "category": "Garage automobile", "rating": 4.6, "reviews": 128, "website": true, "email": true, "phone": true } ], "limit": 10, "offset": 0 }

6. Create the list (paid)

LIST_KEY=$(uuidgen)
curl -s https://primaverapp.com/api/v1/lists \
  -H "Authorization: Bearer $PRIMAVERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $LIST_KEY" \
  -d "$(jq -n --slurpfile s search.json '{name: "Independent garages, Lyon", search: $s[0], rows: 300, maxCredits: 300}')"

{
  "list": { "id": "8c1f…", "name": "Independent garages, Lyon", "status": "ready", "rows": 300, "requestedRows": 300, "creditsSpent": 296, "withEmail": false, "warning": null, "error": null },
  "alreadyDelivered": 4,
  "credits": { "bound": 300, "charged": 296, "balance": 9004 }
}

• 201: the list is ready. 202: it goes on filling in the background (more than 10,000 rows, guessed addresses of a list "with email", rarely searched area): follow it (step 7), never send it again under a new key.
• alreadyDelivered: places of the list already delivered to the account before, not billed again.
• After a timeout or a lost response, send the very same request with the same $LIST_KEY: you get either the original response (header Idempotent-Replayed: true, same charged as the first time), or, if that response was not saved, the list as it is now with replayed: true and charged: 0. In both cases nothing is debited again.
• "withEmail": true: a list "with email" (rows is a number of addresses; found addresses first, then guessed and checked ones). maxCredits must cover the estimate made with "withEmail": true (export, guessed addresses and verification), otherwise 400 max_credits_too_low.
• "verifyEmails": true: the addresses the list delivers are verified (1 credit per address, reserved at creation, unused credits returned). Send maxCredits ≥ the estimate cost + rows. Up to 10,000 rows, not in a rarely searched area; otherwise verify later (step 10).
• Rarely searched area (estimate kind: "zone"): send rows, or "wholeArea": true for the whole area, and maxCredits ≥ zoneEstimate.creditCap. The answer is 202 with fill: the list fills while the area is updated (minutes to hours).

7. Follow the list

curl -s https://primaverapp.com/api/v1/lists/$LIST_ID \
  -H "Authorization: Bearer $PRIMAVERA_API_KEY"

{
  "list": {
    "id": "8c1f…", "status": "ready", "rows": 300,
    "progress": { "export": null, "fill": null, "emailGuess": null, "emailCheck": { "mode": "on_request", "unverified": 212, "running": null } },
    "contents": { "website": 221, "email": 212, "phone": 290, "executive": 0, "emailVerdicts": { "deliverable": 0, "risky": 0, "undeliverable": 0, "noResult": 0, "unchecked": 212 } },
    "jobs": []
  }
}

LIST_ID is list.id of the creation response. Poll every 10 seconds or more while status is creating or filling: progress tells how far the export, the filling, the guessed addresses and the email verification went. progress.emailCheck.unverified is what verifying the addresses would cost (step 10).

8. Read the rows (free)

curl -s -G https://primaverapp.com/api/v1/lists/$LIST_ID/items \
  -H "Authorization: Bearer $PRIMAVERA_API_KEY" \
  --data-urlencode "limit=1000"

{ "columns": [ { "key": "name", "label": "Nom" }, { "key": "email", "label": "Email" }, { "key": "email_status", "label": "Statut email" } ], "items": [ { "placeId": 18234567, "name": "Garage du Rhône", "email": "contact@garagedurhone.fr", "email_status": "non vérifiée" } ], "nextCursor": "…" }

Send cursor = nextCursor to read the next page, until nextCursor is null; columns=name,email,phone keeps only these columns. Labels and values are those of the CSV file, in French.

9. Download a file (free)

curl -s https://primaverapp.com/api/v1/lists/$LIST_ID/files \
  -H "Authorization: Bearer $PRIMAVERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"format": "xlsx"}'

curl -s https://primaverapp.com/api/v1/lists/$LIST_ID/files/$FILE_ID \
  -H "Authorization: Bearer $PRIMAVERA_API_KEY"

FILE_ID is file.id of the first response. Poll the file until its status is ready: url is then a download link valid 120 seconds (call again for a new one). A file stays available 7 days; stale means: prepare it again.

10. Enrich the list (paid)

curl -s https://primaverapp.com/api/v1/lists/$LIST_ID/jobs/estimate \
  -H "Authorization: Bearer $PRIMAVERA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tool": "summary"}'

JOB_KEY=$(uuidgen)
curl -s https://primaverapp.com/api/v1/lists/$LIST_ID/jobs \
  -H "Authorization: Bearer $PRIMAVERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $JOB_KEY" \
  -d '{"tool": "summary", "maxCredits": 300}'

curl -s https://primaverapp.com/api/v1/jobs/$JOB_ID \
  -H "Authorization: Bearer $PRIMAVERA_API_KEY"

The estimate gives estimate.maxCredits: send it as maxCredits. The job answers 202 and runs in the background; each place is billed on its result, never beyond maxCredits. JOB_ID is job.id of that answer; poll GET /jobs/{id} until status is done, then read the results in the rows (step 8). Tools: executives (France only), summary, question (with question), filter (with criterion; GET /jobs/{id} then gives verdicts, and a question with scope: { "kind": "undetermined", "jobId": … } reads the websites of the undetermined places).

To verify the email addresses of a ready list:

curl -s https://primaverapp.com/api/v1/lists/$LIST_ID/email-check \
  -H "Authorization: Bearer $PRIMAVERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"maxCredits": 212}'

maxCredits is the number of addresses you accept to verify: progress.emailCheck.unverified of step 7. 1 credit per address that gets a verdict; the rest is returned when the check ends. Verdicts land in email_status (délivrable, risqué, indélivrable, sans résultat) and in contents.emailVerdicts.

Reference

Each route with its inputs, its output and its own refusals. The common refusals apply to every route; every paid route can also answer idempotency_key_required, max_credits_required, idempotency_conflict, key_budget_exceeded, insufficient_credits. Paths are relative to the base URL.

Account

Plan, balance, fair use and rate limits.

GET /account

Plan, credit balance, fair use and rate limits. Free. Read it first: the balance tells what the account can afford; Agency exports new places without credits under the fair use limit of each country.

Free.

Response 200:

Suggestion

Turn a target into categories: the entry point of every search (100 credits).

POST /categories/suggest

Turn a target into categories (entry point of every search). The entry point for ANY target: call it before choosing categories, with the target in plain words ("independent car repair shops") and the area. Our engine picks the Google Maps categories in groups, counts them in the area, and returns a search ready to use. Costs 100 credits (Idempotency-Key header and maxCredits ≥ 100 required), refunded if the engine returns no selection. Send the very same request again with the same Idempotency-Key to get the saved selection without paying twice. A request too vague to choose categories is refused with 422 clarification_needed (refunded): its details carry the question to ask the user and its options; no search is returned until categories are chosen.

Paid: Idempotency-Key header and maxCredits required.

JSON body:

Response 200:

Refusals of this route (plus the common ones):

• invalid_request (400): A field is missing or invalid: see "details".
• country_unavailable (400): The country is not open yet.
• target_unresolved (400): categories.request is set without any category: call /categories/suggest first.
• target_excluded (400): The exclusions remove every category of the target.
• clarification_needed (422): The request is too vague: ask the user the question in "details", then suggest again (refunded).
• invalid_selection (422): The engine chose no usable category (refunded): describe the target more precisely.

Lookups

Areas, single categories and brands, to adjust a search. Free.

GET /areas

Find an area (region, département, commune, postal code, radius). Free. Use the "area" field of a result (or of match when resolved) as search.area or as the area of /categories/suggest.

Free.

Query parameters:

Response 200:

Refusals of this route (plus the common ones):

• invalid_request (400): A field is missing or invalid: see "details".
• country_unavailable (400): The country is not open yet.

GET /categories

Look up a single category by name. Free. To build a target, call POST /categories/suggest instead; use this only to check or add one category (search.categories.ids).

Free.

Query parameters:

Response 200:

Refusals of this route (plus the common ones):

• invalid_request (400): A field is missing or invalid: see "details".
• country_unavailable (400): The country is not open yet.

GET /networks

Look up a brand or network. Free. Use the id in search.filters.networks ({ mode: "only" | "exclude", ids }). Without ids, mode "exclude" removes every known network.

Free.

Query parameters:

Response 200:

Refusals of this route (plus the common ones):

• invalid_request (400): A field is missing or invalid: see "details".

Search

Count, figures, sample rows and cost of a search. Free.

POST /search/count

Count the places of a search. Free. Places already delivered to the account are left out unless search.excludeDelivered is false.

Free.

JSON body:

Response 200:

Refusals of this route (plus the common ones):

• invalid_request (400): A field is missing or invalid: see "details".
• country_unavailable (400): The country is not open yet.
• target_unresolved (400): categories.request is set without any category: call /categories/suggest first.
• target_excluded (400): The exclusions remove every category of the target.
• zone_unavailable (422): Rarely searched area without any estimate: narrow the target or the area.

POST /search/metrics

Places with email, phone and website. Free. The figures of the search card in one call, and the estimated number of email addresses.

Free.

JSON body:

Response 200:

Refusals of this route (plus the common ones):

• invalid_request (400): A field is missing or invalid: see "details".
• country_unavailable (400): The country is not open yet.
• target_unresolved (400): categories.request is set without any category: call /categories/suggest first.
• target_excluded (400): The exclusions remove every category of the target.
• zone_unavailable (422): Rarely searched area without any estimate: narrow the target or the area.

POST /search/preview

Sample rows of a search, without contact details. Free. Up to 25 rows; contact details are booleans (they only come with a list).

Free.

JSON body:

Response 200:

Refusals of this route (plus the common ones):

• invalid_request (400): A field is missing or invalid: see "details".
• country_unavailable (400): The country is not open yet.
• target_unresolved (400): categories.request is set without any category: call /categories/suggest first.
• target_excluded (400): The exclusions remove every category of the target.
• zone_unavailable (422): Rarely searched area without any estimate: narrow the target or the area.

POST /search/estimate

Rows, cost and balance of a list. Free. Up to 50000 rows. Send "cost" as maxCredits to POST /lists. In a rarely searched area, returns the estimate of the area (kind "zone"): create the list, it fills afterwards.

Free.

JSON body:

Response 200:

When kind is "export":

When kind is "zone":

Refusals of this route (plus the common ones):

• invalid_request (400): A field is missing or invalid: see "details".
• country_unavailable (400): The country is not open yet.
• target_unresolved (400): categories.request is set without any category: call /categories/suggest first.
• target_excluded (400): The exclusions remove every category of the target.
• zone_unavailable (422): Rarely searched area without any estimate: narrow the target or the area.
• fair_use_limit (403): Agency: the fair use limit of this country is reached.

Lists

Create, complete, read and download lists.

GET /lists

The lists of the account. Free. Newest first, page by page (cursor).

Free.

Query parameters:

Response 200:

Refusals of this route (plus the common ones):

• invalid_request (400): A field is missing or invalid: see "details".

POST /lists

Create a list from a search. Exports the places of the search into a new list (contact details included), up to 50,000 rows. Price: 1 credit per place never delivered to the account (Agency: included under fair use); withEmail: the export, the guessed addresses and their verification; verifyEmails: plus 1 credit per address verified. maxCredits is never exceeded: send the cost of POST /search/estimate (with the same withEmail), and with verifyEmails at least that cost plus rows. One export at a time per account. In a rarely searched area (estimate kind "zone"), the list fills while the area is updated: send rows or wholeArea: true, and maxCredits ≥ the creditCap of the estimate. A replay with the same Idempotency-Key returns the list as it is now (replayed: true), without charging again.

Paid: Idempotency-Key header and maxCredits required.

JSON body:

Response 201:

Response 202: The list goes on filling in the background (export over 10,000 rows, guessed addresses of a list "with email", rarely searched area). Follow the list with GET /lists/{id} until status is "ready" (or "failed"). Do not send the request again under a new Idempotency-Key.

Refusals of this route (plus the common ones):

• invalid_request (400): A field is missing or invalid: see "details".
• country_unavailable (400): The country is not open yet.
• target_unresolved (400): categories.request is set without any category: call /categories/suggest first.
• target_excluded (400): The exclusions remove every category of the target.
• max_credits_too_low (400): maxCredits does not cover the call: the message gives the amount needed. Nothing was charged.
• verify_emails_unavailable (400): verifyEmails over 10,000 rows or in a rarely searched area: verify after creation with POST /lists/{id}/email-check.
• whole_area_unavailable (400): wholeArea outside a rarely searched area: send rows.
• empty_search (422): No place matches the search. Nothing was charged.
• zone_unavailable (422): The rarely searched area cannot be estimated or filled as asked.
• whole_country (422): This country cannot be filled whole: choose a region or a city.
• fair_use_limit (403): Agency: the fair use limit of this country is reached.
• export_in_progress (409): One export at a time per account, or places are still being added to this list.
• included_ended (409): Exports are no longer included (the Agency subscription ended): estimate again.
• legacy_delivery_conflict (409): These places are temporarily unavailable: try another search.
• too_many_active_fills (409): Too many lists being filled at once: wait until one is done.
• catalog_unavailable (503): The export failed and any credit taken was refunded: retry with the same request and Idempotency-Key.
• refund_pending (500): The export failed and its refund is on its way (within 30 minutes): do not retry now.

GET /lists/{id}

Status, progress and contents of a list. Free. Status, rows, credits spent, progress of the export, of the filling, of the guessed addresses and of the email verification (progress.emailCheck.unverified = what POST /lists/{id}/email-check would cost), contents (rows with a website, an email, a phone, an executive; email verdicts) and the 20 latest jobs. Poll it every 10 seconds or more.

Free.

Response 200:

Refusals of this route (plus the common ones):

• not_found (404): Unknown id, or a list, job or file of another account.

PATCH /lists/{id}

Rename a list. Free.

Free.

JSON body:

Response 200:

Refusals of this route (plus the common ones):

• not_found (404): Unknown id, or a list, job or file of another account.
• invalid_request (400): A field is missing or invalid: see "details".
• invalid_name (400): Empty or too long name.
• list_creating (409): The export of the list is still running.

DELETE /lists/{id}

Delete a list. Free, final, refunds nothing; places stay delivered (never billed again). Ask the user first, then send the list id again as confirm (DELETE /lists/{id}?confirm={id}). Refused while the list is being created or worked on.

Free.

Query parameters:

Response 204: empty body.

Refusals of this route (plus the common ones):

• confirmation_required (400): The confirm parameter (the list id again) is missing: ask the user, then send it.
• not_found (404): Unknown id, or a list, job or file of another account.
• list_creating (409): The export of the list is still running.
• job_running (409): A job still runs on the list.
• export_in_progress (409): One export at a time per account, or places are still being added to this list.
• email_run_open (409): Email addresses are still being guessed for the list (progress.emailGuess).
• fill_in_progress (409): The list still fills itself (rarely searched area).

GET /lists/{id}/items

The rows of a list, contact details included. Free. Up to 1,000 rows per page; send nextCursor back as cursor until it is null. Each row: placeId, then one field per column key (text as in the CSV file, French labels and values, numbers as numbers, null when empty); columns lists the keys. email_status holds the verdict of the email verification (délivrable, risqué, indélivrable, sans résultat, en attente, non vérifiée). Readable once the list is "ready" (or "filling").

Free.

Query parameters:

Response 200:

Refusals of this route (plus the common ones):

• not_found (404): Unknown id, or a list, job or file of another account.
• invalid_request (400): A field is missing or invalid: see "details".
• list_not_ready (409): The list is not ready (export running or failed): wait until GET /lists/{id} says "ready".

POST /lists/{id}/complete

Add the places of the original search not yet in the list. Priced as an export (1 credit per place never delivered; Agency: included). maxCredits is never exceeded.

Paid: Idempotency-Key header and maxCredits required.

JSON body:

Response 200:

Response 202: Places are still being added in the background. Follow the list with GET /lists/{id} until status is "ready" (or "failed").

Refusals of this route (plus the common ones):

• not_found (404): Unknown id, or a list, job or file of another account.
• invalid_request (400): A field is missing or invalid: see "details".
• not_completable (409): Only a list created from a search can be completed (not a merged list).
• list_not_ready (409): The list is not ready (export running or failed): wait until GET /lists/{id} says "ready".
• job_running (409): A job still runs on the list.
• email_run_open (409): Email addresses are still being guessed for the list (progress.emailGuess).
• fill_in_progress (409): The list still fills itself (rarely searched area).
• list_full (409): The list already holds 50,000 places: create a new list.
• export_in_progress (409): One export at a time per account, or places are still being added to this list.
• included_ended (409): Exports are no longer included (the Agency subscription ended): estimate again.
• fair_use_limit (403): Agency: the fair use limit of this country is reached.

POST /lists/merge

Merge lists into a new one. Merges 2 to 20 ready lists into a new list without duplicates. Nothing is billed again.

Free, Idempotency-Key header required.

JSON body:

Response 201:

Refusals of this route (plus the common ones):

• invalid_request (400): A field is missing or invalid: see "details".
• invalid_lists (400): Send 2 to 20 different list ids.
• not_found (404): Unknown id, or a list, job or file of another account.
• list_not_ready (409): The list is not ready (export running or failed): wait until GET /lists/{id} says "ready".

POST /lists/{id}/files

Prepare a CSV or Excel file of a list. A CSV holds every column; an Excel file the columns you choose. Then poll GET /lists/{id}/files/{fileId} until the file is ready. A file stays available 7 days.

Free, Idempotency-Key header required.

JSON body:

Response 200:

Response 202: The file is being prepared: poll GET /lists/{id}/files/{fileId}.

Refusals of this route (plus the common ones):

• not_found (404): Unknown id, or a list, job or file of another account.
• invalid_request (400): A field is missing or invalid: see "details".
• list_not_ready (409): The list is not ready (export running or failed): wait until GET /lists/{id} says "ready".
• empty_list (409): The list has no rows.

GET /lists/{id}/files/{fileId}

Status of a file, then its download link. Free. Once status is "ready", url is a download link valid 120 seconds (call again for a new one). "stale": prepare the file again.

Free.

Response 200:

Refusals of this route (plus the common ones):

• not_found (404): Unknown id, or a list, job or file of another account.

Jobs

Executives, website summary, question to the website, AI filter, email verification.

POST /lists/{id}/jobs/estimate

Places a job would process, and its maxCredits. Free. Send the same tool, question, criterion and scope as the job; send estimate.maxCredits as maxCredits.

Free.

JSON body:

Response 200:

Refusals of this route (plus the common ones):

• not_found (404): Unknown id, or a list, job or file of another account.
• invalid_request (400): A field is missing or invalid: see "details".
• not_in_france (409): Executives exist for places in France only.
• list_not_ready (409): The list is not ready (export running or failed): wait until GET /lists/{id} says "ready".
• job_unavailable (409): The job cannot run on this list as it is: check it with GET /lists/{id}.

POST /lists/{id}/jobs

Run executives, website summary, question to the website or AI filter. Runs in the background (202). Nothing is charged at launch: each place is billed on its result (executives: 2 credits per place with at least one executive found, France only; summary, question, filter: 1 credit per row analysed, even when negative or undetermined), never beyond maxCredits nor the estimate. Results land in GET /lists/{id}/items. A replay with the same Idempotency-Key returns the job already started.

Paid: Idempotency-Key header and maxCredits required.

JSON body:

Response 202:

Refusals of this route (plus the common ones):

• not_found (404): Unknown id, or a list, job or file of another account.
• invalid_request (400): A field is missing or invalid: see "details".
• not_in_france (409): Executives exist for places in France only.
• list_not_ready (409): The list is not ready (export running or failed): wait until GET /lists/{id} says "ready".
• job_unavailable (409): The job cannot run on this list as it is: check it with GET /lists/{id}.
• max_credits_too_low (400): maxCredits does not cover the call: the message gives the amount needed. Nothing was charged.
• invalid_scope (400): scope is not { kind: "all" }, { kind: "conforming", jobId } or { kind: "undetermined", jobId }.
• nothing_to_do (422): No place of the list needs this job. Nothing was charged.
• too_many_items (422): More than 50,000 places to process: narrow the scope.
• scope_unavailable (409): The job named in scope is not a finished filter or question job of this list.
• parent_unavailable (409): The qualification to complete is not finished.
• too_many_active_jobs (409): Three jobs already run on the lists of the account: wait until one is done.
• active_job_exists (409): A job of this tool already runs on this list: follow it.
• email_run_open (409): Email addresses are still being guessed for the list (progress.emailGuess).

GET /jobs/{id}

Progress of a job. Free. Status, places done and billed, credits spent; for a finished filter or question job, the places per verdict.

Free.

Response 200:

Refusals of this route (plus the common ones):

• not_found (404): Unknown id, or a list, job or file of another account.

POST /lists/{id}/email-check

Verify the email addresses of a list. 1 credit per address that gets a verdict. maxCredits is the number of addresses you accept to verify: send progress.emailCheck.unverified of GET /lists/{id}; if there are more, the call is refused with the number (nothing charged). The credits are reserved now; those without a verdict are returned when the check ends. Verdicts land in GET /lists/{id}/items (email_status) and in contents.emailVerdicts.

Paid: Idempotency-Key header and maxCredits required.

JSON body:

Response 200:

Refusals of this route (plus the common ones):

• not_found (404): Unknown id, or a list, job or file of another account.
• invalid_request (400): A field is missing or invalid: see "details".
• max_credits_too_low (400): maxCredits does not cover the call: the message gives the amount needed. Nothing was charged.
• email_check_running (409): A verification already runs on this list: follow progress.emailCheck.
• nothing_to_check (409): Every address of the list is already verified.
• email_check_included (409): The addresses of this list are verified automatically, for free.
• export_in_progress (409): One export at a time per account, or places are still being added to this list.
• list_not_ready (409): The list is not ready (export running or failed): wait until GET /lists/{id} says "ready".

Objects

The objects that several routes return.

The list object

The job object

The file object