Skip to content
ThreadkiteThreadkite Docs

Set up an organisation for a business, with the app installed

POST
/v1/partner/organisations
curl --request POST \
  --url https://api.threadkite.app/v1/partner/organisations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "Smith Motors", "country": "GB", "locationName": "Smith Motors Leeds", "ownerName": "Chris Moore", "ownerEmail": "hello@example.com", "industryPack": "automotive", "plan": "trial", "referralCode": "MOTORMS" }'

It starts a free trial from when its owner joins (plan: "trial", the default), or goes straight on the Free plan (plan: "free"); we bill the business directly if it upgrades. The owner is emailed that you set it up, then an owner invitation.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
name
required
string
<= 120 characters

Example 

Smith Motors
country
required
string
Allowed values: GB IE US CA AU NZ DE FR ES NL
locationName
required
string
<= 120 characters

Example 

Smith Motors Leeds
ownerName
string
<= 120 characters

Example 

Chris Moore
ownerEmail
required

We email them that you set Threadkite up for them, and an owner invitation

string format: email
industryPack

The industry pack the business uses (automotive), or null for none

string
nullable
Allowed values: automotive
plan

trial: a 14-day trial of Pro, from when the owner joins. free: straight on the Free plan, with no trial

string
default: trial
Allowed values: trial free
referralCode

The referral partner who brought you this business, by their referral code: they get the referral (commission and any referral discount) instead of you. We must have agreed it with you first; any other code is refused (referral_not_allowed). Leave it out and the referral is yours

string
/^\s*[A-Za-z0-9_-]{3,32}\s*$/

Example 

MOTORMS

Responses

Section titled “Responses”

201

Section titled “201”
Media typeapplication/json
object
organisationId
required
string format: uuid
name
required
string
referralCode
required

The referring partner’s code: yours, or the referralCode you gave

string
installation
required
object
id
required
string format: uuid
organisationId
required
string format: uuid
organisationName
required
string
grantedScopes
required
Array<string>
Allowed values: organisation:read locations:read locations:write members:read members:write items:read items:write leads:write contacts:read contacts:write contacts:delete companies:read companies:write companies:delete threads:read threads:write messages:read messages:write tasks:read tasks:write appointments:read appointments:write events:read events:write records:read records:write flows:read flows:write segments:read reports:read reports:write sales:read sales:write imports:read imports:write webhooks:manage
status
required
string
Allowed values: active removed
installedBy
required

person: an owner or admin connected it; partner: you created the organisation

string
Allowed values: person partner
installedAt
required
string format: date-time
removedAt
required
string format: date-time
nullable
lastUsedAt
required
string format: date-time
nullable
inboundId
required

Its own address for your webhooks: /v1/inbound/installations/<inboundId> on the API

string
nullable
accountId
required

The customer’s id in your system, for the app-wide webhook address

string
nullable
ownerInvite
required
One of:
object
email
required
string format: email
expiresAt
required
string format: date-time
expired
required

The link has expired; resend it to send a fresh one

boolean
lastSentAt
required
string format: date-time
nullable

Example 

{
  "referralCode": "MOTORMS",
  "installation": {
    "organisationName": "Smith Motors",
    "grantedScopes": [
      "organisation:read"
    ],
    "status": "active",
    "installedBy": "person",
    "inboundId": "in_8Kq2xW7mR4tZ9pL3vN6bH1cY",
    "accountId": "D-0042"
  },
  "ownerInvite": {
    "email": "chris@smithmotors.co.uk"
  }
}

401

Section titled “401”

Missing or invalid app token (code invalid_app_token)

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
}