> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oktivo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Capturing Leads via API

> Push leads into Oktivo CRM from forms, chatbots, ad platforms, and your own backend

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:

<Steps>
  <Step title="Open account settings">
    In the dashboard, click your account and open **Settings**
    (`app.oktivo.com/account`).
  </Step>

  <Step title="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.

    <Frame caption="Settings → API Tokens: create, rotate, and delete tokens">
      <img src="https://mintcdn.com/oktivo/Loo3hGuHHxFQQqmO/images/create_token.png?fit=max&auto=format&n=Loo3hGuHHxFQQqmO&q=85&s=09ee6f0eec40b71fb3ab425c5bc1d26b" alt="Oktivo account API Tokens settings with the Create Token button" width="1901" height="862" data-path="images/create_token.png" />
    </Frame>
  </Step>

  <Step title="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).
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Note>
  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.
</Note>

See [Authentication](/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.

```bash theme={null}
curl -X POST https://client-backend.oktivo.com/api/v1/crm/leads \
  -H "Authorization: Bearer okt_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Priya Sharma",
    "phone": "9876543210",
    "email": "priya@example.com",
    "metadata": { "source": "website" }
  }'
```

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](/api-reference/leads/create-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`:

```json theme={null}
{
  "name": "Priya Sharma",
  "phone": "9876543210",
  "customFields": {
    "course": "Data Science",
    "budget": "₹2,50,000",
    "preferred_batch": "Weekend"
  }
}
```

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](/api-reference/leads/create-lead#lead-sources).
* **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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.