Pipeline stages

Your contact board is made of stages, like New lead, Contacted and Won. A contact sits in one stage at a time: its pipeline_stage holds the stage’s id. To move a contact, send a stage id as pipeline_stage when you update the contact. These routes tell you which ids exist and let you change them.

Stages are grouped into pipelines. Every account has a main pipeline (id default) and can add more. Stage ids are unique across the whole account, so a stage id alone says which pipeline a contact is in. A contact whose stage id matches no stage shows in the main pipeline. You can have up to 50 stages across all your pipelines, and up to 20 pipelines counting the main one.

Until you change your stages, your board uses the built-in ones: new_lead, contacted, interested, qualified, won and lost. A contact with no stage counts as new_lead. The value off_board is reserved: it takes contacts off the board without deleting them.

Removing a stage never deletes contacts and never leaves them on a stage that is gone. A change that would remove a stage still holding contacts is refused with 409 until you move them out.

#The stage object

idstring: The stage id. This is the value a contact’s pipeline_stage holds. Up to 60 characters. New ids are made by Ready from the stage name, for example hot_leads.
namestring: The name on the board. Up to 40 characters.
colorstring: A hex color like #3B82F6. Anything else is saved as #94A3B8.
pipeline_id, pipeline_namestring: The pipeline the stage belongs to. Only on stages in the top level data list.

#The pipeline object

idstring: default for the main pipeline, otherwise an id like p_3f9a1c2e.
namestring: The pipeline’s name. The main one is called Main pipeline until you rename it. Up to 60 characters.
is_defaultboolean: true for the main pipeline. It can be renamed but not deleted.
stagesobject[]: Its stages in board order, each with id, name and color.

#List stages

Your saved stage list and your pipelines. Any team member can read it.

Returns

pipelinesobject[]: Read stage ids from pipelines[].stages. Your stages split into pipeline objects, main first. Always filled in, with the built-in stages when data is null.
dataobject[] or null: Your saved list: every stage across all pipelines, main pipeline first. null until you change your stages: you are on the built-in ones.

curl "https://api.tryready.com/pipeline-stages" \
  -H "X-API-Key: $READY_API_KEY"

const res = await fetch('https://api.tryready.com/pipeline-stages', {
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
  },
});
const json = await res.json().catch(() => ({}));
if (!res.ok || json.success === false) {
  throw new Error(`${res.status}${json.error_code || json.code ? ' ' + (json.error_code || json.code) : ''}: ${json.error || json.message || res.statusText}`);
}

import os, requests

r = requests.get(
    "https://api.tryready.com/pipeline-stages",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    timeout=30,
)
data = r.json() if r.headers.get("content-type", "").startswith("application/json") else {}
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code") or ""}: {data.get("error") or data.get("message") or r.reason}')

Returns:

{
  "success": true,
  "data": [
    { "id": "new_lead", "name": "New lead", "color": "#94A3B8", "pipeline_id": "default", "pipeline_name": "Main pipeline" },
    { "id": "contacted", "name": "Contacted", "color": "#3B82F6", "pipeline_id": "default", "pipeline_name": "Main pipeline" },
    { "id": "won", "name": "Won", "color": "#22C55E", "pipeline_id": "default", "pipeline_name": "Main pipeline" }
  ],
  "pipelines": [
    {
      "id": "default",
      "name": "Main pipeline",
      "is_default": true,
      "stages": [
        { "id": "new_lead", "name": "New lead", "color": "#94A3B8" },
        { "id": "contacted", "name": "Contacted", "color": "#3B82F6" },
        { "id": "won", "name": "Won", "color": "#22C55E" }
      ]
    }
  ]
}

#Add stages

Adds stages to the end of your main pipeline. It only adds: it never removes, renames or reorders a stage, so no contact is moved. To remove or change stages, update a pipeline. A stage whose id or name (any case) is already there is skipped, so sending the same request twice adds nothing. Needs the edit_contacts permission.

Parameters

appendobject[]Required: The stages to add, each {"name": "...", "color": "..."}. Leave out id and Ready makes one from the name. An id you send is kept, unless it is off_board or repeated in the list.
stagesobject[]: Rarely needed. The list to start from. Used only if you never changed your stages; otherwise the saved list is used. Without it, the built-in stages are the start.

Returns data and pipelines as List stages does.

Errors

HTTP	Code	When
400	`invalid_stages`	No `append` list, or the result would have more than 50 stages.
400	`invalid_field`	`append` or `stages` isn’t a list.
409	`stages_changed`	Your stages changed while this was saving. Read them again and retry.

curl -X PUT "https://api.tryready.com/pipeline-stages" \
  -H "X-API-Key: $READY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "append": [
      {
        "name": "Hot leads",
        "color": "#F97316"
      }
    ]
  }'

const res = await fetch('https://api.tryready.com/pipeline-stages', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "append": [
      {
        "name": "Hot leads",
        "color": "#F97316"
      }
    ]
  }),
});
const json = await res.json().catch(() => ({}));
if (!res.ok || json.success === false) {
  throw new Error(`${res.status}${json.error_code || json.code ? ' ' + (json.error_code || json.code) : ''}: ${json.error || json.message || res.statusText}`);
}

import os, requests

r = requests.put(
    "https://api.tryready.com/pipeline-stages",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    json={
        "append": [
            {
                "name": "Hot leads",
                "color": "#F97316"
            }
        ]
    },
    timeout=30,
)
data = r.json() if r.headers.get("content-type", "").startswith("application/json") else {}
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code") or ""}: {data.get("error") or data.get("message") or r.reason}')

#Count contacts per stage

How many contacts are in each stage. Spam and deleted contacts are not counted. The numbers can be up to 90 seconds old. Needs the view_reports permission, and a team seat that sees only its assigned contacts is refused.

Returns

by_stageobject: Stage id to count. Includes any stage id a contact holds, even one no longer on the board. Contacts with no stage are counted under new_lead.
totalinteger: The sum of by_stage.

Errors

HTTP	Code	When
403	`permission_denied`	Your seat lacks `view_reports`.
403	`report_scope_forbidden`	Your seat sees only its assigned contacts.
503	`report_unavailable`	The counts couldn’t be loaded. Retry in a minute.

curl "https://api.tryready.com/pipeline-stages/counts" \
  -H "X-API-Key: $READY_API_KEY"

const res = await fetch('https://api.tryready.com/pipeline-stages/counts', {
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
  },
});
const json = await res.json().catch(() => ({}));
if (!res.ok || json.success === false) {
  throw new Error(`${res.status}${json.error_code || json.code ? ' ' + (json.error_code || json.code) : ''}: ${json.error || json.message || res.statusText}`);
}

import os, requests

r = requests.get(
    "https://api.tryready.com/pipeline-stages/counts",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    timeout=30,
)
data = r.json() if r.headers.get("content-type", "").startswith("application/json") else {}
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code") or ""}: {data.get("error") or data.get("message") or r.reason}')

Returns:

{
  "success": true,
  "by_stage": { "new_lead": 812, "contacted": 240, "won": 37 },
  "total": 1089
}

#Move every contact out of a stage

Moves all your contacts in one stage to another stage, or off the board. This can’t be undone, and contacts moved into a stage that already has contacts can’t be told apart afterwards. Read the stage’s count with Count contacts per stage first. Do this before you remove a stage that still has contacts. Sending it again moves 0. Needs the edit_contacts permission, and a team seat that sees only its assigned contacts is refused.

Parameters

fromstringRequired: The stage id to empty. It doesn’t have to be on the board, so you can also clear an old id. new_lead includes contacts with no stage.
tostringRequired: A stage id on your board, or off_board to take the contacts off the board and keep them. The same value as from moves nothing.

Returns

movedinteger: How many contacts were moved.

Errors

HTTP	Code	When
400	`invalid_stages`	`from` or `to` is missing, or `to` isn’t a stage on your board.
400	`invalid_field`	`from` or `to` is a list or an object.
403	`report_scope_forbidden`	Your seat sees only its assigned contacts.

curl -X POST "https://api.tryready.com/pipeline-stages/reassign" \
  -H "X-API-Key: $READY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "interested",
    "to": "qualified"
  }'

const res = await fetch('https://api.tryready.com/pipeline-stages/reassign', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "from": "interested",
    "to": "qualified"
  }),
});
const json = await res.json().catch(() => ({}));
if (!res.ok || json.success === false) {
  throw new Error(`${res.status}${json.error_code || json.code ? ' ' + (json.error_code || json.code) : ''}: ${json.error || json.message || res.statusText}`);
}

import os, requests

r = requests.post(
    "https://api.tryready.com/pipeline-stages/reassign",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    json={
        "from": "interested",
        "to": "qualified"
    },
    timeout=30,
)
data = r.json() if r.headers.get("content-type", "").startswith("application/json") else {}
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code") or ""}: {data.get("error") or data.get("message") or r.reason}')

Returns:

{
  "success": true,
  "moved": 42
}

#List pipelines

Every pipeline with its stages, main pipeline first. Any team member can read it.

Returns a list of pipeline objects in data.

curl "https://api.tryready.com/pipeline-stages/pipelines" \
  -H "X-API-Key: $READY_API_KEY"

const res = await fetch('https://api.tryready.com/pipeline-stages/pipelines', {
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
  },
});
const json = await res.json().catch(() => ({}));
if (!res.ok || json.success === false) {
  throw new Error(`${res.status}${json.error_code || json.code ? ' ' + (json.error_code || json.code) : ''}: ${json.error || json.message || res.statusText}`);
}

import os, requests

r = requests.get(
    "https://api.tryready.com/pipeline-stages/pipelines",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    timeout=30,
)
data = r.json() if r.headers.get("content-type", "").startswith("application/json") else {}
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code") or ""}: {data.get("error") or data.get("message") or r.reason}')

Returns:

{
  "success": true,
  "data": [
    {
      "id": "default",
      "name": "Main pipeline",
      "is_default": true,
      "stages": [
        { "id": "new_lead", "name": "New lead", "color": "#94A3B8" },
        { "id": "won", "name": "Won", "color": "#22C55E" }
      ]
    },
    {
      "id": "p_3f9a1c2e",
      "name": "Buyers",
      "is_default": false,
      "stages": [
        { "id": "new_lead_2", "name": "New lead", "color": "#94A3B8" },
        { "id": "closed", "name": "Closed", "color": "#22C55E" }
      ]
    }
  ]
}

#Create a pipeline

Adds a pipeline. Ready makes every stage id from the stage name, so two pipelines can both have a "New lead" stage with different ids. Returns 201. Needs the edit_contacts permission.

Parameters

namestringRequired: Up to 60 characters.
stagesobject[]: Its stages in order, each {"name": "...", "color": "..."}. Any id you send is ignored. Without a list you get New lead, Contacted, Qualified, Won and Lost.
Idempotency-Keystring · header: A retry with the same key returns the first answer instead of making a second pipeline.

Returns data and pipelines as List stages does, plus pipeline_id, the new pipeline’s id.

Errors

HTTP	Code	When
400	`invalid_pipeline`	No name, no stage with a name, already 20 pipelines, or more than 50 stages in total.
400	`invalid_field`	`name` is a list or an object.
409	`stages_changed`	Your stages changed while this was saving. Read them again and retry.

curl -X POST "https://api.tryready.com/pipeline-stages/pipelines" \
  -H "X-API-Key: $READY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Buyers",
    "stages": [
      {
        "name": "New lead",
        "color": "#94A3B8"
      },
      {
        "name": "Closed",
        "color": "#22C55E"
      }
    ]
  }'

const res = await fetch('https://api.tryready.com/pipeline-stages/pipelines', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Buyers",
    "stages": [
      {
        "name": "New lead",
        "color": "#94A3B8"
      },
      {
        "name": "Closed",
        "color": "#22C55E"
      }
    ]
  }),
});
const json = await res.json().catch(() => ({}));
if (!res.ok || json.success === false) {
  throw new Error(`${res.status}${json.error_code || json.code ? ' ' + (json.error_code || json.code) : ''}: ${json.error || json.message || res.statusText}`);
}

import os, requests

r = requests.post(
    "https://api.tryready.com/pipeline-stages/pipelines",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    json={
        "name": "Buyers",
        "stages": [
            {
                "name": "New lead",
                "color": "#94A3B8"
            },
            {
                "name": "Closed",
                "color": "#22C55E"
            }
        ]
    },
    timeout=30,
)
data = r.json() if r.headers.get("content-type", "").startswith("application/json") else {}
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code") or ""}: {data.get("error") or data.get("message") or r.reason}')

#Update a pipeline

Renames a pipeline, replaces its stages, or both. Send the full stage list you want: stages you leave out are removed. Sending the same request again saves the same thing. Needs the edit_contacts permission.

Parameters

idstring · pathRequired: The pipeline id. default is the main pipeline.
namestring: The new name, up to 60 characters.
stagesobject[]: The pipeline’s new stages in board order, each {"id": "...", "name": "...", "color": "..."}.
Keeping, adding and removing stages
Send a stage’s current id to keep it (with a new name or color if you like). A row without an id, or with an id from another pipeline, is a new stage and gets a new id. Rows without a name are skipped. A stage of this pipeline that you leave out is removed. If any removed stage still has contacts, nothing is saved and you get 409 with that stage’s id and count: move its contacts first, then retry. Contacts are never moved for you here. Spam and deleted contacts don’t block a removal; they keep the old stage id.

Returns data and pipelines as List stages does.

Errors

HTTP	Code	When
400	`invalid_pipeline`	An empty name, no stage left, or more than 50 stages in total.
400	`invalid_field`	`stages` isn’t a list, or `name` is a list or an object.
404	`PIPELINE_NOT_FOUND`	No pipeline with this id on your account.
409	`stage_has_contacts`	A removed stage still has contacts. The body adds `stage_id` and `count`.
409	`stages_changed`	Your stages changed while this was saving. Read them again and retry.

curl -X PUT "https://api.tryready.com/pipeline-stages/pipelines/p_3f9a1c2e" \
  -H "X-API-Key: $READY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Home buyers",
    "stages": [
      {
        "id": "new_lead_2",
        "name": "New lead",
        "color": "#94A3B8"
      },
      {
        "name": "Touring",
        "color": "#3B82F6"
      },
      {
        "id": "closed",
        "name": "Closed",
        "color": "#22C55E"
      }
    ]
  }'

const res = await fetch('https://api.tryready.com/pipeline-stages/pipelines/p_3f9a1c2e', {
  method: 'PUT',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "Home buyers",
    "stages": [
      {
        "id": "new_lead_2",
        "name": "New lead",
        "color": "#94A3B8"
      },
      {
        "name": "Touring",
        "color": "#3B82F6"
      },
      {
        "id": "closed",
        "name": "Closed",
        "color": "#22C55E"
      }
    ]
  }),
});
const json = await res.json().catch(() => ({}));
if (!res.ok || json.success === false) {
  throw new Error(`${res.status}${json.error_code || json.code ? ' ' + (json.error_code || json.code) : ''}: ${json.error || json.message || res.statusText}`);
}

import os, requests

r = requests.put(
    "https://api.tryready.com/pipeline-stages/pipelines/p_3f9a1c2e",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    json={
        "name": "Home buyers",
        "stages": [
            {
                "id": "new_lead_2",
                "name": "New lead",
                "color": "#94A3B8"
            },
            {
                "name": "Touring",
                "color": "#3B82F6"
            },
            {
                "id": "closed",
                "name": "Closed",
                "color": "#22C55E"
            }
        ]
    },
    timeout=30,
)
data = r.json() if r.headers.get("content-type", "").startswith("application/json") else {}
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code") or ""}: {data.get("error") or data.get("message") or r.reason}')

Returns:

{
  "success": false,
  "error": "Move the 3 contacts out of \"Touring\" before you remove it.",
  "stage_id": "touring",
  "count": 3
}

#Delete a pipeline

Removes a pipeline and its stages. The main pipeline can’t be deleted. If the pipeline still has contacts, you must say where they go with move_to; without it you get 409 with the count and nothing changes. The move and the delete happen together or not at all. Needs the edit_contacts permission, and a team seat that sees only its assigned contacts can’t delete a pipeline that has contacts.

Parameters

idstring · pathRequired: The pipeline id.
move_tostring · query: A stage id in another pipeline, or off_board to take the contacts off the board and keep them.

Returns data and pipelines as List stages does, plus moved, how many contacts were moved.

Errors

HTTP	Code	When
400	`invalid_pipeline`	The id is `default`.
400	`invalid_move_to`	`move_to` isn’t a stage in another pipeline or `off_board`.
400	`invalid_field`	`move_to` is sent more than once.
403	`report_scope_forbidden`	The pipeline has contacts and your seat sees only its assigned contacts.
404	`PIPELINE_NOT_FOUND`	No pipeline with this id on your account, including one you already deleted.
409	`pipeline_has_contacts`	The pipeline has contacts and you sent no `move_to`. The body adds `count`.
409	`stages_changed`	Your stages changed while this was saving. Nothing was moved. Retry.

curl -X DELETE "https://api.tryready.com/pipeline-stages/pipelines/p_3f9a1c2e?move_to=new_lead" \
  -H "X-API-Key: $READY_API_KEY"

const res = await fetch('https://api.tryready.com/pipeline-stages/pipelines/p_3f9a1c2e?move_to=new_lead', {
  method: 'DELETE',
  headers: {
    'X-API-Key': process.env.READY_API_KEY,
  },
});
const json = await res.json().catch(() => ({}));
if (!res.ok || json.success === false) {
  throw new Error(`${res.status}${json.error_code || json.code ? ' ' + (json.error_code || json.code) : ''}: ${json.error || json.message || res.statusText}`);
}

import os, requests

r = requests.delete(
    "https://api.tryready.com/pipeline-stages/pipelines/p_3f9a1c2e",
    headers={"X-API-Key": os.environ["READY_API_KEY"]},
    params={
        "move_to": "new_lead"
    },
    timeout=30,
)
data = r.json() if r.headers.get("content-type", "").startswith("application/json") else {}
if not r.ok or data.get("success") is False:
    raise RuntimeError(f'{r.status_code} {data.get("error_code") or data.get("code") or ""}: {data.get("error") or data.get("message") or r.reason}')