Skip to content
ThreadkiteThreadkite Docs

Start a new chapter

POST
/v1/threads/{id}/chapters
curl --request POST \
  --url https://api.threadkite.app/v1/threads/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/chapters \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "close": { "outcome": "deal", "lostReasonId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "note": "example", "valueMinor": 1899500 }, "carryItems": false }'

Starts a new chapter in the thread and opens it. On a thread that is still open, give close to say how the current chapter ended first. carryItems starts it with what the current chapter was about.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string format: uuid

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

Start a new chapter in the thread

object
close

How the current chapter ended, when the thread is still open (it is closed first). Not needed when the thread is Done

object
outcome
required

deal (Won), lost (needs a lost reason), none or no_reply

string
Allowed values: deal lost none no_reply
lostReasonId

Required when the outcome is lost, unless your organisation has no lost reasons: then give a note saying why instead

string format: uuid
note
string
<= 500 characters
valueMinor

Sale value for Won, in minor units of the organisation’s currency

integer
<= 100000000000

Example 

1899500
carryItems

Start the new chapter with what the current one was about (“still looking, just later”); otherwise it starts empty

boolean

Responses

Section titled “Responses”

200

Section titled “200”
Media typeapplication/json
object
id
required
string format: uuid
inbox
required

The inbox it is in

object
id
required
string format: uuid
name
required
string
type
required
string
Allowed values: sales service parts bodyshop general
contact
required
One of:
object
id
required
string format: uuid
name
required
string
nullable
email
required
string
nullable
phoneE164
required
string
nullable
avatarUrl
required

Their picture, uploaded by your team; null when none

string
nullable
company
required
One of:
object
id
required
string format: uuid
name
required
string
avatarUrl
required

The company’s picture (uploaded, or its website’s icon); null when none

string
nullable
status
required

As the register gives it (active, dissolved, liquidation…); null when not known

string
nullable
state
required
string
Allowed values: open snoozed done spam
stage
required

The current chapter’s, derived from its activity, never set by hand

string
Allowed values: new contacted booked attended won lost
chapter
required

The current chapter (the latest)

object
id
required
string format: uuid
number
required

1, 2, 3 within the thread

integer
>= -9007199254740991 <= 9007199254740991
startedAt
required
string format: date-time
startedBy
required

What started it: first (the thread began), lead (a new lead on a Done thread), period (they wrote long after it closed), staff, api, flow, or migration

string
Allowed values: first lead period staff api flow migration
closedAt
required

Null while open

string format: date-time
nullable
outcome
required
string
nullable
Allowed values: deal lost none no_reply
previousChapter
required
One of:
object
id
required
string format: uuid
number
required

1, 2, 3 within the thread

integer
>= -9007199254740991 <= 9007199254740991
startedAt
required
string format: date-time
startedBy
required

What started it: first (the thread began), lead (a new lead on a Done thread), period (they wrote long after it closed), staff, api, flow, or migration

string
Allowed values: first lead period staff api flow migration
closedAt
required

Null while open

string format: date-time
nullable
outcome
required
string
nullable
Allowed values: deal lost none no_reply
nextAppointment
required
One of:
object
id
required
string format: uuid
type
required

The appointment type id

string
typeLabel
required
string
startsAt
required
string format: date-time
timeZone
required

The time zone it is written in

string
waiting
required

Who the thread is waiting on

string
Allowed values: us customer none
score
required
One of:
object
band
required

Hot, Warm or Cold

string
Allowed values: hot warm cold
reasons
required

Why, up to three, the strongest first

Array<string>
scoredAt
required
string format: date-time
nullable
waitingSince
required
string format: date-time
nullable
noReplyNeededAt
required

When someone said the contact’s latest messages need no reply (POST /v1/threads/{id}/no-reply-needed); null once they write again or the team replies

string format: date-time
nullable
firstResponseDueAt
required

When the first reply is due

string format: date-time
nullable
owner
required
One of:
object
id
required
string
name
required
string
avatarUrl
required

Their picture; null to show their initials

string
nullable
locationId
required
string format: uuid
nullable
lastMessage
required
One of:
object
at
required
string format: date-time
preview
required
string
kind
required
string
Allowed values: message note automated event
channel
required
string
Allowed values: email sms whatsapp chat phone form api marketplace visit messenger instagram internal
tags
required
Array<object>
object
id
required
string format: uuid
name
required
string
colour
required
string
archived
required

Archived since it was added: it stays on the thread until taken off, but cannot be added again

boolean
unread
required

Unread for the signed-in person (null for API keys)

boolean
nullable
pinned
required

Pinned by the signed-in person (POST /v1/threads/{id}/pin): pinned threads come first in the list. Each person pins their own; always false for API keys

boolean
leadCount
required

Leads in every chapter

number
isTest
required

Started by “Send a test lead”: kept out of Unassigned, rules, lead counts and webhooks, and can be deleted

boolean
snoozedUntil
required
string format: date-time
nullable
snoozeUntilReply
required
boolean
items
required

What the current chapter is about: catalogue items and free-text lines, main items with their add-ons (parentId), in order

Array<object>
object
id
required
string format: uuid
item
required
One of:
One of: discriminator: type
object
id
required
string format: uuid
source
required

Where the item came from: manual, csv, api or an integration key

string
externalId
required

The item’s id in its source

string
locationId
required
string format: uuid
nullable
title
required

From the attributes

string
status
required

The availability: in_stock, out_of_stock, preorder or backorder for products; an industry pack’s item types have their own

string
price
required
One of:
object
amountMinor
required

Amount in minor units (pence, cents)

number
currency
required

ISO 4217

string
billing
required

How the price is charged: one_off (once), monthly (every month) or annual (every year)

string
Allowed values: one_off monthly annual
images
required

Image links, main image first

Array<string>
archivedAt
required

When it was removed from the catalogue (no longer in stock). Removed items stay on the leads and threads that mention them

string format: date-time
nullable
url
required

Advert or product page

string
nullable
addOn
required

Usually sold as an add-on to something else (a warranty, delivery, an onboarding package). Suggestions only

boolean
addOnFor
required

The item types it is usually added to; empty means anything

Array<string>
createdAt
required
string format: date-time
updatedAt
required
string format: date-time
attributes
required
object
title
required

Google/Meta title

string
<= 150 characters
description

Google/Meta description

string
<= 5000 characters
link

Product page. Google/Meta link

string format: uri
imageLinks

Main image first. Google/Meta image_link and additional_image_link

Array<string>
<= 11 items
price
required

Google/Meta price

object
amountMinor
required

Amount in minor units (pence, cents)

number
currency
required

ISO 4217

string
salePrice

Google/Meta sale_price

object
amountMinor
required

Amount in minor units (pence, cents)

number
currency
required

ISO 4217

string
availability

Google/Meta availability

string
default: in_stock
Allowed values: in_stock out_of_stock preorder backorder
condition

Google/Meta condition

string
default: new
Allowed values: new refurbished used
brand

Google/Meta brand

string
<= 70 characters
gtin

GTIN-8, 12, 13 or 14. Google/Meta gtin

string
mpn

Google/Meta mpn

string
<= 70 characters
sku

Your own stock code

string
<= 100 characters
googleProductCategory

Google/Meta google_product_category

string
<= 750 characters
productType

Google/Meta product_type

string
<= 750 characters
itemGroupId

Shared by variants. Google/Meta item_group_id

string
<= 50 characters
size

Google/Meta size

string
<= 100 characters
colour

Google/Meta color

string
<= 100 characters
material

Google/Meta material

string
<= 200 characters
pattern

Google/Meta pattern

string
<= 100 characters
customLabel0

Google/Meta custom_label_0

string
<= 100 characters
customLabel1

Google/Meta custom_label_1

string
<= 100 characters
customLabel2

Google/Meta custom_label_2

string
<= 100 characters
customLabel3

Google/Meta custom_label_3

string
<= 100 characters
customLabel4

Google/Meta custom_label_4

string
<= 100 characters
type
required
string
Allowed values: product
label
required

A free-text line’s words

string
nullable
price
required
One of:
object
amountMinor
required

Amount in minor units (pence, cents)

number
currency
required

ISO 4217

string
billing
required

How the price is charged: a free-text line’s own, or a catalogue item’s (as on item). one_off, monthly or annual

string
Allowed values: one_off monthly annual
quantity
required
integer
>= -9007199254740991 <= 9007199254740991
parentId
required

The main item this is an add-on to; null for a main item

string format: uuid
nullable
position
required

Order among its siblings

integer
>= -9007199254740991 <= 9007199254740991
source
required

How it got there: named by a lead, added by staff, the API or the assistant

string
Allowed values: lead staff api assistant
messageId
required

The message that first named it

string format: uuid
nullable
addedBy
required
One of:
object
id
required
string
name
required
string
createdAt
required
string format: date-time
leadSource
required
One of:
object
id
required
string format: uuid
name
required
string
logoUrl
required

Null shows an initial badge

string
nullable
display
required

What its row in the inbox list shows, from its inbox’s list layout

object
item
required

The item line: the first main item the thread is about. Null when the inbox hides it or the thread is about nothing

object
reference
required

The item’s reference (an identifier its industry pack names, such as a plate), drawn the way its industry pack draws it; null when the layout leaves it out or the item has none

string
nullable
referenceType
required

The item type the reference belongs to; null with no reference

string
nullable
text
required

The layout’s other item fields, formatted and joined with ’ · ’

string
more
required

Other main items the thread is about

integer
>= -9007199254740991 <= 9007199254740991
archived
required

The item is no longer in the catalogue

boolean
details
required

The thread details to show under it, in order (read each from the thread’s own fields)

Array<string>
Allowed values: stage score next_appointment source waiting tags owner location
createdAt
required
string format: date-time
updatedAt
required

Changes when the thread or its summary changes; poll it to know when to reload

string format: date-time
contactDetails
required
One of:
object
id
required
string format: uuid
name
required
string
nullable
email
required
string
nullable
phone
required

As given

string
nullable
phoneE164
required

E.164

string
nullable
avatarUrl
required

Their picture, uploaded by your team; null when none

string
nullable
companies
required

The companies they work for now, their primary company first (see /v1/contacts/{id}/companies for past ones)

Array<object>
object
company
required
object
id
required
string format: uuid
name
required
string
avatarUrl
required

The company’s picture (uploaded, or its website’s icon); null when none

string
nullable
status
required

As the register gives it (active, dissolved, liquidation…); null when not known

string
nullable
role
required

What they do for the company, in your words: Director, Accounts…

string
nullable
jobTitle
required
string
nullable
isPrimary
required

Their main company (at most one); shown first and with their name

boolean
source
required

How the link was made: manual (your team), domain (their email address is at one of the company’s domains), form, lead, import, api, integration or assistant

string
Allowed values: manual domain form lead import api integration assistant
endedAt
required

When they left the company; kept for history, not current

string format: date-time
nullable
createdAt
required
string format: date-time
emailInvalidAt
required

Email bounced or is not valid

string format: date-time
nullable
phoneInvalidAt
required

The number failed or is not valid

string format: date-time
nullable
mergedIntoId
required

Set when this contact was merged into another

string format: uuid
nullable
redactedAt
required

When the contact and their data were deleted (an erasure): what’s left is only kept so counts and reports add up

string format: date-time
nullable
externalIds
required
Array<object>
object
integration
required

The other system, e.g. my-dms

string
externalId
required

The contact’s id there

string
appName
required

The installed partner app this id belongs to (its integration is the app slug)

string
nullable
url
required

The contact in that app (from the app’s contact address), for Open in …

string
nullable
consents
required
Array<object>
object
channel
required
string
Allowed values: email sms whatsapp chat phone form api marketplace visit messenger instagram internal
status
required
string
Allowed values: opted_in opted_out unknown
source
required

Where the latest decision came from, in short: form, api, staff, stop_reply, unsubscribe, import, complaint, assistant, connection, merge or system. The full story (who, how, the wording shown) is in the consent history.

string
at
required
string format: date-time
pendingOptInAt
required

A contact form asked to opt them back in after they opted out. Not applied: anyone can type an address into a form.

string format: date-time
nullable
attributes
required

Contact field values by field key (see /v1/contact-fields): text, numbers, dates as YYYY-MM-DD and true or false

object
key
additional properties
One of:
string
marketingSuppressed
required

Channels on which this person asked not to receive marketing: their email address or number is on the marketing suppression list (someone with it opted out and their data was deleted). Marketing opt-ins there are kept as pending and marketing sends are refused; replies and service messages are unaffected

Array<string>
threadId
required

The contact’s most recent live thread you can see, if any (a contact has one thread per inbox)

string format: uuid
nullable
threadIds
required

The contact’s live threads you can see, one per inbox, most recent first

Array<string>
createdAt
required
string format: date-time
updatedAt
required
string format: date-time
participants
required
Array<object>
object
contact
required
object
id
required
string format: uuid
name
required
string
nullable
email
required
string
nullable
phoneE164
required
string
nullable
avatarUrl
required

Their picture, uploaded by your team; null when none

string
nullable
company
required
One of:
object
id
required
string format: uuid
name
required
string
avatarUrl
required

The company’s picture (uploaded, or its website’s icon); null when none

string
nullable
status
required

As the register gives it (active, dissolved, liquidation…); null when not known

string
nullable
role
required
string
Allowed values: primary participant
links
required

The current chapter’s links

Array<object>
object
id
required
string format: uuid
chapterId
required

The chapter it belongs to (a deal is its chapter’s)

string format: uuid
messageId
required
string format: uuid
nullable
recordType
required
string
Allowed values: deal appraisal finance_application invoice esign reservation other
integration
required
string
externalId
required
string
label
required
string
url
required
string
nullable
status
required
string
nullable
createdAt
required
string format: date-time
currentChapter
required

The current chapter in full: its outcome, value, owner at close and summary

object
id
required
string format: uuid
number
required

1, 2, 3 within the thread

integer
>= -9007199254740991 <= 9007199254740991
startedAt
required
string format: date-time
startedBy
required

What started it: first (the thread began), lead (a new lead on a Done thread), period (they wrote long after it closed), staff, api, flow, or migration

string
Allowed values: first lead period staff api flow migration
closedAt
required

Null while open

string format: date-time
nullable
outcome
required
string
nullable
Allowed values: deal lost none no_reply
threadId
required
string format: uuid
stage
required

Derived from the chapter’s activity, never set by hand

string
Allowed values: new contacted booked attended won lost
outcomeNote
required

Lost reason or closing note

string
nullable
lostReasonId
required
string format: uuid
nullable
outcomeValueMinor
required

Sale value when closed as Won, in minor units

number
nullable
outcomeCurrency
required
string
nullable
owner
required
One of:
object
id
required
string
name
required
string
locationId
required

Where its first lead came in

string format: uuid
nullable
leadCount
required
integer
>= -9007199254740991 <= 9007199254740991
lastLeadAt
required
string format: date-time
nullable
summary
required

The AI summary of the chapter (three to five lines, newline separated); kept when it closes

string
nullable
items
required

What they were interested in: catalogue items and free-text lines, main items with their add-ons (parentId), in order

Array<object>
object
id
required
string format: uuid
item
required
One of:
One of: discriminator: type
object
id
required
string format: uuid
source
required

Where the item came from: manual, csv, api or an integration key

string
externalId
required

The item’s id in its source

string
locationId
required
string format: uuid
nullable
title
required

From the attributes

string
status
required

The availability: in_stock, out_of_stock, preorder or backorder for products; an industry pack’s item types have their own

string
price
required
One of:
object
amountMinor
required

Amount in minor units (pence, cents)

number
currency
required

ISO 4217

string
billing
required

How the price is charged: one_off (once), monthly (every month) or annual (every year)

string
Allowed values: one_off monthly annual
images
required

Image links, main image first

Array<string>
archivedAt
required

When it was removed from the catalogue (no longer in stock). Removed items stay on the leads and threads that mention them

string format: date-time
nullable
url
required

Advert or product page

string
nullable
addOn
required

Usually sold as an add-on to something else (a warranty, delivery, an onboarding package). Suggestions only

boolean
addOnFor
required

The item types it is usually added to; empty means anything

Array<string>
createdAt
required
string format: date-time
updatedAt
required
string format: date-time
attributes
required
object
title
required

Google/Meta title

string
<= 150 characters
description

Google/Meta description

string
<= 5000 characters
link

Product page. Google/Meta link

string format: uri
imageLinks

Main image first. Google/Meta image_link and additional_image_link

Array<string>
<= 11 items
price
required

Google/Meta price

object
amountMinor
required

Amount in minor units (pence, cents)

number
currency
required

ISO 4217

string
salePrice

Google/Meta sale_price

object
amountMinor
required

Amount in minor units (pence, cents)

number
currency
required

ISO 4217

string
availability

Google/Meta availability

string
default: in_stock
Allowed values: in_stock out_of_stock preorder backorder
condition

Google/Meta condition

string
default: new
Allowed values: new refurbished used
brand

Google/Meta brand

string
<= 70 characters
gtin

GTIN-8, 12, 13 or 14. Google/Meta gtin

string
mpn

Google/Meta mpn

string
<= 70 characters
sku

Your own stock code

string
<= 100 characters
googleProductCategory

Google/Meta google_product_category

string
<= 750 characters
productType

Google/Meta product_type

string
<= 750 characters
itemGroupId

Shared by variants. Google/Meta item_group_id

string
<= 50 characters
size

Google/Meta size

string
<= 100 characters
colour

Google/Meta color

string
<= 100 characters
material

Google/Meta material

string
<= 200 characters
pattern

Google/Meta pattern

string
<= 100 characters
customLabel0

Google/Meta custom_label_0

string
<= 100 characters
customLabel1

Google/Meta custom_label_1

string
<= 100 characters
customLabel2

Google/Meta custom_label_2

string
<= 100 characters
customLabel3

Google/Meta custom_label_3

string
<= 100 characters
customLabel4

Google/Meta custom_label_4

string
<= 100 characters
type
required
string
Allowed values: product
label
required

A free-text line’s words

string
nullable
price
required
One of:
object
amountMinor
required

Amount in minor units (pence, cents)

number
currency
required

ISO 4217

string
billing
required

How the price is charged: a free-text line’s own, or a catalogue item’s (as on item). one_off, monthly or annual

string
Allowed values: one_off monthly annual
quantity
required
integer
>= -9007199254740991 <= 9007199254740991
parentId
required

The main item this is an add-on to; null for a main item

string format: uuid
nullable
position
required

Order among its siblings

integer
>= -9007199254740991 <= 9007199254740991
source
required

How it got there: named by a lead, added by staff, the API or the assistant

string
Allowed values: lead staff api assistant
messageId
required

The message that first named it

string format: uuid
nullable
addedBy
required
One of:
object
id
required
string
name
required
string
createdAt
required
string format: date-time
chapterCount
required
integer
>= -9007199254740991 <= 9007199254740991
pinnedNotes
required

Notes pinned to the top of the thread for everyone who opens it, the latest pinned first (up to 3 can be pinned; a thread merged in keeps its pins, so a merged thread can show more)

Array<object>
object
id
required

The note (a message of kind note)

string format: uuid
text
required
string
authorName
required
string
nullable
createdAt
required
string format: date-time
pin
required
object
at
required

When it was pinned

string format: date-time
by
required
One of:
object
id
required
string
name
required
string
canReply
required

Whether you can reply and act on this thread (Basic seats read and add notes)

boolean

Example 

{
  "inbox": {
    "name": "Leeds Sales",
    "type": "sales"
  },
  "contact": {
    "name": "Sarah Turner",
    "email": "sarah.turner@example.co.uk",
    "phoneE164": "+447911123456",
    "avatarUrl": "https://api.threadkite.com/avatars/9b0d….jpg",
    "company": {
      "name": "Acme Fleet Services Ltd",
      "avatarUrl": "https://api.threadkite.com/avatars/6c1f….png",
      "status": "active"
    }
  },
  "state": "open",
  "stage": "new",
  "chapter": {
    "number": 2,
    "startedBy": "first",
    "outcome": "deal"
  },
  "previousChapter": {
    "number": 2,
    "startedBy": "first",
    "outcome": "deal"
  },
  "nextAppointment": {
    "type": "consultation",
    "typeLabel": "Consultation",
    "timeZone": "Europe/London"
  },
  "waiting": "us",
  "score": {
    "band": "hot",
    "reasons": [
      "Asked about finance",
      "Replies within 5 minutes"
    ]
  },
  "owner": {
    "id": "usr_8f2c",
    "name": "James Patel",
    "avatarUrl": "https://api.threadkite.app/avatars/0b7c3a52-5d9e-4f3a-9a51-2f1e8c6d4b10.jpg"
  },
  "lastMessage": {
    "preview": "Is this still available? Could I come in on Saturday?",
    "kind": "message",
    "channel": "email"
  },
  "tags": [
    {
      "name": "Finance",
      "colour": "blue"
    }
  ],
  "leadCount": 2,
  "items": [
    {
      "item": {
        "source": "my-dms",
        "externalId": "SKU-1042",
        "title": "Oak dining table",
        "status": "in_stock",
        "price": {
          "amountMinor": 1299500,
          "currency": "GBP"
        },
        "billing": "one_off",
        "addOnFor": [
          "product"
        ],
        "attributes": {
          "title": "Merino jumper",
          "price": {
            "amountMinor": 1299500,
            "currency": "GBP"
          },
          "salePrice": {
            "amountMinor": 1299500,
            "currency": "GBP"
          },
          "availability": "in_stock",
          "condition": "new"
        },
        "type": "product"
      },
      "label": "Custom paint",
      "price": {
        "amountMinor": 1299500,
        "currency": "GBP"
      },
      "billing": "one_off",
      "quantity": 1,
      "source": "lead",
      "addedBy": {
        "id": "usr_8f2c",
        "name": "James Patel"
      }
    }
  ],
  "leadSource": {
    "name": "Google Ads"
  },
  "display": {
    "item": {
      "reference": "FL-1042",
      "referenceType": "flat",
      "text": "2 bed flat, Roundhay · £1,150 a month",
      "more": 1
    },
    "details": [
      "stage",
      "source",
      "next_appointment"
    ]
  },
  "contactDetails": {
    "name": "Sarah Turner",
    "email": "sarah.turner@example.co.uk",
    "phone": "07911 123456",
    "phoneE164": "+447911123456",
    "avatarUrl": "https://api.threadkite.com/avatars/9b0d….jpg",
    "companies": [
      {
        "company": {
          "name": "Acme Fleet Services Ltd",
          "avatarUrl": "https://api.threadkite.com/avatars/6c1f….png",
          "status": "active"
        },
        "role": "Fleet manager",
        "jobTitle": "Head of Transport",
        "source": "manual"
      }
    ],
    "externalIds": [
      {
        "integration": "my-dms",
        "externalId": "CUST-10442",
        "appName": "Northern DMS",
        "url": "https://dms.example/customers/CUST-10442"
      }
    ],
    "consents": [
      {
        "channel": "email",
        "status": "opted_in",
        "source": "stop_reply"
      }
    ],
    "attributes": {
      "finance_end_date": "2027-01-03",
      "budget": 15000
    },
    "marketingSuppressed": [
      "email"
    ]
  },
  "participants": [
    {
      "contact": {
        "name": "Sarah Turner",
        "email": "sarah.turner@example.co.uk",
        "phoneE164": "+447911123456",
        "avatarUrl": "https://api.threadkite.com/avatars/9b0d….jpg",
        "company": {
          "name": "Acme Fleet Services Ltd",
          "avatarUrl": "https://api.threadkite.com/avatars/6c1f….png",
          "status": "active"
        }
      },
      "role": "primary"
    }
  ],
  "links": [
    {
      "recordType": "deal",
      "integration": "my-dms",
      "externalId": "DEAL-2231",
      "label": "Deal #2231",
      "url": "https://dms.example.com/deals/2231",
      "status": "won"
    }
  ],
  "currentChapter": {
    "number": 2,
    "startedBy": "first",
    "outcome": "deal",
    "stage": "new",
    "outcomeCurrency": "GBP",
    "owner": {
      "id": "usr_8f2c",
      "name": "James Patel"
    },
    "leadCount": 1,
    "items": [
      {
        "item": {
          "source": "my-dms",
          "externalId": "SKU-1042",
          "title": "Oak dining table",
          "status": "in_stock",
          "price": {
            "amountMinor": 1299500,
            "currency": "GBP"
          },
          "billing": "one_off",
          "addOnFor": [
            "product"
          ],
          "attributes": {
            "title": "Merino jumper",
            "price": {
              "amountMinor": 1299500,
              "currency": "GBP"
            },
            "salePrice": {
              "amountMinor": 1299500,
              "currency": "GBP"
            },
            "availability": "in_stock",
            "condition": "new"
          },
          "type": "product"
        },
        "label": "Custom paint",
        "price": {
          "amountMinor": 1299500,
          "currency": "GBP"
        },
        "billing": "one_off",
        "quantity": 1,
        "source": "lead",
        "addedBy": {
          "id": "usr_8f2c",
          "name": "James Patel"
        }
      }
    ]
  },
  "chapterCount": 2,
  "pinnedNotes": [
    {
      "text": "Prefers a text to a call. Ask for Sam at the front desk.",
      "authorName": "James Patel",
      "pin": {
        "by": {
          "id": "usr_8f2c",
          "name": "James Patel"
        }
      }
    }
  ]
}

400

Section titled “400”
Media typeapplication/json
object
statusCode
required
number
code
required

Stable machine-readable reason

string
message
required
string
errors

With code invalid: every problem with the request, by field (message is the first)

Array<object>
object
path
required

Dotted path inside the item, e.g. attributes.price.amountMinor

string
message
required
string

Example 

{
  "statusCode": 403,
  "code": "forbidden",
  "message": "You do not have permission to do that.",
  "errors": [
    {
      "message": "Enter the make"
    }
  ]
}

401

Section titled “401”

Missing or invalid API key

Media typeapplication/json
object
statusCode
required
number
code
required

Stable machine-readable reason

string
message
required
string
errors

With code invalid: every problem with the request, by field (message is the first)

Array<object>
object
path
required

Dotted path inside the item, e.g. attributes.price.amountMinor

string
message
required
string

Example 

{
  "statusCode": 403,
  "code": "forbidden",
  "message": "You do not have permission to do that.",
  "errors": [
    {
      "message": "Enter the make"
    }
  ]
}

402

Section titled “402”

The organisation is on the Free plan (code upgrade_required)

Media typeapplication/json
object
statusCode
required
number
code
required

Stable machine-readable reason

string
message
required
string
feature
required

The feature that needs Pro

string
nullable
Allowed values: extraSeats connections aiAssistant aiReplies rules fullReports api inboxes bulkMessages videoMessages
upgradePath
required

Where to upgrade or pay, in the web app

string

Example 

{
  "statusCode": 402,
  "code": "upgrade_required",
  "message": "Connections are part of Pro. Upgrade to connect texts, calls and more.",
  "feature": "extraSeats",
  "upgradePath": "/settings/billing"
}

403

Section titled “403”

The key does not have the scope (or the person the permission)

Media typeapplication/json
object
statusCode
required
number
code
required

Stable machine-readable reason

string
message
required
string
errors

With code invalid: every problem with the request, by field (message is the first)

Array<object>
object
path
required

Dotted path inside the item, e.g. attributes.price.amountMinor

string
message
required
string

Example 

{
  "statusCode": 403,
  "code": "forbidden",
  "message": "You do not have permission to do that.",
  "errors": [
    {
      "message": "Enter the make"
    }
  ]
}

404

Section titled “404”
Media typeapplication/json
object
statusCode
required
number
code
required

Stable machine-readable reason

string
message
required
string
errors

With code invalid: every problem with the request, by field (message is the first)

Array<object>
object
path
required

Dotted path inside the item, e.g. attributes.price.amountMinor

string
message
required
string

Example 

{
  "statusCode": 403,
  "code": "forbidden",
  "message": "You do not have permission to do that.",
  "errors": [
    {
      "message": "Enter the make"
    }
  ]
}

429

Section titled “429”

Rate limit reached

Media typeapplication/json
object
statusCode
required
number
code
required

Stable machine-readable reason

string
message
required
string
retryAfter
required

Seconds until another request will be accepted

number

Example 

{
  "statusCode": 429,
  "code": "rate_limited",
  "message": "Too many requests. Each key can make 120 requests a minute; try again in 12 seconds.",
  "retryAfter": 12
}