Create Lead(s)

POST /leads

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 1,000 leads per request and use partial success handling (valid leads are created even if some fail validation).

Request Body

Field	Type	Required	Description
first_name	string	Yes	Lead's first name
last_name	string	No	Lead's last name
email	string	No	Lead's email address
phone	string	No	Lead's phone number (required if assigning to a workflow with call steps)
workflow_id	string (uuid)	No	Workflow ID to assign the lead to. Use GET /workflows to list available workflows
campaign_id	string (uuid)	No	Campaign ID to tag the lead with. Use GET /campaigns to list available campaigns
metadata	object	No	Arbitrary key-value data. Values can be strings, numbers, or booleans

Examples

Single lead with workflow

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

Single lead with custom metadata

curl -X POST https://api.getnexor.ai/api/public/leads \
  -H "Content-Type: application/json" \
  -H "X-API-Key: nxr_live_your_api_key" \
  -d '{
    "first_name": "Maria",
    "last_name": "Garcia",
    "email": "maria@example.com",
    "phone": "+56912345678",
    "workflow_id": "uuid-of-workflow",
    "campaign_id": "uuid-of-campaign",
    "metadata": {
      "edad": 35,
      "rango_sueldo": "$2000-$4000",
      "broker_asociado": "Juan Perez",
      "estado_lead": "interesado",
      "notas_asociadas": "Prefiere contacto por WhatsApp",
      "fecha_lead": "2025-01-15"
    }
  }'

Bulk lead creation

curl -X POST https://api.getnexor.ai/api/public/leads \
  -H "Content-Type: application/json" \
  -H "X-API-Key: nxr_live_your_api_key" \
  -d '[
    {
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "phone": "+1234567890",
      "workflow_id": "uuid-of-workflow",
      "campaign_id": "uuid-of-campaign",
      "metadata": {
        "edad": 28,
        "rango_sueldo": "$3000-$5000",
        "broker_asociado": "Carlos Lopez"
      }
    },
    {
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane@example.com",
      "phone": "+0987654321",
      "workflow_id": "uuid-of-workflow",
      "campaign_id": "uuid-of-campaign",
      "metadata": {
        "edad": 35,
        "rango_sueldo": "$2000-$4000",
        "broker_asociado": "Juan Perez"
      }
    }
  ]'

Responses

201 — Lead(s) created successfully

Single lead response:

{
  "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
    }
  }
}

Bulk response with partial success:

{
  "success": false,
  "results": [
    {
      "success": true,
      "lead": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "first_name": "John",
        "last_name": "Doe",
        "email": "john@example.com",
        "phone": "+1234567890",
        "source": "api",
        "metadata": {},
        "created_at": "2026-02-10T12:00:00Z"
      },
      "index": 0
    },
    {
      "success": false,
      "error": "first_name is required",
      "index": 1
    }
  ],
  "summary": {
    "total": 2,
    "created": 1,
    "failed": 1
  }
}

400 — Validation error

{
  "error": "Validation error",
  "message": "first_name is required"
}

Other validation errors:

• "phone is required when assigning to a workflow with call steps"
• "campaign_id not found or does not belong to your account"

401 — Authentication error

See Authentication.

404 — Workflow not found

{
  "error": "Not found",
  "message": "Workflow not found or does not belong to your account"
}

500 — Internal server error