Route Lead Through Processor

POST /processors/:processorId/leads

Create a lead and route it through a processor's rules to determine the target workflow. The request body is identical to Create Lead(s) but without workflow_id — the processor decides which workflow the lead enters.

The processor evaluates its routing rules top-to-bottom. The first rule where all conditions match determines the target workflow. If no rule matches, the processor's default workflow is used.

Supports both single and bulk requests (up to 1,000 leads). In bulk mode, each lead is evaluated independently and may land in different workflows.

Path Parameters

Parameter	Type	Description
processorId	string (uuid)	Processor ID

Request Body

Same as Create Lead(s), minus workflow_id:

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 target workflow has call steps)
source	string	No	Lead source, defaults to "api"
company	string	No	Lead's company
title	string	No	Lead's job title
campaign_id	string (uuid)	No	Campaign ID to tag the lead with
metadata	object	No	Arbitrary key-value data — this is what routing rules typically evaluate

tip

The metadata object is the primary source for routing conditions. Include all the fields your processor's rules need to evaluate (e.g., language, budget, city, campaign_name).

Examples

Single lead — routed by language

curl -X POST https://api.getnexor.ai/api/public/processors/abc-123-uuid/leads \
  -H "Content-Type: application/json" \
  -H "X-API-Key: nxr_live_your_api_key" \
  -d '{
    "first_name": "María",
    "last_name": "González",
    "phone": "+5215512345678",
    "email": "maria@example.com",
    "source": "meta_ads",
    "metadata": {
      "language": "ES",
      "campaign_name": "Q1 Launch"
    }
  }'

Single lead — routed by budget + city

curl -X POST https://api.getnexor.ai/api/public/processors/abc-123-uuid/leads \
  -H "Content-Type: application/json" \
  -H "X-API-Key: nxr_live_your_api_key" \
  -d '{
    "first_name": "Carlos",
    "last_name": "Ruiz",
    "phone": "+5215598765432",
    "metadata": {
      "budget": 750000,
      "city": "CDMX",
      "property_type": "departamento"
    }
  }'

Bulk — mixed routing

Each lead is evaluated independently and may end up in different workflows:

curl -X POST https://api.getnexor.ai/api/public/processors/abc-123-uuid/leads \
  -H "Content-Type: application/json" \
  -H "X-API-Key: nxr_live_your_api_key" \
  -d '[
    {
      "first_name": "María",
      "phone": "+5215512345678",
      "metadata": { "language": "ES" }
    },
    {
      "first_name": "John",
      "phone": "+12025551234",
      "metadata": { "language": "EN" }
    }
  ]'

Responses

201 — Lead(s) created and routed

Single lead response:

{
  "success": true,
  "lead": {
    "id": "lead-uuid",
    "first_name": "María",
    "last_name": "González",
    "email": "maria@example.com",
    "phone": "+5215512345678",
    "source": "meta_ads",
    "metadata": {
      "language": "ES",
      "campaign_name": "Q1 Launch"
    },
    "created_at": "2026-03-31T12:00:00Z"
  },
  "workflow_run": {
    "id": "run-uuid",
    "job_id": "job-123",
    "workflow": {
      "id": "uuid-of-es-workflow",
      "name": "Enlace de Pago Enviado"
    },
    "cadence": {
      "stepIndex": 0,
      "channel": "call",
      "attemptNumber": 1,
      "maxAttempts": 3,
      "totalSteps": 5
    }
  },
  "routing": {
    "processor_id": "abc-123-uuid",
    "processor_name": "Language Router",
    "matched_rule": {
      "id": "rule-2-uuid",
      "name": "Spanish leads",
      "position": 2
    }
  }
}

When the default workflow is used (no rule matched):

{
  "success": true,
  "lead": { "..." : "..." },
  "workflow_run": { "..." : "..." },
  "routing": {
    "processor_id": "abc-123-uuid",
    "processor_name": "Language Router",
    "matched_rule": null
  }
}

Bulk response:

{
  "success": true,
  "results": [
    {
      "success": true,
      "lead": { "id": "lead-1-uuid", "first_name": "María", "..." : "..." },
      "workflow_run": {
        "id": "run-1-uuid",
        "workflow": { "id": "uuid-es", "name": "Enlace de Pago Enviado" }
      },
      "routing": {
        "processor_id": "abc-123-uuid",
        "processor_name": "Language Router",
        "matched_rule": { "id": "rule-2-uuid", "name": "Spanish leads", "position": 2 }
      },
      "index": 0
    },
    {
      "success": true,
      "lead": { "id": "lead-2-uuid", "first_name": "John", "..." : "..." },
      "workflow_run": {
        "id": "run-2-uuid",
        "workflow": { "id": "uuid-en", "name": "Payment Link Sent" }
      },
      "routing": {
        "processor_id": "abc-123-uuid",
        "processor_name": "Language Router",
        "matched_rule": { "id": "rule-1-uuid", "name": "English leads", "position": 1 }
      },
      "index": 1
    }
  ],
  "summary": {
    "total": 2,
    "created": 2,
    "failed": 0
  }
}

400 — Validation error

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

Other validation errors:

• "Processor is misconfigured: default workflow is inactive or deleted"
• "phone is required when assigning to a workflow with call steps"
• "Maximum 1000 leads per request"

401 — Authentication error

See Authentication.

404 — Processor not found

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

500 — Internal server error