Create or update an account

PUT

/audience/management/v1/accounts/{externalId}

const url = 'https://api.ebitex.io/audience/management/v1/accounts/example';
const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"name":"example","attributes":{},"attribution":{"source":"example","medium":"example","campaign":"example","isEmpty":true}}'
};

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

curl --request PUT \
  --url https://api.ebitex.io/audience/management/v1/accounts/example \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "example", "attributes": {}, "attribution": { "source": "example", "medium": "example", "campaign": "example", "isEmpty": true } }'

Creates the account when no account has this external id, or updates it. { "name", "attributes": { … }, "attribution": { "source", "medium", "campaign" } }: a name replaces the name (a new account without one is named by its external id); attributes are merged key by key over the existing values, so a key you do not send stays as it is and a key sent as null is cleared. Values are checked against the account fields the organization defines in Audience settings. attribution is the account’s first touch (where it came from, for example the UTM values of the visit that started a trial): it is recorded once, on an account that has none, and never changed afterwards, so sending a different one later is ignored. Each member is at most 100 characters; a missing one is recorded as (none). Sending the same body twice changes nothing.

Accounts are optional and off until the organization turns them on in Audience settings; every account route answers 409 accounts_not_enabled until then. An account is a group of people the organization tracks as one thing (a company, a household, a school). It is identified by an external id you supply (for example your own customer id), which is case-sensitive and unique in the organization: there is no fuzzy matching, so two accounts are the same account only when the external id is the same. A person can belong to any number of accounts, with an optional role in each.

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

Authorizations

apiKey

Parameters

Path Parameters

externalId

required

string

Request Body

application/json

One of:

null
object

null

Example^generated

{
  "name": "example",
  "attributes": {},
  "attribution": {
    "source": "example",
    "medium": "example",
    "campaign": "example",
    "isEmpty": true
  }
}

Responses

200

{ "id", "externalId", "name", "attributes": { … }, "source": { "kind", "key", "label" }, "memberCount", "createdAtUtc", "updatedAtUtc", "rowVersion", "firstTouch": { "source", "medium", "campaign", "campaignId" } }; firstTouch is absent until a first touch is recorded. 201 when it was created, 200 when it already existed.

400

validation_failed: a field is invalid; a custom field is keyed attributes.<key>.

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

quota_exceeded: creating this account would pass the plan’s account limit (audience.max_accounts); quotaKey names it. Updating an existing account is never refused.

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

not_found: no such route.

409

accounts_not_enabled: the organization has not turned accounts on.

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.