POST /users/attributes

Stores a set of targeting attributes against one user so later offer requests are targeted on them without the values traveling in a link. Your hosted offer page URL then carries no attributes at all, just apiKey, userId, and whichever presentation parameters you use.

POST https://api.encorekit.com/encore/publisher/sdk/v1/users/attributes

Call it before you open the offer page for a user, or ahead of your POST /offers/feed, and again whenever what you know about that user changes. To attach attributes to a single request instead of storing them, put them in that request’s own attributes object: a request attribute always wins over the stored one.

Authentication

Pass your publishable key in the X-API-Key header (pk_live_* for production, pk_test_* for development). This is the same guard POST /offers/feed uses, so no new credential is involved. Multi-app projects also send X-Platform.

Store against the app that serves the offers. The set is keyed on the app your key resolves plus userId, so a set stored against one app in a multi-app project is invisible to another. The hosted offer page runs the Web SDK, which sends X-Platform: web, so a multi-app project storing attributes for that page sends X-Platform: web here too.

How the stored set is used

Each call replaces the last one. The write is idempotent on the app plus userId, and the newest set is the whole truth. Attributes are never merged into what was stored before, so send the complete set every time.
There is no expiry. The last set stays authoritative until a newer one arrives, and a data-subject erasure request removes it.
A request attribute always wins. POST /offers/feed, and the POST /offers/search call the Web SDK makes on your behalf, read the stored set only to fill an attribute the request itself omitted. POST /offers/catalog and POST /offers/message do not read it.
Storing an attribute never makes it optional on a request. /offers/feed still requires countryCode and language in its own body, and rejects a request that omits them before the stored set is read. What the store fills on that endpoint is everything else.
The user does not have to exist yet. The first call for a userId creates the user, so there is no ordering requirement against any other endpoint.

Request

Structure

interface StoreUserAttributesRequest {
  userId: string;                  // required: the same end-user id your offer requests use
  attributes: {                    // required: replaces any previously stored set
    // Accepted from any app
    countryCode?: string;          // ISO 3166-1 alpha-2, two uppercase letters
    language?: string;             // BCP-47 language tag
    city?: string;
    state?: string;
    region?: string;
    subscriptionTier?: string;
    monthsSubscribed?: string;
    billingCycle?: string;
    lastPaymentAmount?: string;
    lastActiveDate?: string;
    totalSessions?: string;
    custom?: Record<string, string>;
    age?: number;                  // whole years, integer 0-120; see Sending an age

    // Accepted only from an app declared adults_only
    email?: string;
    firstName?: string;
    lastName?: string;
    mobile?: string;
    phoneNumber?: string;
    postalCode?: string;           // prefer this spelling
    postcode?: string;             // a separate key, not an alias
    latitude?: string;             // decimal degrees as a string
    longitude?: string;            // decimal degrees as a string
    gender?: string;
  };
}

Field Reference

Field	Type	Required	Description
`userId`	string	Yes	Your stable end-user identifier, the same one your offer requests and your offer page URL carry. It is the key the stored set is filed under.
`attributes`	object	Yes	The complete set to store. Replaces any set stored earlier for this user. An empty object is valid and clears the stored set.
`attributes.countryCode`	string	No	ISO 3166-1 alpha-2, two uppercase letters (for example `"US"`, `"GB"`, `"CA"`). Drives geo-targeting and the country dimension on analytics.
`attributes.language`	string	No	BCP-47 language tag (for example `"en"`, `"es"`). Drives creative locale resolution.
`attributes.city`	string	No	Coarse geography, accepted from any app.
`attributes.state`	string	No	Coarse geography, accepted from any app.
`attributes.region`	string	No	Coarse geography, accepted from any app.
`attributes.subscriptionTier`	string	No	Your own tier label (for example `"premium"`).
`attributes.monthsSubscribed`	string	No	Months the user has been subscribed, as a string.
`attributes.billingCycle`	string	No	Your own cycle label (for example `"annual"`).
`attributes.lastPaymentAmount`	string	No	Last payment amount, as a string.
`attributes.lastActiveDate`	string	No	ISO 8601 datetime the user was last active (for example `2024-03-15T14:30:00Z`).
`attributes.totalSessions`	string	No	Session count, as a string.
`attributes.custom`	object	No	Free-form string map for app-specific values (for example `{ "plan": "gold" }`). Values are strings.
`attributes.age`	integer	No	Whole years, `0` to `120`. Accepted from any app. Read Sending an age and What is stored for a user under 18 before you send it: the range rule and what an under-18 age does are both easy to get wrong.
`attributes.email`	string	No	Adults-only apps only. See Attributes that need an adults-only app.
`attributes.firstName`	string	No	Adults-only apps only.
`attributes.lastName`	string	No	Adults-only apps only.
`attributes.mobile`	string	No	Adults-only apps only.
`attributes.phoneNumber`	string	No	Adults-only apps only.
`attributes.postalCode`	string	No	Adults-only apps only. Precise location, unlike `city` and `state`. Prefer this one: it is the spelling every Encore SDK and the offer page URL use.
`attributes.postcode`	string	No	Adults-only apps only. A separate key, not an alias of `postalCode`, and stored under its own name. Accepted for callers whose own schema uses this spelling. Send one or the other, not both.
`attributes.latitude`	string	No	Adults-only apps only. Decimal degrees as a string (for example `"37.7749"`).
`attributes.longitude`	string	No	Adults-only apps only. Decimal degrees as a string (for example `"-122.4194"`).
`attributes.gender`	string	No	Adults-only apps only.

Sending an age

age is an integer count of whole years. It is accepted from every app, whatever that app’s audience declaration says, because it is what narrows which offers a user may be shown rather than something that identifies them.

If you hold only a range, send its lowest end. "13-17" is sent as 13, never 15 and never 17. Sending the middle of a range defeats the check silently: flooring can never mask a minor, and a midpoint can.

An age under 18 does not switch offers off. That user is still served. What changes is that the offers come from age-appropriate inventory only, ranked by the app-level bandit, with no per-user personalization. The response reports minor: true so you can see which branch a user took. The instant you sent the set is recorded, and the age acted on is counted forward from it. A user stored at 17 becomes an adult on schedule rather than staying 17 forever. Send age, never a date of birth. dateOfBirth is refused here: an age carries the same targeting value with far less identifying power.

What is stored for a user under 18

Only age, countryCode, and language are kept. Everything else you sent is discarded, custom included, along with city, state, region, and every subscription and billing field. Those three survive because of what they do. age narrows which offers the user may be shown, countryCode decides where an offer may legally appear, and language picks the creative locale that renders. None of the three chooses an advertiser. Everything else exists to personalize the pick, and personalization is withheld for this user, so storing it would keep data that can never be acted on.

This is silent, and it is not an error. The call returns 200, and the only sign is minor: true in the response. Send subscriptionTier for a 16-year-old and you get success, no warning, and no subscriptionTier in the stored set afterwards.

It is decided per request, from the age that request carried, so this is not a separate integration to build. The same set sent for an adult is stored whole. Once a user is 18, re-send their set and it is stored in full.

Attributes that need an adults-only app

email, firstName, lastName, mobile, phoneNumber, postcode, postalCode, latitude, longitude, and gender are accepted only from an app whose audience is declared adults_only, meaning it is rated 18+ in its store listing. Every other status is refused with a 400, including the default status an app carries before anyone has declared its audience. The refusal names the keys it rejected and stores nothing at all, not even the attributes that would have been allowed:

{
  "error": "These attributes are accepted only from an app rated 18+ in its store listing: email, gender. This app's child_audience_status is \"unknown\", not \"adults_only\". Re-send without them, or have the app's audience declaration corrected first."
}

Re-send without those keys, or have the app’s audience declaration corrected in the dashboard first. Neither postalCode nor postcode reaches offer selection today, so an app that cannot send them loses no targeting by leaving them out.

Attributes that are refused

Key	Why
`dateOfBirth`	Refused from every app, including adults-only ones. Send `age` instead.
`interests`	Not part of this vocabulary. There is no substitute key.
Anything else	Any key not listed in Field Reference is refused rather than ignored, so a typo surfaces as a `400` instead of as targeting that quietly does less.

Response

Structure

interface StoreUserAttributesResponse {
  success: true;
  userId: string;      // canonical user UUID, not the id you sent
  storedAt: string;    // ISO 8601 instant the set was recorded
  minor: boolean;      // true when the age you sent was under 18
}

Field Reference

Field	Type	Description
`success`	`true`	Always `true` on a 200. Non-success outcomes come back as 4xx/5xx; see Status codes.
`userId`	UUID	Encore’s canonical user id, which is not the `userId` you sent. Keep using your own id on every other endpoint.
`storedAt`	string	ISO 8601 instant the set was recorded. This is what a stored `age` is counted forward from.
`minor`	boolean	`true` when the `age` you sent was under 18, `false` otherwise (including when you sent no age). Offers are still served either way. A `true` means this user was served from age-appropriate inventory and that only three attributes were kept from the set you sent. See What is stored for a user under 18.

Example

curl --location --request POST 'https://api.encorekit.com/encore/publisher/sdk/v1/users/attributes' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "userId": "user-123",
    "attributes": {
      "countryCode": "US",
      "language": "en",
      "subscriptionTier": "gold",
      "monthsSubscribed": "14",
      "age": 34,
      "custom": { "machine": "kiosk-4471" }
    }
  }'

{
  "success": true,
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "storedAt": "2026-09-02T10:14:07.412Z",
  "minor": false
}

Status codes

Code	Meaning
`200`	The set was stored and replaces any previous one.
`400`	A gated key from an app that is not `adults_only`, a refused or unrecognized key, an `age` that is not a whole number between `0` and `120`, or a missing `userId`. Nothing was stored. Don’t retry; fix the request. The gate returns the sentence shown under Attributes that need an adults-only app; a schema failure returns the offending field in `details` instead. Both are `{ error, details? }`.
`401`	Missing or invalid `X-API-Key`, or an `X-Platform` value your project has no app for.
`503`	Server temporarily over capacity. Retry with backoff.
`5xx` (other)	Encore-side failure.

Retry guidance

Retrying is safe, but only useful for some failures. The call is an idempotent replace, so sending the same set twice leaves exactly the state one call would have. This is unlike the offer-selection endpoints, where each call mints fresh links and analytics rows. A 400 or 401 is deterministic, so repeating it produces the same refusal: fix the request instead.
Use exponential backoff with jitter (for example 200ms, 1s, 5s, max 3 retries) for transient failures (503 / network).
After exhausting retries, open the offer page anyway. A user with no stored set is served from what the request itself carries, so the worst case is less targeted, never nothing.

Hosted Offer Page: the page these attributes target, and how to move off URL parameters.
POST /offers/feed: the ranked selection that reads the stored set for attributes its own body omits.
API Reference overview: auth and the claim model.

​Authentication

​How the stored set is used

​Request

​Structure

​Field Reference

​Sending an age

​What is stored for a user under 18

​Attributes that need an adults-only app

​Attributes that are refused

​Response

​Structure

​Field Reference

​Example

​Status codes

​Retry guidance

​Related

Authentication

How the stored set is used

Request

Structure

Field Reference

Sending an age

What is stored for a user under 18

Attributes that need an adults-only app

Attributes that are refused

Response

Structure

Field Reference

Example

Status codes

Retry guidance

Related