Quickstart

This page goes from nothing to a published decision and its receipt using only curl against the hosted sandbox. Every call below is a documented /v1 route; the API reference has the full request and response shapes and a playground that runs them for you.

Mint sandbox credentials

There is no sign-up. One call gives you a tenant of your own with a personal API key, OAuth client credentials and a webhook signing key.

Mint credentials

curl -s -X POST https://sandbox.composer.id/v1/sandbox/keys \
  -H 'Content-Type: application/json' \
  -d '{"label": "my-first-key"}'

Response (abridged)

{
  "tenant": "tn_RjH3CJm8SlH6",
  "api_key": "sk_sandbox_...",
  "client_id": "cid_...",
  "client_secret": "cs_...",
  "webhook_signing_key": "whsec_...",
  "expires_at": "2026-10-22T11:26:29Z",
  "token_endpoint": "/v1/oauth/token"
}

Save the api_key; the secrets are shown once. Everything you create is visible only to credentials from this tenant.

Keep it in your shell

export KEY=sk_sandbox_...
export BASE=https://sandbox.composer.id/v1

Check you are in

The index

curl -s $BASE -H "Authorization: Bearer $KEY"

The index lists every route and reports "durable": true, which means your intents survive between calls. A missing or wrong key is a 401.

Create an intent

An intent is the decision Triage made, as a record. The payload is yours; composerID mints the intent_id.

Create

curl -s -X POST $BASE/intent \
  -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{
    "payload": {
      "channel": "contingent_hire",
      "role_title": "Data Engineer",
      "start_date": "2026-11-02",
      "location": {"country": "gb"}
    }
  }'

The 201 response is the intent record: an intent_id beginning itn_, intent_version: 1, and your payload. Keep the id.

Keep it in your shell

export ID=itn_...

Plan and preflight

/plan tells you which destinations this intent would publish to. /preflight checks it against one destination’s required fields before anything is sent.

curl -s -X POST $BASE/plan \
  -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d "{\"intent_id\": \"$ID\"}"

curl -s -X POST $BASE/preflight \
  -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d "{\"intent_id\": \"$ID\", \"platform\": \"fieldglass\"}"

A 200 means the destination has everything it needs. A 422 means it does not, and the body carries an enrichment_request naming the missing_fields. Answer them and preflight again:

Answer the missing fields

curl -s -X POST $BASE/enrichment-request \
  -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d "{\"intent_id\": \"$ID\", \"answers\": {\"cost_center\": \"CC-7\", \"worker_type\": \"CONTINGENT\"}}"

Enrichment completes the same intent version; it does not create a new one.

See what would be written

Ask composerID for the exact body it would send, without sending it:

Dry run

curl -s -X POST $BASE/publish \
  -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d "{\"intent_id\": \"$ID\", \"platform\": \"fieldglass\", \"dry_run\": true}"

Preview (abridged)

{
  "mode": "create",
  "object_type": "job_posting",
  "profile": "fieldglass.contingent_requisition.v1",
  "carrier_field": "customFields.intentId",
  "idempotency_key": "itn_...-1-fieldglass-job_posting",
  "payload": {
    "jobPostingTitle": "Data Engineer",
    "startDate": "2026-11-02",
    "workLocationCountry": "GB",
    "costCenterCode": "CC-7",
    "workerTypeCode": "CONTINGENT",
    "customFields.intentId": "itn_..."
  },
  "dry_run": true
}

That is the record as the destination’s API would receive it: its own field names, with the Intent ID in the field that carries it. Nothing was stored and no event was recorded. Every destination answers a dry run, so this is how you see what composerID would post to any of them.

Publish, then publish again

Publish

curl -s -X POST $BASE/publish \
  -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d "{\"intent_id\": \"$ID\", \"platform\": \"fieldglass\"}"

Receipt (abridged)

{
  "target_system": "fieldglass",
  "object_type": "job_posting",
  "external_id": "FI-...",
  "idempotency_key": "itn_...-1-fieldglass-job_posting",
  "status": "published",
  "replayed": false,
  "payload": {"jobPostingTitle": "Data Engineer", "...": "..."}
}

The receipt carries the destination’s own record id and the payload that was written: the same body the dry run showed. Run the same publish a second time. You get the same receipt with "replayed": true and no second record. The idempotency key is built from the intent id, its version and the destination, so a retry can never create a duplicate. Change the intent with PATCH /intent/{id} and the version increments; publishing that is new, not a replay.

Read the timeline

Timeline

curl -s $BASE/intent/$ID/timeline -H "Authorization: Bearer $KEY"

Every event so far, in order: created, planned, preflighted, enriched, published. Destination webhooks land here too, verified against your webhook_signing_key and correlated to the same intent_id. The timeline is append-only.

Destinations in the sandbox are mock tenants that behave the way each vendor’s published API says the real one does. The receipt you got is real in every respect except that no vendor system was written to. Each destination page states the field its Intent ID lands in.

Run it locally

The same API runs from the repository with no dependencies beyond Python 3.11.

Local sandbox

git clone https://github.com/jamiegannaway/composer-id
cd composer-id
python3 -m service.server          # http://127.0.0.1:8787/v1, prints a key

And the conformance pack, the eighteen claims this documentation makes, can be run against any deployment, including yours:

Conformance

make conformance BASE=https://sandbox.composer.id/v1 KEY=$KEY

Next steps

Authentication

OAuth 2.0 client credentials, scopes, and which scope each route needs.

Connect a destination

What a destination needs from you, and where the Intent ID lands.

⌘I

Get started

Concepts

Guides

Destinations

Upstream connectors

API reference

Endpoints

Manuscript API (Triage)

Manuscript endpoints

Resources

Run it locally

Next steps

Authentication

Connect a destination

​Run it locally

​Next steps

Authentication

Connect a destination

Run it locally

Next steps