Export API · Guide

Get a support object

Retrieve the values in a Demandbase support object, such as JobLevel, so you can validate filters and map returned IDs before creating or interpreting an export.

GET/v1/reference/{object}Authentication: Bearer API key

Before you start

Authenticate every call

Store your Demandbase API key in a secret such as DB_API_KEY. The example below reads it from an environment variable so the key never appears in source control or command history.

Choose the object you need

Replace {object} with a supported reference object. This example uses JobLevel because its returned values can be used while building export filters and downstream mappings.

Use the response as the source of truth

Object values can evolve. Fetch the current list when your integration starts or refreshes its configuration instead of hard-coding labels and IDs indefinitely.

Common workflows

Populate a filter picker

Fetch a support object, display the returned names, and submit the selected identifiers to the export workflow that needs them.

Validate configuration

Compare configured values with the response before creating a job. This catches renamed, removed, or unsupported values before they become a failed export request.

Refresh a local cache

Cache the response for your application’s normal configuration lifetime, then refresh it when an administrator changes export settings or when a request reports an invalid value.

Quickstart

Step 1 · Send the request

Use this cURL request as the baseline implementation. It calls the support-object endpoint directly, passes the object name in the path, and sends the API key in the Authorization header.

curl --request GET \

--url https://uapi.demandbase.com/data/export/v1/reference/IdealBuyingGroup \

--header "Authorization: Bearer $DB_API_KEY" \

--header "Accept: application/json"

In application code, keep the method, path, and authentication header aligned with this example. Change only the object name after confirming that the object is supported for your account and workflow.

Step 2 · Read the response

A successful response identifies the object and returns its available values in data. Persist the fields your integration needs, but retain the original object type so responses from multiple reference objects cannot be mixed.

{

"objectType": "JobLevel",

"data": [

{

"id": 1,

"name": "C Level"

}

]

}

Request anatomy

Part	Example	Why it matters
Method	`GET`	Reads the current support-object values without creating or changing an export job.
Path	`/v1/reference/{object}`	Replace `{object}` with the exact supported object name, including capitalization such as `JobLevel`.
Authentication	`Authorization: Bearer $DB_API_KEY`	Identifies the Demandbase account and controls whether the object can be read.
Accept header	`application/json`	Requests the JSON representation consumed by the example response and most client libraries.

Code reference: The cURL block above is the canonical request for this guide. When you translate it to JavaScript, Java, Python, or another client, preserve the same GET method, /v1/reference/JobLevel path, and Bearer authentication header.

Response anatomy

Field	Type	How to use it
`objectType`	string	Confirms which reference object was returned, for example `JobLevel`.
`data`	array	Contains the available object values. Iterate this array rather than assuming a fixed number of values.
`data[].id`	string or number	Stable value used by your mapping or downstream filter logic when the API expects an object identifier.
`data[].name`	string	Human-readable label for a selector, audit log, or configuration screen.
`data[].description`	string, when returned	Optional explanation that can help users distinguish similar values.

Rules and constraints

Use the exact reference-object name in the path. Treat object names as case-sensitive and do not URL-encode a slash or add a second path segment.
Do not send a request body for this GET endpoint. The object selector belongs in the path shown in the cURL example.
Keep the API key server-side. If the call is made from a browser, proxy it through a trusted service so the credential is not exposed.
Use the returned values to drive configuration, but do not assume that labels, ordering, or the number of values will remain constant.
Fetch the object again when a dependent export request returns an invalid-value error or when you refresh the integration’s configuration.

Empty results: A successful response can contain an empty data array when the requested object has no available values for the account. Treat that as a valid no-options state, show an actionable empty state in your UI, and do not retry indefinitely.

Errors and recovery

Handle non-success responses explicitly so your integration can report the object name, request ID, and corrective action. The status alone is not a substitute for logging the response body safely.

Status	Meaning	Recovery
`400`	The object name or request shape is invalid.	Compare the path with the supported-object list, correct capitalization or encoding, then retry once.
`401`	The API key is missing, expired, or not accepted.	Load the current key from the server-side secret store and verify the `Authorization: Bearer` header before retrying.
`403`	The key is valid but the account is not permitted to read this object.	Stop repeated retries, confirm account entitlements and object access, and contact Demandbase support if access should be available.

Integration pattern: Log the HTTP status, endpoint, object name, and a redacted response body. Return a user-facing message that distinguishes a bad object name, an authentication problem, and an entitlement problem.

Next steps

Use the values returned here to configure an export request, then follow the detailed endpoint contract for Get Support Object. For the broader sequence, continue to Create an Export Job and Check Export Job Status.

Get reference data fields for an object — Guide