Skip to content
ThreadkiteThreadkite Docs

Threads in a folder

GET
/v1/threads
curl --request GET \
  --url 'https://api.threadkite.app/v1/threads?folder=mine&channel=email&waiting=us&returning=true&sort=recent&item=colour%3ARed%2CBlue%3Bprice%3A..500&limit=25' \
  --header 'Authorization: Bearer <token>'

Folders: mine, unassigned, waiting (on us), open, snoozed, done, spam. Only threads in inboxes you can see (yours; every inbox for owners, admins and keys without an inbox limit). Filter by inbox, owner, location, source, tag, channel, derived stage and the items a thread is about (item); q searches names, message text and item words, and matches an exact email, phone number or item identifier. Most recent activity first; pages by cursor.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
folder
string
default: open
Allowed values: mine unassigned waiting open snoozed done spam visitors
inboxId

Only threads in this inbox (every inbox you can see when left out)

string format: uuid

Only threads in this inbox (every inbox you can see when left out)

ownerUserId

Only threads owned by this user

string
>= 1 characters <= 100 characters

Only threads owned by this user

locationId
string format: uuid
sourceId

Threads with a message from this source

string format: uuid

Threads with a message from this source

tagId
string format: uuid
companyId

Threads of people who work at this company now

string format: uuid

Threads of people who work at this company now

channel

Threads with a message on it

string
Allowed values: email sms whatsapp chat phone form api marketplace visit messenger instagram internal

Threads with a message on it

stage

Comma-separated derived stages, e.g. new,contacted

string

Comma-separated derived stages, e.g. new,contacted

score

Comma-separated lead scores, e.g. hot,warm

string

Comma-separated lead scores, e.g. hot,warm

waiting

Only threads waiting on this side: us (the team), customer or none

string
Allowed values: us customer none

Only threads waiting on this side: us (the team), customer or none

returning

true: only returning customers (threads on their second chapter or later); false: only first chapters

string
Allowed values: true false

true: only returning customers (threads on their second chapter or later); false: only first chapters

sort

recent: latest activity first; score: Hot first, then Warm, then Cold, then unscored, latest activity first within each; waiting: longest waiting first (by waitingSince), threads not waiting last

string
default: recent
Allowed values: recent score waiting

recent: latest activity first; score: Hot first, then Warm, then Cold, then unscored, latest activity first within each; waiting: longest waiting first (by waitingSince), threads not waiting last

item

Item filters (GET /v1/inboxes/list-fields lists them): key:value,value for some values, key:lowest..highest for a range (either end may be left out; price in major units), several joined with ;, values URI-encoded (up to 20 a filter). A thread matches when one item it is about matches every filter

string
<= 8000 characters

Example 

colour:Red,Blue;price:..500

Item filters (GET /v1/inboxes/list-fields lists them): key:value,value for some values, key:lowest..highest for a range (either end may be left out; price in major units), several joined with ;, values URI-encoded (up to 20 a filter). A thread matches when one item it is about matches every filter

q

Search contact names, the names of the companies they work at, message text and the words of the items a thread is about; an exact email, phone number or item identifier matches exactly

string
<= 200 characters

Search contact names, the names of the companies they work at, message text and the words of the items a thread is about; an exact email, phone number or item identifier matches exactly

limit
integer
default: 25 >= 1 <= 100
cursor

The nextCursor from the previous page

string
<= 500 characters

The nextCursor from the previous page

updatedSince

Only threads changed since then (a new message, assigned, closed, tagged): what an app that was away needs to fetch again

string format: date-time

Only threads changed since then (a new message, assigned, closed, tagged): what an app that was away needs to fetch again

Responses

Section titled “Responses”

200

Section titled “200”
Media typeapplication/json
object
data
required
Array<object>
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
nextCursor
required

Pass as cursor to get the next page; null on the last page

string
nullable

Example 

{
  "data": [
    {
      "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"
        ]
      }
    }
  ]
}

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
}