Intellayer Public API

What this is. The API lets other software read and change your records with an API key you create on Settings > API and webhooks. The key decides what that software may see and do. If someone else builds the connection for you, make a key there and give it to them; the rest of this page is for them.

Getting started

Read and write your organisation's records from your own systems. Every request carries an API key made on Settings > API and webhooks.

Every address on this page starts with https://api.intellayer.app/api/public/v1. The full description for tools (Postman, n8n, Make, Zapier) is the OpenAPI document: /api/public/v1/openapi.json.

1. Make a key on Settings > API and webhooks, choosing the role it acts with. Copy it: it is shown once.
2. Check it works by asking who it is:

   curl -H "Authorization: Bearer $API_KEY" https://api.intellayer.app/api/public/v1/me

   If your organisation takes access tokens only, get a token first (Access tokens).
3. Read records, a page at a time: GET /api/public/v1/leads?page=1&pageSize=50.

To hear about changes as they happen instead of asking again and again, see the Webhooks guide.

Signing in

A key acts as the person who made it, limited to the role chosen for it: it sees and changes only what that role allows, and stops working when it is revoked or expires, or when its creator loses access.

Every key has a client ID, its 12-character public id (the part after ascpk_), shown under each key on Settings > API and webhooks and in the dialog when the key is made. Unless it was made with No secret it also has a secret: the whole key, shown once. An integration signs in in one of three ways:

1. The key on every call. The simplest: send the key with each request. Refused while access tokens only is on.
2. An access token from the key. Send the client ID and the key to the token endpoint, get a token that works for one hour, and send the token with each request instead of the key.
3. An access token from a key pair. The integration keeps a private key that never leaves it and proves who it is with that instead of a secret, then uses the same hour-long token.

Whichever way, every check of the key (revoked, expired, suspended, allowed addresses, role) runs on every call.

The key on every call

Authorization: Bearer ascpk_xxxxxxxxxxxx_…

or X-Api-Key: ascpk_…, for tools that cannot set Authorization.

Access tokens

Instead of sending the key with every call, an integration can trade it for an access token that lasts an hour, so the key itself crosses the network once an hour at most. POST /api/public/v1/oauth/token, form-encoded, with grant_type=client_credentials (OAuth 2.0 client credentials) and the key as the client: client_secret_basic (Authorization: Basic base64(client_id:client_secret)) or client_secret_post (client_id and client_secret in the form). The client_id is the key's client ID (shown under each key on Settings > API and webhooks, and in the dialog when the key is made); the client_secret is the whole key.

curl -s -X POST https://api.intellayer.app/api/public/v1/oauth/token \
  -u "$CLIENT_ID:$API_KEY" -d grant_type=client_credentials

{ "access_token": "eyJ…", "token_type": "Bearer", "expires_in": 3600 }

Send it as Authorization: Bearer <access_token>. Every check of the key runs on every call made with the token: revoke, suspend or limit the key and its tokens stop or are limited at once. Ask for a new token shortly before expires_in runs out; an expired one gets 401 with errors.apiKeys.tokenInvalid.

Node.js:

const res = await fetch(`${apiHost}/api/public/v1/oauth/token`, {
  method: 'POST',
  headers: { Authorization: 'Basic ' + Buffer.from(`${clientId}:${apiKey}`).toString('base64') },
  body: new URLSearchParams({ grant_type: 'client_credentials' }),
});
const { access_token, expires_in } = await res.json();
const leads = await fetch(`${apiHost}/api/public/v1/leads`, { headers: { Authorization: `Bearer ${access_token}` } });

Errors follow RFC 6749: 400 with unsupported_grant_type or invalid_request (no grant, or more than one way of authenticating), 401 with invalid_client for an unknown client or a wrong secret, and 401 invalid_client with the key's own error in error_description (for example errors.apiKeys.revoked or errors.apiKeys.ipNotAllowed). The endpoint takes 30 requests a minute per address; failed attempts count towards the key's unusual-use alerts.

Key pair sign-in

A key can hold the integration's public key instead of, or as well as, a secret (private_key_jwt). The integration then proves itself at the token endpoint with a short assertion signed by its private key (RFC 7523), and the private key never leaves it. Register the public key when making the key, or later from its Public key action: PEM (BEGIN PUBLIC KEY or BEGIN RSA PUBLIC KEY) or a JWK; RSA of at least 2048 bits, or EC P-256 or P-384. Tick No secret and the key has no secret at all: it works only through the token endpoint. Registering or replacing a public key asks for your second factor and is emailed to the Owners.

# EC P-256 (ES256)
openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 -out client.key
# or RSA (RS256)
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:3072 -out client.key
# the public half, to paste into the settings page
openssl pkey -in client.key -pubout -out client.pub

The assertion is a JWT signed with RS256, ES256 or ES384 (anything else, none and HS256 included, is refused) with these claims: iss and sub the client_id; aud the token endpoint's full URL, https://api.intellayer.app/api/public/v1/oauth/token; exp at most 5 minutes ahead; jti unique (each assertion is accepted once); iat optional. Clocks may differ by up to 60 seconds. Send it as client_assertion with client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer.

Node.js (no libraries):

const { createPrivateKey, sign, randomUUID } = require('crypto');
const key = createPrivateKey(fs.readFileSync('client.key'));
const b64 = o => Buffer.from(JSON.stringify(o)).toString('base64url');
const now = Math.floor(Date.now() / 1000);
const head = b64({ alg: 'ES256', typ: 'JWT' });
const body = b64({ iss: clientId, sub: clientId, aud: tokenUrl, iat: now, exp: now + 120, jti: randomUUID() });
const sig = sign('sha256', Buffer.from(`${head}.${body}`), { key, dsaEncoding: 'ieee-p1363' }).toString('base64url');
const res = await fetch(tokenUrl, { method: 'POST', body: new URLSearchParams({
  grant_type: 'client_credentials',
  client_assertion_type: 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer',
  client_assertion: `${head}.${body}.${sig}`,
}) });

C# (System.IdentityModel.Tokens.Jwt):

using var ec = ECDsa.Create();
ec.ImportFromPem(File.ReadAllText("client.key"));
var now = DateTime.UtcNow;
var assertion = new JwtSecurityTokenHandler().WriteToken(new JwtSecurityToken(
    issuer: clientId, audience: tokenUrl,
    claims: [new Claim("sub", clientId), new Claim("jti", Guid.NewGuid().ToString())],
    notBefore: now, expires: now.AddMinutes(2),
    signingCredentials: new SigningCredentials(new ECDsaSecurityKey(ec), SecurityAlgorithms.EcdsaSha256)));
var response = await http.PostAsync(tokenUrl, new FormUrlEncodedContent(new Dictionary<string, string>
{
    ["grant_type"] = "client_credentials",
    ["client_assertion_type"] = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
    ["client_assertion"] = assertion,
}));

Access tokens only

An Owner can switch the organisation to Access tokens only on Settings > API and webhooks. From then on a key sent with any call other than the token endpoint gets 401 with errors.apiKeys.tokensOnly: only access tokens and key pair sign-in work. Move every integration to tokens before it is turned on.

Key safety and expiry

Format. ascpk_, a 12-character public id, _ and a 49-character secret whose last six characters are a checksum, so a secret scanner can recognise a leaked key without false alarms: \bascpk_[a-km-np-z2-9]{12}_[0-9A-Za-z]{49}\b. Older keys start ak_ and keep working until they expire or are given a new secret.

Expiry. Every key expires: 90 days after it is made unless another date is chosen, a year at most. Its creator and the organisation's Owners are emailed 14 and 3 days before. An expired key gets 401 with errors.apiKeys.expired.

New secret. A key can be given a new secret on the settings page; it keeps its id, role and allowed addresses. The previous secret keeps working for 24 hours, so you can switch without downtime. A second new secret within those 24 hours ends the oldest at once.

Allowed addresses. A key can be limited to IPv4 and IPv6 addresses and ranges (CIDR). A call from anywhere else gets 403 with errors.apiKeys.ipNotAllowed, even with the right key.

Unusual use. The organisation's Owners are emailed when a key is used from a new address or country, its volume jumps, or it keeps being refused. If they have turned on automatic suspension, a key used from a new country or refused again and again with its right secret gets 401 with errors.apiKeys.suspended until an Owner resumes it.

Personal data

A key reads personal data only when it is allowed to (Can read personal data on the settings page; turning it on asks for your second factor and is emailed to the Owners). Keys made before this setting existed keep reading it; new keys do not unless it is ticked. GET /me shows it as canReadPersonalData.

Without it the personal fields are still in every answer, set to null, and the answer carries "redacted": true next to data. The fields: leads and customers: firstName, lastName, email, phone, address, city, district, postalCode, notes; companies: email, phone, notes, taxId, address, city, postalCode (a sole trader's are their own); invoices: billingName, billingVatNumber; proposals: customerName; tasks: description. Writes work as before, though the record returned is redacted too. Finding records by email, and setting a customer's email (a duplicate is refused), get 403 with errors.apiKeys.personalDataRequired, since the answer would say whether that person is on file. Full webhook payloads of a subscription made through such a key are redacted the same way, carry "redacted": true, and their changes name the fields without their values.

Responses and limits

Every response is { "success", "data", "error", "meta" }. Lists take page (from 1) and pageSize (up to 100); meta carries totalCount. Errors carry a stable error.code. Under each endpoint below, Response names the object inside data.

Your organisation has a number of requests per minute, set by its plan and shared by all its keys. A key can also be given a lower limit of its own. Past either you get 429 with Retry-After in seconds; GET /me shows the key's limit.

Endpoints

Companies

Customers

Invoices

Leads

Me

OAuth

Pipeline stages

Proposals

Tasks

Webhooks

Objects

ApiError

ApiResponse

PaginationMeta

PublicCompany

PublicCompanyWrite

PublicCustomer

PublicCustomerCreate

PublicCustomerUpdate

PublicDeleted

PublicInvoice

PublicKeyDto

PublicLead

PublicLeadCreate

PublicLeadUpdate

PublicMeDto

PublicOrganizationDto

PublicPermissionDto

PublicPipelineStage

PublicProposal

PublicTask

PublicTaskCreate

PublicTokenError

PublicTokenRequest

PublicTokenResponse

PublicWebhookCreated

PublicWebhookEvent

PublicWebhookSubscribe

PublicWebhookSubscription

WebhookChange

A field an *.updated event changed. previous and current only in full payloads, and not for a key that may not read personal data.

WebhookThinData

A thin webhook payload's data: the record's id, its type, and the API path that returns it.