Skip to content
ThreadkiteThreadkite Docs

Add something a contact owns

POST
/v1/contacts/{id}/items
curl --request POST \
  --url https://api.threadkite.app/v1/contacts/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/items \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "type": "owned_product", "attributes": { "sku": "SKU-1042", "name": "Oak dining table", "boughtFromUs": true }, "current": true, "externalSource": "my-dms", "externalId": "VEH-44120" }'

Checked against the item type (/v1/contact-item-types). The same externalId from your system, or the same registration for this contact, updates the item that is already there (200) instead of adding another (201). Contact fields that follow their items (the finance end date) are kept in step. Pro.

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
object
type
required
string
>= 1 characters <= 60 characters

Example 

owned_product
attributes
required

Checked against the item type; amounts are { amountMinor, currency }

object
key
additional properties
any

Example 

{
  "sku": "SKU-1042",
  "name": "Oak dining table",
  "boughtFromUs": true
}
current
boolean
default: true
externalSource

Your system, with externalId

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

Example 

my-dms
externalId

Your id for it: sending the same id again updates the item

string
>= 1 characters <= 200 characters

Example 

VEH-44120

Responses

Section titled “Responses”

200

Section titled “200”

It was already there and is updated

Media typeapplication/json
object
id
required
string format: uuid
contactId
required
string format: uuid
type
required

One of your industry pack’s item types

string
title
required
string
subtitle
required
string
nullable
current
required

They have it now (false: sold or replaced)

boolean
source
required

Who added it

string
Allowed values: staff api event dms
externalSource
required
string
nullable
externalId
required
string
nullable
attributes
required

The item’s details, as the item type describes them (see /v1/contact-item-types)

object
key
additional properties
any
createdAt
required
string format: date-time
updatedAt
required
string format: date-time

Example 

{
  "type": "owned_product",
  "title": "Oak dining table",
  "subtitle": "SKU-1042 · Solid oak · 2025",
  "source": "staff",
  "externalSource": "my-dms",
  "externalId": "VEH-44120",
  "attributes": {
    "sku": "SKU-1042",
    "name": "Oak dining table",
    "warrantyEndDate": "2028-03-01",
    "price": {
      "amountMinor": 89900,
      "currency": "GBP"
    }
  }
}

201

Section titled “201”

Added

Media typeapplication/json
object
id
required
string format: uuid
contactId
required
string format: uuid
type
required

One of your industry pack’s item types

string
title
required
string
subtitle
required
string
nullable
current
required

They have it now (false: sold or replaced)

boolean
source
required

Who added it

string
Allowed values: staff api event dms
externalSource
required
string
nullable
externalId
required
string
nullable
attributes
required

The item’s details, as the item type describes them (see /v1/contact-item-types)

object
key
additional properties
any
createdAt
required
string format: date-time
updatedAt
required
string format: date-time

Example 

{
  "type": "owned_product",
  "title": "Oak dining table",
  "subtitle": "SKU-1042 · Solid oak · 2025",
  "source": "staff",
  "externalSource": "my-dms",
  "externalId": "VEH-44120",
  "attributes": {
    "sku": "SKU-1042",
    "name": "Oak dining table",
    "warrantyEndDate": "2028-03-01",
    "price": {
      "amountMinor": 89900,
      "currency": "GBP"
    }
  }
}

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"
    }
  ]
}

409

Section titled “409”
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
}