A record, by its type and its id in your system, with its history

GET

/v1/records/{type}/{externalId}

curl --request GET \
  --url https://api.threadkite.app/v1/records/example/example \
  --header 'Authorization: Bearer <token>'

• Threadkite API

An app reads its own records; anyone else names the integration it sent them with (api when it named none).

Authorizations

• api_key
  records:read

Parameters

Path Parameters

type

required

string

<= 50 characters /^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$/

externalId

required

string

>= 1 characters <= 200 characters

Query Parameters

integration

The integration it was sent with, when you are not an app (api when left out)

string

/^[a-z0-9][a-z0-9_.-]{0,49}$/

The integration it was sent with, when you are not an app (api when left out)

Responses

200

Media typeapplication/json

object

record

required

object

id

required

string format: uuid

source

required

The app (its slug) or the integration that sent it

string

sourceName

required

The app’s name, or the integration

string

appId

required

The app that sent it, if an app did

string format: uuid

nullable

type

required

string

icon

required

The icon its type gets (link for types without their own)

string

Allowed values: invoice quote signature document payment booking order link

externalId

required

string

label

required

string

url

required

string

nullable

status

required

string

nullable

tone

required

string

Allowed values: success warning danger neutral

amount

required

One of:

object

object

value

required

In major units

number

currency

required

string

details

required

object

key

additional properties

string

contactIds

required

The contacts it is about

Array<string>

threadId

required

The thread it shows on, if any (and if you can see it)

string format: uuid

nullable

chapterId

required

string format: uuid

nullable

inboxId

required

The inbox of the thread it shows on

string format: uuid

nullable

stateAt

required

When the event its current state came from happened

string format: date-time

createdAt

required

string format: date-time

updatedAt

required

string format: date-time

history

required

Newest first, up to 100

Array<object>

object

id

required

string format: uuid

eventId

required

The contact event that carried it

string format: uuid

nullable

eventName

required

string

nullable

occurredAt

required

string format: date-time

applied

required

False when it arrived late: older than the record’s state, so it changed nothing

boolean

statusBefore

required

string

nullable

statusAfter

required

string

nullable

changed

required

The fields it changed

Array<string>

Example

{
  "record": {
    "source": "acme-crm",
    "sourceName": "Acme CRM",
    "type": "invoice",
    "icon": "invoice",
    "externalId": "8812",
    "label": "Invoice INV-8812",
    "status": "Paid",
    "tone": "success",
    "amount": {
      "value": 289,
      "currency": "GBP"
    }
  },
  "history": [
    {
      "eventName": "event.invoice.paid",
      "changed": [
        "status",
        "tone"
      ]
    }
  ]
}

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

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

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

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

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
}