Authentication

Every request to the LineHQ Public API carries an API key. This page covers getting one, what each permission allows, the limits, the errors you can get back, and how ids and lists work.

Base URL: https://app.linehq.co.uk/api/v1

API keys

An API key belongs to one LineHQ account and acts as the person who created it. The account owner can create keys, and so can a member the owner has allowed to manage API keys. Keys are created in the LineHQ portal; the key itself is shown once, so store it somewhere safe. Revoke a key in the portal and it stops working straight away.

Send the key in the Authorization header of every request:

curl "https://app.linehq.co.uk/api/v1/me" -H "Authorization: Bearer $LINEHQ_API_KEY" -H "Accept: application/json"

GET /me answers with the account, the user the key acts as, and the permissions it holds, so it's the quickest way to check a key works.

Permissions

Each key holds the permissions chosen when it was created. Every key can read. Give a key only what your integration needs: a key handed to another system can do anything its permissions allow.

Some changes can't be made with an API key at all, such as routing, caller ID, texts and devices: those belong to the LineHQ app and the portal.

Account roles

Each operation in the reference states the account role it needs. Owner or member means any user of the account; owner only means the key must belong to an account owner, whatever its permissions. A key is refused once its user leaves the account.

Rate limits

Each user can make 60 requests a minute, shared by all their API keys and by their own LineHQ app and AI assistant sessions. Some operations are limited further:

Over a limit, you get 429 with a Retry-After header: wait that many seconds before trying again.

Errors

Errors answer with JSON carrying a plain-English message.

A validation error looks like this:

{
  "message": "The display name field is required.",
  "errors": {
    "display_name": ["The display name field is required."]
  }
}

When the account doesn't have Integrations

Calls, messages, contacts and adding webhooks need the Integrations add-on; the operations that do are marked in the reference. An API key on an account without it is refused with 403 and this body (LineHQ's own apps are never refused):

{
  "reason": "addon_required",
  "capability": "integrations",
  "message": "This needs the Integrations add-on. The account owner can add it from the plans page.",
  "pricing_url": "https://linehq.co.uk/pricing"
}

reason is addon_required (the plan can add it), plan_required (a different plan is needed), account_inactive (the account is paused) or platform_disabled (LineHQ has it switched off). Act on reason and capability; message is for people and its wording may change.

Ids

Records are addressed by opaque ids: most by their public_id, such as 8kQ2mVn4Lr7Tz1Xc9Bw3Hd6Fs0Jy5Pa2; notifications by their id and webhook deliveries by their event_id, both UUIDs. Store ids as text and don't rely on their length or characters. Some responses also carry a numeric id that isn't documented: don't store or send it, as it may disappear.

Lists and pagination

Long lists come a page at a time. Ask for a page with page (from 1) and its size with per_page (usually up to 100). Each page carries:

Follow next_page_url until it's null. Numbers and blocked callers come whole in data, and receipts are the latest 48.

This page as Markdown, for AI tools: https://linehq.co.uk/developers/authentication.md