Find a company on Companies House

GET

/v1/companies/lookup

curl --request GET \
  --url 'https://api.threadkite.app/v1/companies/lookup?q=Acme%20Fleet' \
  --header 'Authorization: Bearer <token>'

• Threadkite API

By name or company number, best matches first (up to 10). For organisations in the UK, when Threadkite has Companies House set up (companiesHouse in the company settings); otherwise 404. Search results leave out SIC codes: look the number up for them. Officers and owners are never fetched.

Authorizations

• api_key
  companies:read

Parameters

Query Parameters

q

required

A company name or number

string

>= 2 characters <= 160 characters

Example

Acme Fleet

A company name or number

Responses

200

Media typeapplication/json

object

data

required

Best matches first (up to 10)

Array<object>

object

companyNumber

required

string

name

required

Its registered name

string

knownAs

required

The name it is known by: legal words left off, in title case

string

status

required

Companies House’s word: active, dissolved, liquidation…

string

nullable

companyType

required

string

nullable

address

required

One of:

object

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

incorporatedOn

required

string format: date

nullable

dissolvedOn

required

string format: date

nullable

sicCodes

required

Its SIC codes; null in search results (look the number up for them)

Array<string>

nullable

Example

{
  "data": [
    {
      "companyNumber": "01234567",
      "name": "ACME FLEET SERVICES LIMITED",
      "knownAs": "Acme Fleet Services",
      "status": "active",
      "companyType": "ltd",
      "address": {
        "lines": [
          "Unit 4, Riverside Park",
          "Canal Road"
        ],
        "town": "Leeds",
        "county": "West Yorkshire",
        "postcode": "LS12 2DX",
        "country": "United Kingdom"
      },
      "incorporatedOn": "2004-05-12",
      "sicCodes": [
        "49410"
      ]
    }
  ]
}

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

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

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

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

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

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

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