Stages

See where a lead is in its workflow, and move it with the same rules the CRM applies.

GET Get the workflow

GET/v1/leads/{id}/stages

The lead's workflow and every stage in it, in order, with the current one marked and allowedFromCurrent saying where it can go next. Not cacheable; it depends on where the lead is right now.

Path parameters

idstring · uuidRequired

The lead's id.

Responses

200

The workflow, the current stage, and `data`, every stage in order.

404

No such lead in your organisation.

Example request

curl https://api.evacrm.co.uk/v1/leads/1e4e3f90-4384-42ce-90c3-540db5343964/stages \
  -H "Authorization: Bearer sk_..."

Example response · 200

{
  "lead": { "id": "1e4e3f90-…", "code": "L013898" },
  "workflow": { "id": "…", "name": "Leads" },
  "current": { "id": "90ee4027-…", "name": "Unassigned & Unappointed" },
  "data": [
    { "id": "90ee4027-…", "name": "Unassigned & Unappointed", "order": 1, "category": "Live", "current": true,  "allowedFromCurrent": false },
    { "id": "24c32379-…", "name": "Appointed", "order": 2, "category": "Live", "current": false, "allowedFromCurrent": true, "action": "Book appointment" },
    { "id": "bd7c3675-…", "name": "Sold",      "order": 3, "category": "Sold", "current": false, "allowedFromCurrent": true },
    { "id": "86b1e72e-…", "name": "Lost",      "order": 4, "category": "Lost", "current": false, "allowedFromCurrent": true }
  ]
}

allowedFromCurrent follows the rule the CRM's own stage dropdown uses: the transitions your administrator configured from the current stage. A workflow with no transitions configured at all is free-form, and every other stage is allowed.
action names what the CRM would prompt staff for on that move (an appointment, a note). The API moves the stage without it.
category is the stage's kind. Moving into a Sold or Lost category stage flips the lead's status.
description carries the administrator's note on the stage, when there is one.

Moves the lead. The move runs through the CRM, so everything the CRM does on a stage change happens: the stage history (marked as moved via the API), automatic tasks and notes configured on the stage, and sold/lost flags.

Path parameters

idstring · uuidRequired

The lead's id.

Request bodyapplication/json

stagestring · id or nameRequired

A stage from the workflow. Names match case-insensitively within the lead's own workflow.

Responses

200

Moved. Or, if the lead was already there, `changed: false` and nothing written.

404

No such lead in your organisation.

422

Unknown stage, or one not allowed from the current stage. `fields.stage` says which.

502

The CRM did not answer. Nothing changed; repeat the request.

Example request

curl -X PUT https://api.evacrm.co.uk/v1/leads/1e4e3f90-4384-42ce-90c3-540db5343964/stage \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "stage": "Appointed" }'

Example response · 200

{
  "changed": true,
  "lead": { "id": "1e4e3f90-…", "code": "L013898" },
  "from": { "id": "90ee4027-…", "name": "Unassigned & Unappointed" },
  "to":   { "id": "24c32379-…", "name": "Appointed" }
}

GET List workflows

GET/v1/leads/workflows

Every lead workflow in your organisation with its stages in order. This is where the names and ids for the stage and workflow filters on list leads come from. The same stage name often exists in more than one workflow; a filter by name covers all of them. Cacheable for five minutes; it changes only when someone edits the workflow settings in the CRM.

Responses

200

`data`, one entry per workflow, each with its `stages`.

Example request

curl https://api.evacrm.co.uk/v1/leads/workflows \
  -H "Authorization: Bearer sk_..."

Example response · 200

{
  "object": "list",
  "data": [
    {
      "id": "3f0c1b2e-…",
      "name": "T&K August 2023",
      "active": true,
      "default": true,
      "subWorkflow": false,
      "stages": [
        { "id": "90ee4027-…", "name": "Unassigned & Unappointed", "order": 1, "category": "Live", "description": null },
        { "id": "24c32379-…", "name": "Appointed", "order": 2, "category": "Live", "description": null },
        { "id": "bd7c3675-…", "name": "Sold", "order": 3, "category": "Sold", "description": null },
        { "id": "86b1e72e-…", "name": "Lost", "order": 4, "category": "Lost", "description": null }
      ]
    },
    {
      "id": "a91d…",
      "name": "T&K Lead Workflow",
      "active": true,
      "default": false,
      "subWorkflow": false,
      "stages": [
        { "id": "…", "name": "New", "order": 1, "category": "Live", "description": null },
        { "id": "…", "name": "Quote Sent", "order": 2, "category": "Live", "description": "Awaiting the customer" },
        { "id": "…", "name": "Sold", "order": 3, "category": "Sold", "description": null }
      ]
    }
  ]
}

default marks the workflow new leads start in. subWorkflow is a workflow a stage of another one hands off to; leads can still sit in it, and its stages filter like any other.

Stages

GET Get the workflow

PUT Move to a stage

GET List workflows

On this page