WorkloomDevelopers
v1Get an API key
Reference/Pipelines, team and fields

Pipelines, team and fields

The things records point at: your pipelines and their stages, the reasons a deal closes, your teammates and the fields you added. Read these to know which stage keys, reason keys, owner ids and field keys are valid.

Scopes: deals:read, team:read, contacts:read, companies:read to read. It is read-only.

The pipeline object

idstring

The pipeline key. Deals carry it as pipeline_id.

namestring

Its name.

is_defaultboolean

Whether deals land here unless told otherwise.

stagesarray of Stage

Every stage, in order. key is what deals carry as stage and what the move endpoint takes.

The pipeline object
{
  "id": "default",
  "name": "New business",
  "is_default": true,
  "stages": [
    {
      "key": "engaged",
      "label": "Engaged",
      "status": "open",
      "phase": "prospecting",
      "probability": 5,
      "required_fields": []
    },
    {
      "key": "qualified",
      "label": "Qualified",
      "status": "open",
      "phase": "prospecting",
      "probability": 10,
      "required_fields": []
    },
    {
      "key": "discovery",
      "label": "Discovery",
      "status": "open",
      "phase": "opportunity",
      "probability": 20,
      "required_fields": [
        "amount",
        "expected_close_date"
      ]
    },
    {
      "key": "proposal",
      "label": "Proposal",
      "status": "open",
      "phase": "opportunity",
      "probability": 50,
      "required_fields": [
        "amount",
        "expected_close_date"
      ]
    },
    {
      "key": "commit",
      "label": "Commit",
      "status": "open",
      "phase": "opportunity",
      "probability": 80,
      "required_fields": [
        "amount",
        "expected_close_date"
      ]
    },
    {
      "key": "won",
      "label": "Won",
      "status": "won",
      "phase": "closed",
      "probability": 100,
      "required_fields": [
        "amount"
      ]
    },
    {
      "key": "lost",
      "label": "Lost",
      "status": "lost",
      "phase": "closed",
      "probability": 0,
      "required_fields": []
    }
  ]
}

The seat object

idstring

The seat id. Records carry it as owner_seat_id.

namestring, nullable

Their name.

emailstring, nullable

Their sign-in email. Null for a service account, and for a key acting for someone other than an admin.

kindstring

member is a teammate; service a service account; external someone from outside the company. One of member, service, external, operator.

rolestring, nullable

Their role in words, for example Admin, Manager or Rep.

statusstring

Only an active seat can own records. One of active, invited, suspended, ended.

team_idstring, nullable

Their team, if any.

The seat object
{
  "id": "66e0f1a2e4b0a1b2c3d40a0b",
  "name": "Asha Rao",
  "email": "asha@brightpath.example",
  "kind": "member",
  "role": "Rep",
  "status": "active",
  "team_id": null
}

The custom field object

keystring

The key. Values sit under custom_fields.<key>.

labelstring

Its name in Workloom.

objectstring

Which kind of record it belongs to. One of contact, company, deal.

typestring

text, textarea, number, currency, date, boolean, select, multiselect, url, email, user, relation or formula.

optionsarray of string

The choices, for select and multiselect.

read_onlyboolean

True for formula fields and archived fields: they cannot be written.

The custom field object
{
  "key": "region",
  "label": "Region",
  "object": "contact",
  "type": "select",
  "options": [
    "North",
    "South",
    "West"
  ],
  "read_only": false
}

Endpoints

GET/pipelines

List pipelines and stages

Every pipeline with its stages in board order, and the reasons a deal can be lost, won or parked. Use the stage keys for stage and the reason keys for reason_code.

Scope: deals:read
Errors
400

invalid_request, unknown_fields, reason_required or unsupported_version.

401

authentication_required or invalid_key.

403

missing_scope, forbidden, seat_inactive or organisation_inactive.

429

rate_limited. Wait Retry-After seconds.

500

internal_error.

List pipelines and stages
curl "https://api.useworkloom.com/api/public/v1/pipelines" \
  -H "Authorization: Bearer $WORKLOOM_KEY"
const res = await fetch("https://api.useworkloom.com/api/public/v1/pipelines", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.WORKLOOM_KEY}`
  }
});
const data = await res.json();
import os, requests

res = requests.get(
    "https://api.useworkloom.com/api/public/v1/pipelines",
    headers={"Authorization": f"Bearer {os.environ['WORKLOOM_KEY']}"},
)
data = res.json()
Response
{
  "data": [
    {
      "id": "default",
      "name": "New business",
      "is_default": true,
      "stages": [
        {
          "key": "engaged",
          "label": "Engaged",
          "status": "open",
          "phase": "prospecting",
          "probability": 5,
          "required_fields": []
        },
        {
          "key": "qualified",
          "label": "Qualified",
          "status": "open",
          "phase": "prospecting",
          "probability": 10,
          "required_fields": []
        },
        {
          "key": "discovery",
          "label": "Discovery",
          "status": "open",
          "phase": "opportunity",
          "probability": 20,
          "required_fields": [
            "amount",
            "expected_close_date"
          ]
        },
        {
          "key": "proposal",
          "label": "Proposal",
          "status": "open",
          "phase": "opportunity",
          "probability": 50,
          "required_fields": [
            "amount",
            "expected_close_date"
          ]
        },
        {
          "key": "commit",
          "label": "Commit",
          "status": "open",
          "phase": "opportunity",
          "probability": 80,
          "required_fields": [
            "amount",
            "expected_close_date"
          ]
        },
        {
          "key": "won",
          "label": "Won",
          "status": "won",
          "phase": "closed",
          "probability": 100,
          "required_fields": [
            "amount"
          ]
        },
        {
          "key": "lost",
          "label": "Lost",
          "status": "lost",
          "phase": "closed",
          "probability": 0,
          "required_fields": []
        }
      ]
    }
  ],
  "reasons": {
    "lost": [
      {
        "key": "no_budget",
        "label": "No budget"
      },
      {
        "key": "competitor",
        "label": "Chose a competitor"
      }
    ],
    "won": [
      {
        "key": "price",
        "label": "Best price"
      }
    ],
    "parked": [
      {
        "key": "bad_timing",
        "label": "Bad timing"
      }
    ]
  }
}
200 OKsample
GET/seats

List teammates

Everyone with a seat: teammates, service accounts and people from outside the company. owner_seat_id on a record is one of these ids. Emails are shown to a key acting for the workspace or for an admin.

Scope: team:read
Query parameters
statusstring

Only seats in this state: active, invited, suspended or ended.

limitinteger

How many to return, 1 to 100. Default 25.

cursorstring

The next_cursor from the previous page.

Errors
400

invalid_request, unknown_fields, reason_required or unsupported_version.

401

authentication_required or invalid_key.

403

missing_scope, forbidden, seat_inactive or organisation_inactive.

429

rate_limited. Wait Retry-After seconds.

500

internal_error.

List teammates
curl "https://api.useworkloom.com/api/public/v1/seats?status=active&limit=25" \
  -H "Authorization: Bearer $WORKLOOM_KEY"
const res = await fetch("https://api.useworkloom.com/api/public/v1/seats?status=active&limit=25", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.WORKLOOM_KEY}`
  }
});
const data = await res.json();
import os, requests

res = requests.get(
    "https://api.useworkloom.com/api/public/v1/seats?status=active&limit=25",
    headers={"Authorization": f"Bearer {os.environ['WORKLOOM_KEY']}"},
)
data = res.json()
Response
{
  "data": [
    {
      "id": "66e0f1a2e4b0a1b2c3d40a0b",
      "name": "Asha Rao",
      "email": "asha@brightpath.example",
      "kind": "member",
      "role": "Rep",
      "status": "active",
      "team_id": null
    }
  ],
  "has_more": true,
  "next_cursor": "66e0f1a2e4b0a1b2c3d40a0b"
}
200 OKsample
GET/custom-fields

List your own fields

The fields your workspace added in Settings › Data model, with their keys, labels and types. Records carry their values under custom_fields. Needs any one of the read scopes. Needs one of the contacts:read, companies:read, deals:read scopes.

Scope: contacts:read or companies:read or deals:read
Query parameters
objectstring

contact, company or deal. Omit for all three.

Errors
400

invalid_request, unknown_fields, reason_required or unsupported_version.

401

authentication_required or invalid_key.

403

missing_scope, forbidden, seat_inactive or organisation_inactive.

429

rate_limited. Wait Retry-After seconds.

500

internal_error.

List your own fields
curl "https://api.useworkloom.com/api/public/v1/custom-fields?object=contact" \
  -H "Authorization: Bearer $WORKLOOM_KEY"
const res = await fetch("https://api.useworkloom.com/api/public/v1/custom-fields?object=contact", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.WORKLOOM_KEY}`
  }
});
const data = await res.json();
import os, requests

res = requests.get(
    "https://api.useworkloom.com/api/public/v1/custom-fields?object=contact",
    headers={"Authorization": f"Bearer {os.environ['WORKLOOM_KEY']}"},
)
data = res.json()
Response
{
  "data": [
    {
      "key": "region",
      "label": "Region",
      "object": "contact",
      "type": "select",
      "options": [
        "North",
        "South",
        "West"
      ],
      "read_only": false
    }
  ]
}
200 OKsample
Was this page useful?