Package Information
Documentation
n8n-nodes-primavera
Build B2B lists of local businesses in your n8n workflows. Primavera is a database of
businesses: the Google Maps places of France and of other countries, read with their websites (email addresses, phone
numbers, websites, social networks, technologies; executives in France and the United States). This package is a client
of the Primavera API: it turns a target written in plain words ("independent car
repair shops") into a search, counts and estimates it for free, creates the list, reads its rows, runs jobs on it and
verifies its email addresses.
n8n is a fair-code licensed workflow automation
platform.
- Installation
- Credentials
- Operations
- Trigger
- Credits, limits and retries
- Errors
- Example workflow
- Compatibility
- Resources
Installation
Follow the installation guide in the n8n community
nodes documentation: in n8n, open Settings › Community Nodes › Install and enter n8n-nodes-primavera.
Credentials
You need a Primavera account whose email address is confirmed, with or without a subscription (without one, the
free credits of a new account work here as in the web app, with lower rate limits), and an API key:
- Create a key at https://primaverapp.com/dashboard/api. It reads
pv_live_followed by 32 letters and digits and is
shown once. - In n8n, create a Primavera API credential and paste the key. n8n checks it with
GET /account: a403means the
key is valid but the email address of the account is not confirmed yet, or the account is on hold.
The key is sent only to https://primaverapp.com, in the Authorization header. A key can carry a monthly credit cap,
set on the same page: a useful guard for automated workflows.
Operations
Each operation returns the JSON of its API route, except the operations that return many things (rows, lists,
categories, networks, preview rows): one n8n item each. The API documentation
describes every field.
| Resource | Operation | Route | Cost |
|---|---|---|---|
| Account | Get | GET /account |
free |
| Area | Search | GET /areas |
free |
| Category | Suggest (entry point of every target) | POST /categories/suggest |
paid |
| Category | Search | GET /categories |
free |
| Network | Search (brands and networks) | GET /networks |
free |
| Search | Count | POST /search/count |
free |
| Search | Get Metrics (with email, phone, website) | POST /search/metrics |
free |
| Search | Preview (sample rows, no contact details) | POST /search/preview |
free |
| Search | Estimate (rows and cost of a list) | POST /search/estimate |
free |
| List | Create | POST /lists |
paid |
| List | Get | GET /lists/{id} |
free |
| List | Get Many | GET /lists |
free |
| List | Get Rows (one item per row, pages of 1,000 followed) | GET /lists/{id}/items |
free |
| List | Prepare File (CSV or Excel, optional download into binary data) | POST /lists/{id}/files |
free |
| List | Verify Emails | POST /lists/{id}/email-check |
paid |
| Job | Estimate | POST /lists/{id}/jobs/estimate |
free |
| Job | Start (executives, website summary, question to the website, AI filter) | POST /lists/{id}/jobs |
paid |
| Job | Get | GET /jobs/{id} |
free |
Prices are those of the Primavera web app, with the same balance: see
Prices. The node never computes a price itself; the estimates of the API
give the amount to send.
Some work goes on in the background: a list of more than 10,000 rows, the guessed addresses of a list "with email", a
list in a rarely searched area, a job, an email verification, a file. By default the node waits for it, polling the
API (every 10 seconds for a list), up to a Wait Limit you set. When the limit comes first, the node returns the
current state with wait.timedOut: true; follow it later with List › Get, Job › Get or the trigger. A list is never
created twice to catch up.
The node can be used as a tool by the n8n AI Agent.
Trigger
Primavera Trigger › List Ready starts a workflow when a list of the account is ready (optionally: when one fails).
It reads the 100 newest lists of the account once a minute at most, whatever the poll times, and reports each list
once. Lists created before the workflow was activated are not reported, except those still being built then. A list
"with email" is reported once its missing addresses have been guessed (one more call, GET /lists/{id}, for those
lists only). Fetch Test Event returns the newest ready list.
Credits, limits and retries
Every paid operation (Category › Suggest, List › Create, List › Verify Emails, Job › Start) has two fields:
- Max Credits, required and empty by default: the most credits the call may spend. The API never goes over it, and
the node sends nothing when it is empty. Use thecostof Search › Estimate (made with the same rows and the same
"With Email" choice),estimate.maxCreditsof Job › Estimate, or for Verify Emails the number of addresses you
accept to verify (progress.emailCheck.unverifiedof List › Get). A suggestion costs 100 credits. - Idempotency Key, filled by default with
{{ $execution.id }}-{{ $itemIndex }}-{{ JSON.stringify($json).hash() }}
(the execution, the item index and the content of the input item). The node sends the API anIdempotency-Key
header derived from it (a UUID is sent as is; any other value becomes a UUID, the same value always giving the same
UUID in the same node and operation). A retry of the same item ("Retry On Fail", a lost answer, the retries of an AI
Agent tool call) therefore gets the saved result and is never charged twice. Two different requests under the same
key are refused (idempotency_conflict), never charged. The default changes with each execution; to keep a key
across executions (for example one list per row of a sheet), use an ID from your data. Used as a tool by the AI
Agent, the node also puts the request itself in the key, so that the different calls of the agent get different
keys while a retried call keeps its own.
The API allows 20 requests per minute without a subscription, 60 on Pro and 300 on Agency, per account. On a 429, the free operations wait forRetry-After once and send the same request again; paid operations do not retry by themselves.
Contact details (email addresses, phone numbers, websites) only come with a list: previews say whether they exist,
not what they are.
Errors
A refusal of the API shows its code and its hint, for example:
[insufficient_credits] The balance does not cover the call. Hint: Lower rows, or ask the account owner to top up at https://primaverapp.com/dashboard/billing.
With On Error › Continue, the item carries error.code, error.message, error.hint, error.httpCode,error.retryAfterSeconds and error.details. The codes are listed in the
API documentation.
Example workflow
- Primavera › Category › Suggest, renamed "Suggest": Target "independent car repair shops", Options › Area "Lyon",
Max Credits 100. - Primavera › Search › Estimate: Search
{{ $('Suggest').item.json.search }}, Rows 300. - Primavera › List › Create: Search as above, Rows 300, Max Credits
{{ $json.cost }}. - Primavera › List › Get Rows: List
{{ $json.list.id }}(By ID), Return All. - Send the rows to your sheet, CRM or sequencer (Google Sheets, Instantly, lemlist...).
Compatibility
Built with @n8n/node-cli 0.57 against n8n-workflow 2.48 (n8n 2.48). No runtime dependency.
Development
pnpm install
pnpm run lint
pnpm test # build, then unit tests on a fake n8n context (no network)
node test/live-free.mjs checks the built node against the production API with free calls only (no key: an unknown
key must get 401 unauthorized with its hint; with PRIMAVERA_API_KEY set: account, area, categories, count,
figures, preview, estimate and lists).