Lead intake

POST /v1/leads is the one write endpoint on the public API. It exists so you can bring leads in from whatever tool you already pay for, without handing NearSync that tool's credentials.

NearSync does not supply lead data

NearSync sells no contact database and sources no leads. A lead exists in your workspace only because your own provider sent it to us, or because you uploaded a file. This endpoint is the first of those two routes.

(Connecting HubSpot or Pipedrive is a different job: it migrates your existing contacts, companies and deals into Data Management. Those records are not leads and do not arrive through this endpoint.)

Why data is pushed, not pulled

The obvious design would be for NearSync to hold your provider's API key and fetch leads on your behalf. We deliberately don't, because the credentials those vendors issue are unsuitable to custody at scale:

Provider	What it issues
Hunter, Lusha, Clearbit, Cognism	Long-lived static API keys.
Apollo	OAuth, but restricted to approved partner apps.
ZoomInfo	OAuth exists (authorization code with PKCE), but distributing it to customers requires an approved partner app. Their older API auth is a username and password, or a private key.

Storing thousands of customers' long-lived provider secrets creates a concentration of risk with no benefit to you. Reversing the direction removes it: you issue a NearSync key, scoped to one permission, revocable at any time from your own settings, and your provider's credentials never leave your side.

Authentication

Create a key under Settings → API Keys with the leads:write scope, then pass it as a bearer token:

curl -X POST https://api.nearsync.tech/v1/leads \
  -H "Authorization: Bearer ns_live_yourkey..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@acme.com",
    "name": "Jane Doe",
    "company": "Acme",
    "title": "Head of Operations",
    "source": "apollo",
    "external_id": "their-record-id",
    "consent": {
      "basis": "legitimate_interest",
      "source": "Apollo saved search",
      "obtained_at": "2026-08-10"
    }
  }'

A key with leads:write can do nothing else. It cannot read your contacts, invoices, or anything else on the API — those require their own read scopes.

Fields

Field	Required	Notes
`email`	One of `email` or `phone`	Validated for format. A malformed address is rejected rather than stored.
`phone`	One of `email` or `phone`
`name` / `full_name`	No
`company`	No	Stored on the lead's metadata.
`title` / `job_title`	No
`source`	No	Your provider's name, normalised to a slug. Defaults to `api`.
`external_id`	No	Your provider's own record id. Used for idempotency — strongly recommended.
`note`	No
`linkedin_url`	No
`consent`	No	An object: `basis`, `source`, `obtained_at`. See below.

org_id is not a field. Your organization is determined by the API key alone; a body cannot target another tenant.

Responses

{ "ok": true, "lead_id": "…", "contact_id": "…", "deduplicated": false }

Status	Meaning
`200`	Lead filed. `deduplicated: true` means we had already seen this `external_id` and returned the existing lead.
`400`	Missing a contactable field, malformed email, or a body that is not a JSON object.
`401`	Missing or invalid API key.
`403`	The key does not hold the `leads:write` scope.
`413`	Body exceeds 64KB.
`429`	Rate or quota limit reached.

Idempotency

Providers retry, and automation platforms re-run. Include external_id and a repeated delivery returns the original lead_id with deduplicated: true instead of creating a second record.

If you send a consent object, it is stored on the lead as an attributed claim — what was asserted, by which source, when.

It is not promoted into the contact's own subscription state. Specifically, a lead arriving through this endpoint never sets a marketing opt-in. The contact is created with no opt-in timestamp, which means it is not eligible for a marketing campaign or cadence on the strength of having been imported.

This is deliberate. A lead is a record of an introduction. Permission to market to someone is a separate thing, obtained separately, and enforced separately — see Email compliance.

Connecting a specific provider

Most tools can call a webhook directly. For those that can't, any automation platform (Zapier, Make, n8n) can sit between them and this endpoint. In the app, Sales → AI Lead Gen lists what each provider supports.

Why data is pushed, not pulled​

Authentication​

Fields​

Responses​

Idempotency​

Consent is recorded, never assumed​

Connecting a specific provider​