Members

A member is an individual user within a memberbase. Members are identified by a ref - an external reference string that you control. This is your primary key for a member and must be unique within the memberbase.

Publisher does not enforce any format for refs. They can be user IDs, account numbers, or any string meaningful to your system:

• "user_12345"
• "crm-contact-789"

Creating Members

Members are created via the bulk upsert endpoint. If a member with a given ref already exists in the memberbase, their record is updated. Otherwise a new member is created. This idempotent design means you can synchronise your member list on a schedule, or retry requests, without worrying about duplicates or conflicts.

curl -X POST https://<your-instance-url>/publisher.v1/member/bulk-upsert \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "member_base_id": "mb_abc123",
    "members": [
      { "ref": "user_001" },
      { "ref": "user_002" },
      { "ref": "user_003" }
    ]
  }'

The response returns the list of member IDs (newly created or existing):

["m_x1y2z3", "m_a4b5c6", "m_d7e8f9"]

Retrieving a Member

You can look up a member either by their system ID or by their memberbase + ref combination:

By ref (most common):

{
  "member_base_id": "mb_abc123",
  "ref": "user_001"
}

By ID:

{
  "id": "m_x1y2z3"
}

Listing Members

List members within a memberbase with optional filtering and pagination:

{
  "member_base_id": "mb_abc123",
  "pagination": { "limit": 100 },
  "filters": [{ "key": "ref", "in": ["user_001", "user_002"] }]
}

Deleting Members

Remove members in bulk by their IDs:

{
  "member_base_id": "mb_abc123",
  "member_ids": ["m_x1y2z3", "m_a4b5c6"]
}

Deleting a member removes all associated attributes, clips, stamp collections, and transaction history.

Syncing Recommendations

For ongoing member synchronisation:

1. Periodic bulk upsert - Run a scheduled job that upserts your full active member list. The idempotent behaviour ensures no duplicates.
2. Event-driven upsert - Call bulk-upsert in real time as new users are created in your system.
3. Cleanup - Periodically bulk-delete members who are no longer active in your system.

There is no limit on the number of members in a memberbase or the number of members per bulk-upsert call, though smaller batches (1,000-5,000) are recommended for reliability.