Skip to content
ThreadkiteThreadkite Docs

Check a company's VAT number with HMRC

POST
/v1/companies/{id}/vat-check
curl --request POST \
  --url https://api.threadkite.app/v1/companies/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/vat-check \
  --header 'Authorization: Bearer <token>'

Asks HMRC’s “Check a UK VAT number” whether the company’s VAT number (GB or XI) is registered, and to whom, and keeps the answer as vatCheck. For organisations in the UK, when Threadkite has HMRC set up (vatCheck in the company settings); otherwise 404. Sends company.updated with vat_check.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string format: uuid

Responses

Section titled “Responses”

200

Section titled “200”
Media typeapplication/json
object
id
required
string format: uuid
name
required
string
legalName
required
string
nullable
website
required
string
nullable
phone
required
string
nullable
email
required
string format: email
nullable
address
required
One of:
object
lines
required
Array<string>
<= 4 items
town
required
string
nullable <= 100 characters
county
required
string
nullable <= 100 characters
postcode
required
string
nullable <= 20 characters
country
required
string
nullable <= 100 characters
companyNumber
required

Its registered number (Companies House in the UK), normalised

string
nullable
vatNumber
required
string
nullable
vatCheck
required
One of:
object
vatNumber
required

The number checked

string
valid
required

HMRC has it registered

boolean
name
required

Who HMRC has it registered to; null when it is not registered

string
nullable
address
required
One of:
object
lines
required
Array<string>
<= 4 items
town
required
string
nullable <= 100 characters
county
required
string
nullable <= 100 characters
postcode
required
string
nullable <= 20 characters
country
required
string
nullable <= 100 characters
reference
required

HMRC’s consultation number, proof of the check (verified checks only)

string
nullable
checkedAt
required
string format: date-time
status
required

As the register gives it: active, dissolved…

string
nullable
sicCodes
required
Array<string>
owner
required
One of:
object
id
required
string
name
required
string
parentCompanyId
required

Its parent company (one level: a parent has no parent of its own)

string format: uuid
nullable
domains
required

Its web domains. People whose email address is at one are linked to it (unless you turned that off)

Array<string>
externalIds
required
Array<object>
object
integration
required

The other system, e.g. my-dms

string
externalId
required

The contact’s id there

string
attributes
required

Company field values by field key (see /v1/contact-fields?resource=company)

object
key
additional properties
One of:
string
avatarUrl
required

Its picture; null when none

string
nullable
avatarSource
required

upload (your team) or website (its website icon, fetched for you)

string
nullable
Allowed values: upload website
isPersonal
required

A sole trader or partnership: its details are personal data, deleted and exported with its people’s

boolean
contactCount
required

People who work there now

integer
>= -9007199254740991 <= 9007199254740991
mergedIntoId
required

Set when this company was merged into another

string format: uuid
nullable
createdAt
required
string format: date-time
updatedAt
required
string format: date-time

Example 

{
  "name": "Acme Fleet Services",
  "legalName": "Acme Fleet Services Ltd",
  "website": "https://acme.co.uk",
  "phone": "0113 496 0000",
  "email": "office@acme.co.uk",
  "address": {
    "lines": [
      "Unit 4, Riverside Park",
      "Canal Road"
    ],
    "town": "Leeds",
    "county": "West Yorkshire",
    "postcode": "LS12 2DX",
    "country": "United Kingdom"
  },
  "companyNumber": "01234567",
  "vatNumber": "GB123456789",
  "vatCheck": {
    "vatNumber": "GB553557881",
    "name": "Acme Fleet Services Ltd",
    "address": {
      "lines": [
        "Unit 4, Riverside Park",
        "Canal Road"
      ],
      "town": "Leeds",
      "county": "West Yorkshire",
      "postcode": "LS12 2DX",
      "country": "United Kingdom"
    }
  },
  "status": "active",
  "sicCodes": [
    "49410"
  ],
  "owner": {
    "id": "usr_8f2c",
    "name": "James Patel"
  },
  "domains": [
    "acme.co.uk"
  ],
  "externalIds": [
    {
      "integration": "my-dms",
      "externalId": "CUST-10442"
    }
  ],
  "attributes": {
    "account_tier": "Gold"
  },
  "avatarUrl": "https://api.threadkite.com/avatars/6c1f….png",
  "avatarSource": "upload",
  "contactCount": 3
}

400

Section titled “400”

No VAT number, or not a UK one

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
}

503

Section titled “503”

HMRC is not answering just now

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