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.

If the consumer has only one authorized connection for the Unified API you're calling, you can omit x-apideck-service-id - Apideck will route to the only available connection automatically.

If the consumer has multiple connections for the same Unified API (e.g., both Salesforce and HubSpot for CRM), you must include x-apideck-service-id to specify which one. Without it, the request will fail.

A common pattern is to store the consumer's selected service ID in your app and always pass it explicitly. This avoids surprises if 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 will return an error. Always specify the connector when there could be multiple.

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