Skip to content
ThreadkiteThreadkite Docs

Add an automation

POST
/v1/flows
curl --request POST \
  --url https://api.threadkite.app/v1/flows \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "New lead follow-up", "description": "example", "inboxId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "recipeKey": "out_of_hours_reply", "definition": { "version": 1, "trigger": { "type": "event", "events": [ "example" ], "conditions": [] }, "conditions": [], "steps": [ { "id": "example", "type": "wait", "wait": { "kind": "duration", "duration": { "amount": 1, "unit": "minutes", "working": false } } } ], "exits": { "contactReplied": true, "teamReplied": false, "threadClosed": true, "events": [] }, "reentry": { "kind": "once_per_thread" } }, "publish": false }'

From a recipe (recipeKey, its steps unless you give a definition) or from scratch. Saved as a draft; publish: true switches it on straight away.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
name

Required without a recipe; the recipe’s name otherwise

string
>= 1 characters <= 100 characters

Example 

New lead follow-up
description
string
nullable <= 500 characters
inboxId

The inbox it works in; every inbox when left out

string format: uuid
nullable
recipeKey

Start from a ready-made automation (see /v1/flow-recipes)

string
Allowed values: out_of_hours_reply new_lead_follow_up appointment_no_show quiet_lead ai_responder finance_ending positive_equity in_for_service mot_due bought_elsewhere
definition

The steps; the recipe’s when left out

object
version
number
default: 1
Allowed values: 1
trigger
required
One of:
object
type
required
string
Allowed values: event
events
required
Array<string>
>= 1 items <= 10 items
conditions
Array
default: <= 20 items
Any of:
Any of:
object
type
required
string
Allowed values: field
field
required
string
/^(event|contact|consent|thread|time|company)\.[A-Za-z0-9_.]{1,100}$/
op
required
string
Allowed values: equals not_equals in not_in contains not_contains is_set is_not_set greater_than less_than is_true is_false in_last_days in_next_days more_than_days_ago
value
Any of:
string
<= 500 characters
conditions
Array
default: <= 20 items
Any of:
Any of:
object
type
required
string
Allowed values: field
field
required
string
/^(event|contact|consent|thread|time|company)\.[A-Za-z0-9_.]{1,100}$/
op
required
string
Allowed values: equals not_equals in not_in contains not_contains is_set is_not_set greater_than less_than is_true is_false in_last_days in_next_days more_than_days_ago
value
Any of:
string
<= 500 characters
steps
required
Array
<= 100 items
Any of:
object
id
required
string
/^[A-Za-z0-9_-]{1,40}$/
type
required
string
Allowed values: wait
wait
required
One of:
object
kind
required
string
Allowed values: duration
duration
required

How long. working counts only opening hours (minutes and hours), or days the location opens (days)

object
amount
required
integer
>= 1 <= 100000
unit
required
string
Allowed values: minutes hours days weeks
working
boolean
exits
object
contactReplied
boolean
default: true
teamReplied
boolean
threadClosed
boolean
default: true
events
Array<string>
default: <= 20 items
reentry
object
kind
required
string
Allowed values: once once_per_thread once_per_thread_per_day every_n_days always
days
integer
>= 1 <= 3650
publish

Publish it and switch it on straight away (else it is saved as a draft)

boolean

Responses

Section titled “Responses”

201

Section titled “201”
Media typeapplication/json
object
id
required
string format: uuid
name
required
string
description
required
string
nullable
status
required

draft (never published), live (on) or paused

string
Allowed values: draft live paused
recipeKey
required
string
nullable
Allowed values: out_of_hours_reply new_lead_follow_up appointment_no_show quiet_lead ai_responder finance_ending positive_equity in_for_service mot_due bought_elsewhere
inbox
required
One of:
object
id
required
string format: uuid
name
required
string
trigger
required
One of:
object
type
required
string
Allowed values: event date manual
events
required

The events it starts on (any of them), for event triggers; empty otherwise

Array<string>
version
required

The published version number

number
nullable
hasDraft
required

There are unpublished changes

boolean
activeRuns
required

Contacts in it now (waiting or running)

number
runsThisWeek
required

Contacts who started it in the last 7 days

number
allowedOnPlan
required

Your plan lets it be switched on (Free: only the out-of-hours reply, with only its wording changed)

boolean
createdAt
required
string format: date-time
updatedAt
required
string format: date-time
definition
required
One of:

A flow: a trigger, conditions checked when a contact would start, steps in order (with if/else branches), when to stop early (exits) and how often a contact can start it (reentry)

object
version
number
default: 1
Allowed values: 1
trigger
required
One of:
object
type
required
string
Allowed values: event
events
required
Array<string>
>= 1 items <= 10 items
conditions
Array
default: <= 20 items
Any of:
Any of:
object
type
required
string
Allowed values: field
field
required
string
/^(event|contact|consent|thread|time|company)\.[A-Za-z0-9_.]{1,100}$/
op
required
string
Allowed values: equals not_equals in not_in contains not_contains is_set is_not_set greater_than less_than is_true is_false in_last_days in_next_days more_than_days_ago
value
Any of:
string
<= 500 characters
conditions
Array
default: <= 20 items
Any of:
Any of:
object
type
required
string
Allowed values: field
field
required
string
/^(event|contact|consent|thread|time|company)\.[A-Za-z0-9_.]{1,100}$/
op
required
string
Allowed values: equals not_equals in not_in contains not_contains is_set is_not_set greater_than less_than is_true is_false in_last_days in_next_days more_than_days_ago
value
Any of:
string
<= 500 characters
steps
required
Array
<= 100 items
Any of:
object
id
required
string
/^[A-Za-z0-9_-]{1,40}$/
type
required
string
Allowed values: wait
wait
required
One of:
object
kind
required
string
Allowed values: duration
duration
required

How long. working counts only opening hours (minutes and hours), or days the location opens (days)

object
amount
required
integer
>= 1 <= 100000
unit
required
string
Allowed values: minutes hours days weeks
working
boolean
exits
object
contactReplied
boolean
default: true
teamReplied
boolean
threadClosed
boolean
default: true
events
Array<string>
default: <= 20 items
reentry
object
kind
required
string
Allowed values: once once_per_thread once_per_thread_per_day every_n_days always
days
integer
>= 1 <= 3650
draftDefinition
required
One of:

A flow: a trigger, conditions checked when a contact would start, steps in order (with if/else branches), when to stop early (exits) and how often a contact can start it (reentry)

object
version
number
default: 1
Allowed values: 1
trigger
required
One of:
object
type
required
string
Allowed values: event
events
required
Array<string>
>= 1 items <= 10 items
conditions
Array
default: <= 20 items
Any of:
Any of:
object
type
required
string
Allowed values: field
field
required
string
/^(event|contact|consent|thread|time|company)\.[A-Za-z0-9_.]{1,100}$/
op
required
string
Allowed values: equals not_equals in not_in contains not_contains is_set is_not_set greater_than less_than is_true is_false in_last_days in_next_days more_than_days_ago
value
Any of:
string
<= 500 characters
conditions
Array
default: <= 20 items
Any of:
Any of:
object
type
required
string
Allowed values: field
field
required
string
/^(event|contact|consent|thread|time|company)\.[A-Za-z0-9_.]{1,100}$/
op
required
string
Allowed values: equals not_equals in not_in contains not_contains is_set is_not_set greater_than less_than is_true is_false in_last_days in_next_days more_than_days_ago
value
Any of:
string
<= 500 characters
steps
required
Array
<= 100 items
Any of:
object
id
required
string
/^[A-Za-z0-9_-]{1,40}$/
type
required
string
Allowed values: wait
wait
required
One of:
object
kind
required
string
Allowed values: duration
duration
required

How long. working counts only opening hours (minutes and hours), or days the location opens (days)

object
amount
required
integer
>= 1 <= 100000
unit
required
string
Allowed values: minutes hours days weeks
working
boolean
exits
object
contactReplied
boolean
default: true
teamReplied
boolean
threadClosed
boolean
default: true
events
Array<string>
default: <= 20 items
reentry
object
kind
required
string
Allowed values: once once_per_thread once_per_thread_per_day every_n_days always
days
integer
>= 1 <= 3650

Example 

{
  "status": "draft",
  "recipeKey": "out_of_hours_reply",
  "inbox": {
    "name": "Sales"
  },
  "trigger": {
    "type": "event",
    "events": [
      "lead.created"
    ]
  },
  "definition": {
    "version": 1,
    "trigger": {
      "type": "event",
      "conditions": []
    },
    "conditions": [],
    "steps": [
      {
        "type": "wait",
        "wait": {
          "kind": "duration",
          "duration": {
            "unit": "minutes",
            "working": false
          }
        }
      }
    ],
    "exits": {
      "contactReplied": true,
      "teamReplied": false,
      "threadClosed": true,
      "events": []
    },
    "reentry": {
      "kind": "once_per_thread"
    }
  },
  "draftDefinition": {
    "version": 1,
    "trigger": {
      "type": "event",
      "conditions": []
    },
    "conditions": [],
    "steps": [
      {
        "type": "wait",
        "wait": {
          "kind": "duration",
          "duration": {
            "unit": "minutes",
            "working": false
          }
        }
      }
    ],
    "exits": {
      "contactReplied": true,
      "teamReplied": false,
      "threadClosed": true,
      "events": []
    },
    "reentry": {
      "kind": "once_per_thread"
    }
  }
}

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”

Automations are part of Pro; Free can switch on only the out-of-hours reply, changing only its wording (code upgrade_required, feature rules)

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
}