Skip to content
ThreadkiteThreadkite Docs

Move or change an appointment

PATCH
/v1/appointments/{id}
curl --request PATCH \
  --url https://api.threadkite.app/v1/appointments/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0 \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "type": "viewing", "startsAt": "2026-04-15T12:00:00Z", "endsAt": "2026-04-15T12:00:00Z", "hostUserId": "example", "locationId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "itemId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "notes": "example", "notifyChannel": "email", "notify": true }'

A new time sets new reminders. When the customer is being told about it, a new time or place sends them an update (with notify: false, it does not).

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

Example 

viewing
startsAt
string format: date-time
endsAt
string format: date-time
hostUserId
string
>= 1 characters <= 100 characters
locationId
string format: uuid
nullable
itemId
string format: uuid
nullable
notes
string
nullable <= 2000 characters
notifyChannel
string
nullable
Allowed values: email sms whatsapp
notify

Send the customer the new time or place (when they are being told about it)

boolean
default: true

Responses

Section titled “Responses”

200

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

The thread’s inbox

string format: uuid
contact
required
One of:
object
id
required
string format: uuid
name
required
string
nullable
type
required
string
typeLabel
required
string
startsAt
required
string format: date-time
endsAt
required
string format: date-time
timeZone
required

The time zone it is written in

string
status
required
string
Allowed values: booked confirmed cancelled no_show completed
host
required
One of:
object
id
required
string
name
required
string
locationId
required
string format: uuid
nullable
item
required
One of:
object
id
required
string format: uuid
title
required
string
notes
required
string
nullable
notifyChannel
required

The channel the customer is told on (null: not told)

string
nullable
Allowed values: email sms whatsapp
notifyFailure
required

Why the latest message to the customer wasn’t sent, if it wasn’t

string
nullable
cancelledReason
required

Why it was cancelled (for the team)

string
nullable
createdBy
required
One of:
object
id
required
string
name
required
string
canEdit
required

You can move, cancel and mark it

boolean
createdAt
required
string format: date-time
updatedAt
required
string format: date-time

Example 

{
  "contact": {
    "name": "Sarah Turner"
  },
  "type": "consultation",
  "typeLabel": "Consultation",
  "timeZone": "Europe/London",
  "status": "booked",
  "host": {
    "id": "usr_8f2c",
    "name": "James Patel"
  },
  "item": {
    "title": "Oak dining table"
  },
  "notifyChannel": "email",
  "notifyFailure": "They have opted out of texts.",
  "createdBy": {
    "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"
    }
  ]
}

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
}