Open a stage for a person

POST

/audience/management/v1/individuals/{id}/stages/{stage}

const url = 'https://api.ebitex.io/audience/management/v1/individuals/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/stages/example';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"facts":{}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.ebitex.io/audience/management/v1/individuals/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/stages/example \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "facts": {} }'

Opens a pass for the person in a stage (awareness, acquisition, conversion, retention or advocacy), in the stage’s initial state. facts is an object of the stage’s own facts (for example campaign and medium for awareness, score for acquisition, kind and valueMinor for conversion); a fact the stage does not have is refused, never ignored.

A person has at most one open pass per stage: opening one that is already open is refused.

A key holds no role. It can fire a transition only when that transition has no role allow-list; one that does answers 403 transition_not_allowed. A key never holds the permission that overrides a role rule an Owner set, because anyone who can mint a key could otherwise use it to override one. The key’s name, and the fact that a key made the move, are what the person’s history and the organization’s activity log record.

Key: an Audience management key with audience.management.write (write also needs read; erase needs both).

Authorizations

apiKey

Parameters

Path Parameters

required

string format: uuid

stage

required

string

Request Body^required

application/json

object

facts

One of:

null
object

null

Example^generated

{
  "facts": {}
}

Responses

201

{ "id", "stage", "state": { "id", "name", "kind", "isTerminal" }, "outcome", "openedAtUtc", "stateEnteredAtUtc", "closedAtUtc", "facts": { … }, "source": { "kind", "key", "label" }, "availableTransitions": [ { "id", "name", "toStateId" } ], "rowVersion", "campaignId", "campaign": { "id", "name", "kind" } }. On an awareness pass, campaignId and campaign are read-only: the campaign the pass’s campaign fact resolves to (an alias the organization already holds, or an external campaign registered the first time the text is seen). Both are absent on any other stage and when the text resolves to nothing.

400

validation_failed: a fact is invalid. unknown_fact: the stage has no such fact.

401

missing_api_key or invalid_api_key: no key was sent, or it is unknown, revoked or expired, or it was not created from the Audience settings page.

402

payment_required: the organization’s subscription needs attention.

403

scope_denied: the key lacks this route’s scope. ip_denied: the caller’s address is outside the key’s allowed ranges. app_not_available: Audience is not enabled for the organization.

404

individual_not_found or stage_not_found.

not_found: no such route.

409

stage_already_open: the person already has an open pass in this stage. individual_merged: the person was merged into another; use the survivor.

429

rate_limited: the key spent its requests-per-minute budget; Retry-After says how long to wait. too_many_failed_authentications: too many bad keys from this address.