Skip to content
Documentation
English
Explore guides

For administrators

Leads

List, create, show, update, and delete leads, record custom field observations, and run qualification, disqualification, and conversion.

Contents

Before you start

Send Accept: application/json and Authorization: Bearer YOUR_TOKEN to https://{subdomain}.talentohq.com. See API for authentication.

Path and query identifiers are UUID strings.

Successful responses use 200. Validation failures use 422. Missing or invalid tokens, and records that cannot be found, use 401.

List all leads

GET /api/v3/leads

Parameter Type Description
status string Optional lead status.
employee_id string (UUID) Optional owner id.
lead_source_id string (UUID) Optional lead source id.
q string Optional search across company, contact, email, and phone.
custom_field_filters array Optional custom field filters.
custom_field_sort object Optional custom field sort.

Results are paginated. Pass page to move through pages of 50 records.

Response 200 

[
  {
    "id": "e269dd36-bb60-41ac-9242-6ec7afe4c640",
    "company_name": "Acme",
    "contact_name": "Alex Rivera",
    "email": "alex@acme.test",
    "phone": "555-0100",
    "title": "Operations lead",
    "campaign": "spring",
    "status": "new",
    "score": 42,
    "captured_at": "2026-03-01T09:00:00.000Z",
    "qualified_at": null,
    "converted_at": null,
    "disqualified_reason": null,
    "employee_id": "3ed57043-3894-43e9-a03b-69883506a3d6",
    "employee_name": "Employee name",
    "lead_source_id": "0f27fb66-20f6-4e9b-9d7f-664066c28f58",
    "lead_source_name": "Website",
    "customer_id": null,
    "contact_id": null,
    "opportunity_id": null,
    "custom_fields": [
      {
        "custom_field_definition_id": "1ae2fd31-da27-434e-92f2-b8f4480b57a8",
        "name": "Industry",
        "field_type": "string",
        "track_history": true,
        "value": "SaaS",
        "observed_at": "2026-03-01T10:00:00Z",
        "source": "api"
      }
    ]
  }
]

Create a lead

POST /api/v3/leads

Do not set status to qualified, disqualified, or converted here. Use the lifecycle endpoints instead.

Request

{
  "company_name": "Acme",
  "contact_name": "Alex Rivera",
  "email": "alex@acme.test",
  "phone": "555-0100",
  "title": "Operations lead",
  "campaign": "spring",
  "status": "new",
  "disqualified_reason": null,
  "captured_at": "2026-03-01T09:00:00.000Z",
  "employee_id": "3ed57043-3894-43e9-a03b-69883506a3d6",
  "lead_source_id": "0f27fb66-20f6-4e9b-9d7f-664066c28f58",
  "custom_fields": [
    {
      "custom_field_definition_id": "1ae2fd31-da27-434e-92f2-b8f4480b57a8",
      "value": "SaaS"
    }
  ]
}

Response 200 

{
  "id": "e269dd36-bb60-41ac-9242-6ec7afe4c640",
  "company_name": "Acme",
  "contact_name": "Alex Rivera",
  "email": "alex@acme.test",
  "phone": "555-0100",
  "title": "Operations lead",
  "campaign": "spring",
  "status": "new",
  "score": 42,
  "captured_at": "2026-03-01T09:00:00.000Z",
  "qualified_at": null,
  "converted_at": null,
  "disqualified_reason": null,
  "employee_id": "3ed57043-3894-43e9-a03b-69883506a3d6",
  "employee_name": "Employee name",
  "lead_source_id": "0f27fb66-20f6-4e9b-9d7f-664066c28f58",
  "lead_source_name": "Website",
  "customer_id": null,
  "contact_id": null,
  "opportunity_id": null,
  "custom_fields": [
    {
      "custom_field_definition_id": "1ae2fd31-da27-434e-92f2-b8f4480b57a8",
      "name": "Industry",
      "field_type": "string",
      "track_history": true,
      "value": "SaaS",
      "observed_at": "2026-03-01T10:00:00Z",
      "source": "api"
    }
  ]
}

Show a lead

GET /api/v3/leads/{lead_id}

Parameter Type Description
lead_id string (UUID) Lead id.

Response 200 

{
  "id": "e269dd36-bb60-41ac-9242-6ec7afe4c640",
  "company_name": "Acme",
  "contact_name": "Alex Rivera",
  "email": "alex@acme.test",
  "phone": "555-0100",
  "title": "Operations lead",
  "campaign": "spring",
  "status": "new",
  "score": 42,
  "captured_at": "2026-03-01T09:00:00.000Z",
  "qualified_at": null,
  "converted_at": null,
  "disqualified_reason": null,
  "employee_id": "3ed57043-3894-43e9-a03b-69883506a3d6",
  "employee_name": "Employee name",
  "lead_source_id": "0f27fb66-20f6-4e9b-9d7f-664066c28f58",
  "lead_source_name": "Website",
  "customer_id": null,
  "contact_id": null,
  "opportunity_id": null,
  "custom_fields": [
    {
      "custom_field_definition_id": "1ae2fd31-da27-434e-92f2-b8f4480b57a8",
      "name": "Industry",
      "field_type": "string",
      "track_history": true,
      "value": "SaaS",
      "observed_at": "2026-03-01T10:00:00Z",
      "source": "api"
    }
  ]
}

Update a lead

PUT /api/v3/leads/{lead_id}

Request

{
  "company_name": "Acme",
  "contact_name": "Alex Rivera",
  "email": "alex@acme.test",
  "employee_id": "3ed57043-3894-43e9-a03b-69883506a3d6",
  "lead_source_id": "0f27fb66-20f6-4e9b-9d7f-664066c28f58"
}

Response 200 

{
  "id": "e269dd36-bb60-41ac-9242-6ec7afe4c640",
  "company_name": "Acme",
  "contact_name": "Alex Rivera",
  "email": "alex@acme.test",
  "phone": "555-0100",
  "title": "Operations lead",
  "campaign": "spring",
  "status": "new",
  "score": 42,
  "captured_at": "2026-03-01T09:00:00.000Z",
  "qualified_at": null,
  "converted_at": null,
  "disqualified_reason": null,
  "employee_id": "3ed57043-3894-43e9-a03b-69883506a3d6",
  "employee_name": "Employee name",
  "lead_source_id": "0f27fb66-20f6-4e9b-9d7f-664066c28f58",
  "lead_source_name": "Website",
  "customer_id": null,
  "contact_id": null,
  "opportunity_id": null,
  "custom_fields": [
    {
      "custom_field_definition_id": "1ae2fd31-da27-434e-92f2-b8f4480b57a8",
      "name": "Industry",
      "field_type": "string",
      "track_history": true,
      "value": "SaaS",
      "observed_at": "2026-03-01T10:00:00Z",
      "source": "api"
    }
  ]
}

Delete a lead

DELETE /api/v3/leads/{lead_id}

Response 200 

{}

Custom field observations

Observations are nested under a lead.

List observations

GET /api/v3/leads/{lead_id}/custom_field_observations

Parameter Type Description
lead_id string (UUID) Lead id.
custom_field_definition_id string (UUID) Optional definition id.
observed_from string Optional ISO-8601 lower bound.
observed_to string Optional ISO-8601 upper bound.

Results are paginated. Pass page to move through pages of 50 records.

Response 200 

[
  {
    "id": "14902d70-c2f8-4796-8d33-cb996e1702b2",
    "custom_field_definition_id": "1ae2fd31-da27-434e-92f2-b8f4480b57a8",
    "name": "Industry",
    "field_type": "string",
    "value": "SaaS",
    "observed_at": "2026-03-01T10:00:00Z",
    "source": "api",
    "employee_id": "3ed57043-3894-43e9-a03b-69883506a3d6",
    "created_at": "2026-03-01T10:00:01Z"
  }
]

Show an observation

GET /api/v3/leads/{lead_id}/custom_field_observations/{custom_field_observation_id}

Parameter Type Description
lead_id string (UUID) Lead id.
custom_field_observation_id string (UUID) Observation id.

Response 200 

{
  "id": "14902d70-c2f8-4796-8d33-cb996e1702b2",
  "custom_field_definition_id": "1ae2fd31-da27-434e-92f2-b8f4480b57a8",
  "name": "Industry",
  "field_type": "string",
  "value": "SaaS",
  "observed_at": "2026-03-01T10:00:00Z",
  "source": "api",
  "employee_id": "3ed57043-3894-43e9-a03b-69883506a3d6",
  "created_at": "2026-03-01T10:00:01Z"
}

Create an observation

POST /api/v3/leads/{lead_id}/custom_field_observations

A conflicting idempotency_key returns 409.

Request

{
  "custom_field_definition_id": "1ae2fd31-da27-434e-92f2-b8f4480b57a8",
  "value": "SaaS",
  "observed_at": "2026-03-01T10:00:00Z",
  "source": "api",
  "idempotency_key": "obs-1"
}

Response 200 

{
  "id": "14902d70-c2f8-4796-8d33-cb996e1702b2",
  "custom_field_definition_id": "1ae2fd31-da27-434e-92f2-b8f4480b57a8",
  "name": "Industry",
  "field_type": "string",
  "value": "SaaS",
  "observed_at": "2026-03-01T10:00:00Z",
  "source": "api",
  "employee_id": "3ed57043-3894-43e9-a03b-69883506a3d6",
  "created_at": "2026-03-01T10:00:01Z"
}

Qualify, disqualify, and convert

These endpoints change lead lifecycle status. They return the lead object.

Qualify

POST /api/v3/leads/{lead_id}/qualification

Request

{
  "employee_id": "3ed57043-3894-43e9-a03b-69883506a3d6",
  "note": "Budget confirmed"
}

Response 200 

{
  "id": "e269dd36-bb60-41ac-9242-6ec7afe4c640",
  "company_name": "Acme",
  "contact_name": "Alex Rivera",
  "email": "alex@acme.test",
  "phone": "555-0100",
  "title": "Operations lead",
  "campaign": "spring",
  "status": "qualified",
  "score": 42,
  "captured_at": "2026-03-01T09:00:00.000Z",
  "qualified_at": "2026-03-02T09:00:00.000Z",
  "converted_at": null,
  "disqualified_reason": null,
  "employee_id": "3ed57043-3894-43e9-a03b-69883506a3d6",
  "employee_name": "Employee name",
  "lead_source_id": "0f27fb66-20f6-4e9b-9d7f-664066c28f58",
  "lead_source_name": "Website",
  "customer_id": null,
  "contact_id": null,
  "opportunity_id": null,
  "custom_fields": [
    {
      "custom_field_definition_id": "1ae2fd31-da27-434e-92f2-b8f4480b57a8",
      "name": "Industry",
      "field_type": "string",
      "track_history": true,
      "value": "SaaS",
      "observed_at": "2026-03-01T10:00:00Z",
      "source": "api"
    }
  ]
}

Disqualify

POST /api/v3/leads/{lead_id}/disqualification

Request

{
  "reason": "no_budget",
  "note": "Paused until next year"
}

Response 200 

{
  "id": "e269dd36-bb60-41ac-9242-6ec7afe4c640",
  "company_name": "Acme",
  "contact_name": "Alex Rivera",
  "email": "alex@acme.test",
  "phone": "555-0100",
  "title": "Operations lead",
  "campaign": "spring",
  "status": "disqualified",
  "score": 42,
  "captured_at": "2026-03-01T09:00:00.000Z",
  "qualified_at": null,
  "converted_at": null,
  "disqualified_reason": "no_budget",
  "employee_id": "3ed57043-3894-43e9-a03b-69883506a3d6",
  "employee_name": "Employee name",
  "lead_source_id": "0f27fb66-20f6-4e9b-9d7f-664066c28f58",
  "lead_source_name": "Website",
  "customer_id": null,
  "contact_id": null,
  "opportunity_id": null,
  "custom_fields": [
    {
      "custom_field_definition_id": "1ae2fd31-da27-434e-92f2-b8f4480b57a8",
      "name": "Industry",
      "field_type": "string",
      "track_history": true,
      "value": "SaaS",
      "observed_at": "2026-03-01T10:00:00Z",
      "source": "api"
    }
  ]
}

Convert

POST /api/v3/leads/{lead_id}/conversion

Request

{
  "customer_id": "55129d78-0281-4e72-aca1-8d547a2df814",
  "contact_id": "1ae2fd31-da27-434e-92f2-b8f4480b57a8",
  "opportunity_id": null,
  "create_opportunity": true,
  "opportunity_name": "Acme rollout",
  "expected_amount": 12000,
  "amount_period": "one_off"
}

Response 200 

{
  "id": "e269dd36-bb60-41ac-9242-6ec7afe4c640",
  "company_name": "Acme",
  "contact_name": "Alex Rivera",
  "email": "alex@acme.test",
  "phone": "555-0100",
  "title": "Operations lead",
  "campaign": "spring",
  "status": "converted",
  "score": 42,
  "captured_at": "2026-03-01T09:00:00.000Z",
  "qualified_at": null,
  "converted_at": "2026-03-03T09:00:00.000Z",
  "disqualified_reason": null,
  "employee_id": "3ed57043-3894-43e9-a03b-69883506a3d6",
  "employee_name": "Employee name",
  "lead_source_id": "0f27fb66-20f6-4e9b-9d7f-664066c28f58",
  "lead_source_name": "Website",
  "customer_id": "55129d78-0281-4e72-aca1-8d547a2df814",
  "contact_id": "1ae2fd31-da27-434e-92f2-b8f4480b57a8",
  "opportunity_id": "8d429d99-fbd4-4196-a9ac-94f1dc481344",
  "custom_fields": [
    {
      "custom_field_definition_id": "1ae2fd31-da27-434e-92f2-b8f4480b57a8",
      "name": "Industry",
      "field_type": "string",
      "track_history": true,
      "value": "SaaS",
      "observed_at": "2026-03-01T10:00:00Z",
      "source": "api"
    }
  ]
}