Attributes

Attributes are typed key-value pairs attached to members. They enable audience targeting, segmentation, and personalisation of ad delivery.

The delivery engine evaluates member attributes when determining which deals are eligible - for example, showing premium offers only to members whose tier attribute is "gold" or who are within a certain age bracket.

Setting Attributes

Set one or more attributes on members in a single request. Each entry specifies the member, the attribute key (as defined in the attribute schema), and the value:

curl -X POST https://<your-instance-url>/publisher.v1/member.attributes/set \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "member_base_id": "mb_abc123",
    "attributes": [
      { "member_id": "m_x1y2z3", "attribute_key": "tier", "value": "gold" },
      { "member_id": "m_x1y2z3", "attribute_key": "lifetime_spend", "value": 2500 },
      { "member_id": "m_a4b5c6", "attribute_key": "tier", "value": "silver" },
      { "member_id": "m_a4b5c6", "attribute_key": "dob", "value": "2024-01-15T00:00:00Z" }
    ]
  }'

If an attribute already exists on a member, its value is overwritten. Attributes not included in the request are left unchanged.

If you want to delete attributes you can do so selectively by member IDs and/or attribute keys. The member_base_id is always required to scope the deletion:

{
  "member_base_id": "mb_abc123",
  "member_ids": ["m_x1y2z3"],
  "attribute_keys": ["tier"]
}

Or delete all attributes in a memberbase:

{
  "member_base_id": "mb_abc123",
  "delete_all": true
}

Type Validation

Values must match the type declared in the attribute schema:

Schema Type	Valid Values
string	"gold", "active"
number	42, 99.5
boolean	true, false
date	"2024-01-15T10:30:00Z" (ISO 8601)

Setting a value that does not match the schema type returns an invalid_attribute_key error.

Listing Attributes

Retrieve all attributes for a specific member:

{
  "member_id": "m_x1y2z3"
}

Response:

{
  "attributes": [
    {
      "id": "attr_001",
      "member_id": "m_x1y2z3",
      "member_base_id": "mb_abc123",
      "attribute_key": "tier",
      "value": "gold"
    },
    {
      "id": "attr_002",
      "member_id": "m_x1y2z3",
      "member_base_id": "mb_abc123",
      "attribute_key": "lifetime_spend",
      "value": 2500
    }
  ]
}

Effect on Delivery

Attribute changes take effect immediately. The next call to the list-eligible endpoint for a member will evaluate their current attribute values against placement targeting rules.

Syncing Recommendations

For keeping attributes in sync with your source systems:

1. Event-driven updates - Set attributes in real time as user properties change in your system (e.g. tier upgrade, preference change). This ensures delivery targeting is always current.

2. Periodic batch sync - Run a scheduled job that sets attributes for all members. The set endpoint is idempotent - setting the same value again is a no-op in terms of data correctness.

3. Incremental sync - Track changes in your source system and only send attribute updates for members whose properties have changed since the last sync.

For most integrations, a combination of event-driven updates for critical attributes (like tier or subscription status) and periodic batch sync for less time-sensitive data works well.