IDs and Hierarchy

The Future Demand API uses a handful of short identifiers that show up everywhere. This page is the reference for what they mean.

​

At a glance

​

Identifier rules

​

partner_id

• Always present on a Cognito-authenticated user’s cognito:groups claim.
• Pattern: partner-id-<slug> or fd<digits> for legacy partners.
• Send as X-Preferred-Partner-Id header on every authenticated request.
• Immutable for the lifetime of the partner.

​

client_id

• Returned as id from GET /partners/.
• Same entity as partner_id but in an internal numeric/string form.
• Required only by a few legacy endpoints; prefer partner_id wherever both are accepted.

​

eid (event id)

• Returned as id on every event payload. The reference webapp aliases it to eid when constructing URLs (api/events.js:12,179).
• Used as a path segment: /events/{eid}/..., /setup_processes/{eid}, /campaigns/{eid}/....
• Stable for the life of the event. Renaming or rescheduling the event does not change it.

​

tc (taste cluster)

• A string label for a cluster, scoped to one event + one run.
• Used as a path segment for per-cluster operations: /package_builder/packages/{packageId}/{tc}/customer_list, /campaigns/{eid}/{tc}/{tc_run_id}/creative.
• May contain spaces or hyphens — URL-encode in path segments.
• The reference webapp slugifies it (tc.replace(/\s+/g, "-")) when composing cid, but does not slugify it when sending as a path segment to per-cluster endpoints. Mirror that.

​

tc_run_id

• Integer (or short string) identifying one generation of the cluster set for an event.
• Old runs remain readable so existing campaigns stay valid. A new run does not invalidate older runs.
• When listing clusters for an event, you’ll typically receive the latest run. Campaigns store the run they were created against — preserve it.

​

cid (campaign id)

• Computed client-side as ${tc_run_id}_${eid}_${tc-slug} (see webapp/src/api/campaigns.js:54).
• Used to navigate within your own UI; the API mostly accepts the three components separately as path segments. Don’t send cid as a single parameter unless the endpoint explicitly wants it.

​

audience_id / saved_audience_id

• Issued by the upstream ad platform (e.g. Meta) once a Wave campaign is published. Surfaced back as audience_id on campaign records and saved_audience_id on per-cluster edits.

​

package_id

• Returned from POST /package_builder/packages as { id }. Use it for every subsequent operation on the package (status poll, content fetch, CSV download, regenerate).

​

Special partner identifiers

Some Cognito groups grant elevated capability:

​

Common pitfalls