Create or Update 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": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "first_name": "<string>",
    "source": "<string>",
    "metadata": {},
    "created_at": "2023-11-07T05:31:56Z",
    "last_name": "<string>",
    "email": "jsmith@example.com",
    "phone": "<string>",
    "company": "<string>",
    "title": "<string>",
    "campaign_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "assigned_to": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "assigned_user": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>"
    }
  },
  "existed": true,
  "workflow_run": "<unknown>",
  "workflow_run_skipped": "<unknown>",
  "moved_from": "<unknown>",
  "force_first_message": "<unknown>",
  "force_first_channel": "<unknown>",
  "sms_consent": "<unknown>",
  "whatsapp_consent": "<unknown>",
  "warning": "<unknown>"
}

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": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "first_name": "<string>",
    "source": "<string>",
    "metadata": {},
    "created_at": "2023-11-07T05:31:56Z",
    "last_name": "<string>",
    "email": "jsmith@example.com",
    "phone": "<string>",
    "company": "<string>",
    "title": "<string>",
    "campaign_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "assigned_to": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "assigned_user": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>"
    }
  },
  "existed": true,
  "workflow_run": "<unknown>",
  "workflow_run_skipped": "<unknown>",
  "moved_from": "<unknown>",
  "force_first_message": "<unknown>",
  "force_first_channel": "<unknown>",
  "sms_consent": "<unknown>",
  "whatsapp_consent": "<unknown>",
  "warning": "<unknown>"
}

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"

source

string

default:api

company

string | null

title

string | null

city

string | null

date_of_birth

string<date> | null

external_id

string | null

Response

An existing identity was matched and merged.

success

enum<boolean>

required

Available options:

true

lead

object

required

Show child attributes

existed

boolean

workflow_run

any