curl --request POST \
  --url https://api.getnexor.ai/api/public/leads \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "first_name": "John",
  "last_name": "Doe",
  "email": "john@example.com",
  "phone": "+1234567890",
  "workflow_id": "uuid-of-workflow",
  "campaign_id": "uuid-of-campaign"
}
'

{
  "success": true,
  "lead": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "phone": "+1234567890",
    "source": "api",
    "company": null,
    "title": null,
    "metadata": {},
    "created_at": "2026-02-10T12:00:00Z"
  },
  "workflow_run": {
    "id": "uuid",
    "job_id": "job-123",
    "workflow": {
      "id": "uuid",
      "name": "Sales Outreach"
    },
    "cadence": {
      "stepIndex": 0,
      "channel": "call",
      "attemptNumber": 1,
      "maxAttempts": 3,
      "totalSteps": 5
    }
  }
}

Create Lead(s)

Create one or more leads and optionally assign to a workflow. Accepts either a single lead object or an array of lead objects for bulk creation. Leads will automatically be enrolled in the workflow’s cadence sequence. You can include arbitrary metadata as key-value pairs to store client-specific information about the lead. Bulk requests support up to 1000 leads per request and use partial success handling (valid leads are created even if some fail validation).

POST

leads

curl --request POST \
  --url https://api.getnexor.ai/api/public/leads \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "first_name": "John",
  "last_name": "Doe",
  "email": "john@example.com",
  "phone": "+1234567890",
  "workflow_id": "uuid-of-workflow",
  "campaign_id": "uuid-of-campaign"
}
'

{
  "success": true,
  "lead": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john@example.com",
    "phone": "+1234567890",
    "source": "api",
    "company": null,
    "title": null,
    "metadata": {},
    "created_at": "2026-02-10T12:00:00Z"
  },
  "workflow_run": {
    "id": "uuid",
    "job_id": "job-123",
    "workflow": {
      "id": "uuid",
      "name": "Sales Outreach"
    },
    "cadence": {
      "stepIndex": 0,
      "channel": "call",
      "attemptNumber": 1,
      "maxAttempts": 3,
      "totalSteps": 5
    }
  }
}

Automatic metadata mappingAny keys in the request body that are not core lead columns (first_name, last_name, email, phone, source, company, title, city, date_of_birth, external_id, assigned_to, workflow_id, campaign_id, tags, force_first_message, force_first_channel, skip_first_message) will automatically be mapped into the metadata object. This means you can pass extra fields at the top level without explicitly wrapping them in metadata.For example, sending { "first_name": "Tony", "edad": 35, "broker": "Tony" } is equivalent to { "first_name": "Tony", "metadata": { "edad": 35, "broker": "Tony" } }.If you provide both top-level extra keys and a metadata object, they will be merged, with explicit metadata values taking precedence.

Importing leads that already have an ownerSend assigned_to with the team member’s user ID — get it from GET /team, where each member’s id is the value to use. The owner must be an active member of your account; anything else is rejected with 400.Assigning an owner is independent from workflow_id: workflow_id picks the AI agent that works the lead, assigned_to records which person owns it.

Authorizations

X-API-Key

string

header

required

API key for authentication. Keys are prefixed with nxr_live_.

Body

application/json

object
object[]

first_name

string

required

Lead's first name

Example:

"John"

last_name

string

Lead's last name

Example:

"Doe"

string<email>

Lead's email address

Example:

"john@example.com"

phone

string

Lead's phone number (required if assigning to a workflow with call steps)

Example:

"+1234567890"

metadata

object

Arbitrary key-value data specific to your organization. Use this to store any custom information about the lead (e.g., age, salary range, assigned broker, lead status, notes). There is no enforced schema — send any keys and values you need. Values can be strings, numbers, or booleans.

Example:

{
  "edad": 35,
  "rango_sueldo": "$2000-$4000",
  "broker_asociado": "Juan Perez",
  "estado_lead": "interesado",
  "notas_asociadas": "Prefiere contacto por WhatsApp"
}

workflow_id

string<uuid>

Workflow ID to assign the lead to. Use GET /workflows to list available workflows.

Example:

"123e4567-e89b-12d3-a456-426614174000"

campaign_id

string<uuid>

Campaign ID to tag the lead with (optional). Use GET /campaigns to list available campaigns.

Example:

"123e4567-e89b-12d3-a456-426614174001"

force_first_message

object

Override the first outreach with a custom message. Requires workflow_id. The rest of the cadence sequence continues normally from the second touchpoint.

Show child attributes

assigned_to

string<uuid> | null

ID of the team member who owns this lead. Must be an active member of your account — use GET /team to list them and copy the id field. Rejected with 400 otherwise.

Example:

"123e4567-e89b-12d3-a456-426614174002"

Response

Lead(s) created successfully

Option 1
Option 2

success

boolean

required

Example:

true

lead

object

required

Show child attributes

workflow_run

object

Show child attributes

warning

string

Warning message if lead was created but workflow assignment failed

Last modified on August 4, 2026

Quick Start

WhatsApp

Agents

Assistant

Advanced

API Reference

Leads

Agents

Workflow Tools

Client Tools

Groups

Campaigns

Conversions

Reports

Tags

Messages

Background Jobs

Meetings

Team

Processors

Create Lead(s)

Authorizations

Body

Response