Primavera

Add places to a list from its original search; places already in the list are skipped. Priced as an export: 1 credit per place never delivered to the account (Agency: included under fair use).

Paid: maxCredits (the most credits this call may spend, never exceeded) and idempotencyKey (a new UUID v4 for this operation) are required; without them nothing runs. To retry after an error or a timeout, send the same idempotencyKey with the same arguments: nothing is charged twice. Ask the user before calling it.

Same call as POST /api/v1/lists/{id}/complete of the REST API.

Count the places of a search (the "search" returned by suggest_categories). Its input describes the search object in full (target, area, filters one by one, sort): read it to edit a search. Places already delivered to the account are left out unless search.excludeDelivered is false. When "exact" is false, say "≈ N".

Free.

Same call as POST /api/v1/search/count of the REST API.

Export the places of a search into a new list, with their contact details (up to 50,000 rows). Price: 1 credit per place never delivered to this account (Agency: included under fair use); withEmail: only places with an email address (found ones first, then guessed and verified ones); verifyEmails: plus 1 credit per address verified. maxCredits is never exceeded: send the "cost" of estimate_list, once the user agreed. One export at a time per account. While the list says "creating", follow it with get_list.

Paid: maxCredits (the most credits this call may spend, never exceeded) and idempotencyKey (a new UUID v4 for this operation) are required; without them nothing runs. To retry after an error or a timeout, send the same idempotencyKey with the same arguments: nothing is charged twice. Ask the user before calling it.

Same call as POST /api/v1/lists of the REST API.

Rows, cost in credits and balance after, for a list of N rows of a search (up to 50,000). Tell the user the cost, then send "cost" as maxCredits to create_list with the same search, rows and withEmail. In a rarely searched area it returns kind "zone": the list fills itself after creation (create_list with maxCredits ≥ zoneEstimate.creditCap).

Free.

Same call as POST /api/v1/search/estimate of the REST API.

Estimate a job on a list before starting it: places eligible and the most credits it can spend. Jobs: executives (company executives, France and the United States only), summary (a 3-sentence summary of each website), question (a yes/no question asked to each website), filter (a criterion judged on the data we hold, no website read).

Free.

Same call as POST /api/v1/lists/{id}/jobs/estimate of the REST API.

Find an area from a place as written: region, département, commune, postal code, or a radius around a town ("Lyon", "33", "30 km around Nantes"). Use the "area" field of a result (or of "match" when its status is "resolved") as the area of suggest_categories or as search.area.

Free.

Same call as GET /api/v1/areas of the REST API.

Look up a single Google Maps category by name (French or English), with its number of places. To build a target, use suggest_categories instead; use this only to check or add one category id to search.categories.ids.

Free.

Same call as GET /api/v1/categories of the REST API.

Look up a brand, franchise or network by name. Use its id in search.filters.networks ({ "mode": "only" | "exclude", "ids": [...] }); mode "exclude" without ids removes every known network (independent businesses only).

Free.

Same call as GET /api/v1/networks of the REST API.

Plan, credit balance, Agency fair use per country and rate limits of the Primavera account that owns the API key. Call it first: it tells what the account can afford.

Free.

Same call as GET /api/v1/account of the REST API.

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

Free.

Same call as GET /api/v1/jobs/{id} of the REST API.

Status of a list (creating, ready, filling, failed), rows, credits spent, progress of the export, of the guessed email addresses and of the email verification (progress.emailCheck.unverified = what verify_list_emails would cost), contents and latest jobs. While it is not ready, call it again every 10 seconds or more.

Free.

Same call as GET /api/v1/lists/{id} of the REST API.

Status of a prepared file. Once it is ready, "url" is a download link valid 120 seconds: download it at once or give it to the user, and call again for a new link.

Free.

Same call as GET /api/v1/lists/{id}/files/{fileId} of the REST API.

Rows of a ready list with every contact detail, page by page (nextCursor). Keep limit small (50 or less) and choose columns: large pages flood the conversation. For the whole list, use prepare_list_file.

Free.

Same call as GET /api/v1/lists/{id}/items of the REST API.

The figures of a search in one call: total, places with an email address, a phone number, a website, and the estimated number of email addresses.

Free.

Same call as POST /api/v1/search/metrics of the REST API.

The lists of the account, newest first, page by page (send nextCursor back as cursor).

Free.

Same call as GET /api/v1/lists of the REST API.

Prepare the CSV file (every column) or the Excel file (the columns you choose) of a ready list. Then call get_list_file until the file is ready. A file stays available 7 days.

Free. idempotencyKey (a new UUID v4) is required; reuse it only to retry the very same call.

Same call as POST /api/v1/lists/{id}/files of the REST API.

Up to 25 sample places of a search (name, city, category, rating, reviews). Contact details are booleans here: email addresses, phone numbers and websites only come with a list (create_list).

Free.

Same call as POST /api/v1/search/preview of the REST API.

Start a job on a list; it runs in the background. Each place is billed on its result, never beyond maxCredits nor the estimate: send estimate.maxCredits of estimate_list_job, with the same tool, question, criterion and scope. Follow it with get_job; results land in get_list_items.

Paid: maxCredits (the most credits this call may spend, never exceeded) and idempotencyKey (a new UUID v4 for this operation) are required; without them nothing runs. To retry after an error or a timeout, send the same idempotencyKey with the same arguments: nothing is charged twice. Ask the user before calling it.

Same call as POST /api/v1/lists/{id}/jobs of the REST API.

Entry point for ANY target: call it before any search, and never invent category ids. Give the target in plain words, WITHOUT the place ("independent car repair shops", "restaurants that could use an online booking tool") and the area from find_areas. Primavera's engine picks the Google Maps categories in groups and counts them in the area. Returns "selection" (groups, categories left out and why, what the data cannot tell) and "search", the object that count_search, get_search_metrics, preview_search, estimate_list and create_list take: pass it on as is, or edited. Costs 100 credits (maxCredits ≥ 100), refunded when no selection comes back. A request too vague is refused with clarification_needed, refunded: ask the user the question in error.details, then call again with the answer.

Paid: maxCredits (the most credits this call may spend, never exceeded) and idempotencyKey (a new UUID v4 for this operation) are required; without them nothing runs. To retry after an error or a timeout, send the same idempotencyKey with the same arguments: nothing is charged twice. Ask the user before calling it.

Same call as POST /api/v1/categories/suggest of the REST API.

Verify the email addresses of a ready list (deliverable, risky, undeliverable): 1 credit per address that gets a verdict; the credits of the others are returned. maxCredits is the number of addresses you accept to verify: send progress.emailCheck.unverified of get_list.

Paid: maxCredits (the most credits this call may spend, never exceeded) and idempotencyKey (a new UUID v4 for this operation) are required; without them nothing runs. To retry after an error or a timeout, send the same idempotencyKey with the same arguments: nothing is charged twice. Ask the user before calling it.

Same call as POST /api/v1/lists/{id}/email-check of the REST API.