---
title: "Company name suggestions (free inside a session)"
method: GET
path: "/elements/v1/suggest"
tags: ["Website components"]
---

# Company name suggestions (free inside a session)

`GET /elements/v1/suggest`

## Request

- Base URL: `https://api.companystack.co.uk`
- URL: `https://api.companystack.co.uk/elements/v1/suggest`
- Auth: one of:
  - API key in query parameter `key`
  - HTTP bearer

Up to 5 suggestions on the Free plan and 10 on paid plans, best match first. Suggestions are free inside a session (at most 30 a session); the selection that ends the session counts one request. Limited per visitor (120 a minute) and per key.

## Query parameters

- `q` string, required
- `session` string, uuid, required
- `key` string
- `token` string
- `limit` integer

## Response `200`

Suggestions

- object
  - `suggestions` object[]
    - `company_number` string
    - `company_name` string
    - `company_status` string
    - `status_label` string
    - `company_type` string, nullable
    - `locality` string, nullable
    - `postcode` string, nullable
    - `incorporated_on` string, nullable
  - `session` object
    - `suggestions_left` integer
  - `attribution` object: Show `text` with `licence` wherever the data is shown (the Open Government Licence asks for the statement).
    - `text` string
    - `licence` string
    - `licence_url` string
    - `affiliation` string
    - `url` string

## Other responses

- `400`: Missing or malformed session, or an invalid company number
- `401`: No key, or an invalid or revoked key
- `403`: A publishable key or token from a website it does not list (`origin_not_allowed`: no Access-Control-Allow-Origin, so the page cannot read the answer and nothing is counted), a secret key sent from a browser (`secret_key_in_browser`), an endpoint a publishable key cannot reach (`secret_key_required`), or a scope or company a token does not cover (`scope_not_allowed`, `company_not_allowed`)
- `429`: A per-visitor or per-key limit (`rate_limited`), the end of a session (`session_exhausted`: start a new one), the key's daily cap (`key_daily_cap`) or the account's quota (`quota_exceeded`). Retry-After says when to try again.

---

[API](https://skmtc.dev/companystack/apis/companystack-api.md) · [All operations](https://skmtc.dev/companystack/apis/companystack-api/llms.txt) · [OpenAPI document](https://skmtc.dev/companystack/apis/companystack-api/revisions/8f3234237d2d?raw)