Skip to main content
The Lead API lets any external system drop a lead straight into your Oktivo CRM dashboard. This guide walks through a working integration end to end.

​
1. Create an API token

The Lead API is authenticated with an account API token. Create one from your account settings:
1

Open account settings

In the dashboard, click your account and open Settings (app.oktivo.com/account).
2

Go to API Tokens

In the settings sidebar, select the API Tokens tab. You’ll see the API Tokens panel listing any existing tokens with their expiry and last-used date.
Oktivo account API Tokens settings with the Create Token button

Settings → API Tokens: create, rotate, and delete tokens

3

Create the token

Click Create Token (top right), give it a recognisable name (e.g. website-lead-capture), and choose an expiry (1–365 days).
4

Copy and store it

Copy the okt_... value immediately — it is shown only once. Store it as a secret in whatever system will call the API; never commit it to source control.
Each account can have a maximum of 5 active tokens. If you’ve hit the limit, delete an unused token (trash icon) before creating a new one. Use the rotate icon to replace a token’s value in a single step without changing where it’s referenced.
See Authentication for token rotation and expiry details.

​
2. Send your first lead

The only hard requirement is a phone or an email. Everything else is optional.
A 201 means a new lead was created; a 200 with "merged": true means the person already existed and your data was merged in. See the full field reference on Capture a Lead.

​
3. Attach your own fields

Any key that is not a reserved lead field is stored as a custom field and shows up as a column on the CRM dashboard. Send them at the top level, or group them under customFields:
You can send up to 50 custom fields per lead.

​
4. Let Oktivo de-duplicate for you

You do not need to check whether a lead already exists. Oktivo keeps one lead per phone (or email) per account:
  • A new acquisition source on an existing person merges and records a source history entry.
  • Self-service sources (website, chatbot, whatsapp, google_form, ai_powered_lead, payment_page_drop, landing) always merge on repeat and keep the latest values — ideal for returning visitors and re-fired events.
  • Curated sources (api, webhook, manual, csv_import) return a 409 on a repeat of the same source, protecting your data from accidental overwrites.
Set metadata.source to one of the known values so filtering and the merge behaviour stay correct. Any unknown source is stored as api.

​
5. Forward from an unauthenticated webhook (optional)

If a platform can only send plain, unauthenticated webhooks (no custom headers), put a tiny proxy in front of the Lead API that attaches your Bearer token. This repo ships a ready-made Cloudflare Worker at cloudflare-lead-worker/ that maps an arbitrary webhook payload into the Lead API body and forwards it. Set your OKTIVO_API_TOKEN as a Worker secret and point the platform’s webhook at the Worker URL.

​
Common pitfalls

  • Missing identity — sending neither phone nor email returns a 400.
  • Unexpected source — a typo in metadata.source silently becomes api; use the exact values from the source table.
  • Hitting the field cap — more than 50 custom fields returns a 400 rather than silently dropping columns.
  • Rate limits — on a 429, honour the Retry-After header and back off.