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, workflow_id, campaign_id, force_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.

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

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 June 18, 2026

Authentication

Get Lead