Understanding API Headers, Consumers, and Service IDs

Every API call to Apideck requires specific headers that tell Apideck who you are, which user (consumer) the request is for, and which connector to route it to. This article explains each header and how to use them correctly.

• Required headers for every API call

• How consumer IDs work

• How service IDs work

• Targeting a specific connector vs. letting Apideck choose

• Common header mistakes

Every request to the Apideck Unified API requires these headers:

Here's what a complete request looks like:

curl --request GET \
  --url 'https://unify.apideck.com/crm/contacts' \
  --header 'Authorization: Bearer {API_KEY}' \
  --header 'x-apideck-app-id: {APP_ID}' \
  --header 'x-apideck-consumer-id: account:12345' \
  --header 'x-apideck-service-id: salesforce'

The x-apideck-consumer-id header identifies which of your end users (or accounts) this request belongs to. Every connection, authorization, and API call in Apideck is scoped to a consumer.

You define the consumer ID yourself. It should be a stable, unique identifier from your system. Common patterns include:

• account:12345 - If connections are at the account/organization level

• user:uuid-here - If connections are per individual user

• org_abc123 - Any string that uniquely identifies the entity

When you make a Vault session or an API call with a consumer ID that doesn't exist yet, Apideck creates the consumer automatically. There's no separate "create consumer" step.

Important: The consumer ID you use in your API calls must match the consumer ID used when the user authorized their connection in Vault. If they don't match, Apideck won't find the connection and the request will fail.

The x-apideck-service-id header specifies which connector to use for the request. Service IDs are the connector name in kebab-case:

You can find the full list at developers.apideck.com/connectors.

Always send x-apideck-service-id. If you leave it out, Apideck uses one of the consumer's connections for that Unified API. With only one connection that's the right one, but as soon as the consumer connects a second provider (for example both Salesforce and HubSpot for CRM), a request without the header returns data from whichever connection Apideck finds first, with no error.

Store the service ID the consumer connected in your app and pass it on every call. This avoids surprises when a consumer adds a second connection later. For more on supporting multiple connections per connector, see How to handle multiple connections for one connector in the Account Management section.

Using a different consumer ID than what was used in Vault. If your user authorized Salesforce under consumer ID account:12345, but you make API calls with user:67890, Apideck won't find the connection. Always use the same identifier consistently.

Forgetting x-apideck-service-id when multiple connections exist. If a consumer has connected both Xero and QuickBooks, a call to /accounting/invoices without a service ID returns invoices from one of them, with no error, and it may not be the one you meant. Always specify the connector.

Making API calls from the frontend. The Authorization header contains your API key. If you make calls from client-side code, your key will be exposed. All Unified API calls should be made from your server.

Using the wrong service ID format. Service IDs are always lowercase kebab-case. Salesforce or SALESFORCE won't work - use salesforce.

If a request fails and you're unsure why, check the logs in your dashboard. See How to see the log of a request for how to inspect the full request and response.

Related resources:

• Full list of connectors and service IDs

• How to handle multiple connections for one connector

• Error reference

• Unified API references