primavera

n8n nodes for Primavera: B2B lists of local businesses (Google Maps places read with their websites) through the Primavera API.

Package Information

Released: this month
Downloads: 0 weekly / 0 monthly
Latest Version: 0.1.1
Author: Primavera

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

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:

  1. Create a key at https://primaverapp.com/dashboard/api. It reads pv_live_ followed by 32 letters and digits and is
    shown once.
  2. In n8n, create a Primavera API credential and paste the key. n8n checks it with GET /account: a 403 means 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 the cost of Search › Estimate (made with the same rows and the same
    "With Email" choice), estimate.maxCredits of Job › Estimate, or for Verify Emails the number of addresses you
    accept to verify (progress.emailCheck.unverified of 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 an Idempotency-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 for
Retry-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

  1. Primavera › Category › Suggest, renamed "Suggest": Target "independent car repair shops", Options › Area "Lyon",
    Max Credits 100.
  2. Primavera › Search › Estimate: Search {{ $('Suggest').item.json.search }}, Rows 300.
  3. Primavera › List › Create: Search as above, Rows 300, Max Credits {{ $json.cost }}.
  4. Primavera › List › Get Rows: List {{ $json.list.id }} (By ID), Return All.
  5. 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).

Resources

License

MIT

Discussion