Skip to content
ThreadkiteThreadkite Docs

Send a contact form

POST
/f/{publicKey}
curl --request POST \
  --url https://api.threadkite.app/f/example \
  --header 'Content-Type: application/json' \
  --data '{ "name": "Sarah Turner", "email": "sarah.turner@example.co.uk", "message": "Is the Focus still available?", "consent": [ "marketing_email" ], "_tk_token": "m1abc.signature" }'

Posts the answers by field name, as JSON or application/x-www-form-urlencoded, with consent for each ticked box, _tk_token from the form, and optionally _tk_page, _tk_landing, _tk_referrer, utm_* (with utm_id), _tk_click_id (the ad click id, as gclid:...) _tk_item (repeatable: what the lead is about, as an external id, an identifier such as a registration, or a SKU; the first is the main item, and unknown ones are left out) and _tk_addon (repeatable: options added to the main item, as an identifier or, when not in the catalogue, its own words up to 200 characters), and _tk_proof, the robot check’s proof, when the form’s robotCheck is on (without it, the message goes to the Spam folder; without it and without _tk_token as well, it is refused with robot_check_required). Without page details (a plain HTML form on a page without the website script), the Referer is taken as the page, with any UTMs in its address. A plain HTML form is redirected (303) to the thank-you page, or back to the hosted form with a problem; JSON callers get JSON. Spam is answered like any other submission.

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
publicKey
required
string

The form’s public key

Request Bodyrequired

Section titled “Request Bodyrequired”
object
key
additional properties
One of:
string

Example 

{
  "name": "Sarah Turner",
  "email": "sarah.turner@example.co.uk",
  "message": "Is the Focus still available?",
  "consent": [
    "marketing_email"
  ],
  "_tk_token": "m1abc.signature"
}

Responses

Section titled “Responses”

200

Section titled “200”
Media typeapplication/json
object
ok
required
boolean
message
required

The thank-you message to show

string
redirectUrl
required

Go here instead of showing the message

string
nullable

Example 

{
  "ok": true
}

303

Section titled “303”

A plain HTML form: the thank-you page, or the problem

400

Section titled “400”

Answers to change, by field (invalid_submission); or robot_check_required, with the reason as errors.form: the form asks for the robot check and the post had neither _tk_proof nor _tk_token

Media typeapplication/json
object
statusCode
required
number
code
required

Stable machine-readable reason

string
message
required
string
errors
required

Problems by field name (consent.<key> for tick boxes, form overall)

object
key
additional properties
string

Example 

{
  "statusCode": 400,
  "code": "invalid_submission",
  "message": "Check the form: some answers need changing.",
  "errors": {
    "email": "Enter an email address like name@example.co.uk"
  }
}

403

Section titled “403”

Not from an allowed website

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

410

Section titled “410”

The form is archived

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”
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
}