Getting Started

The Publisher API is a POST-based RPC-style interface. All endpoints accept JSON request bodies and return JSON responses. There are no GET endpoints or URL-encoded parameters - every interaction follows the same pattern of posting a JSON payload to a named endpoint.

Base URL

All API requests are made against your Publisher instance's base URL. This is the URL provided during onboarding.

https://<your-instance-url>/publisher.v1/<resource>/<action>

Request Format

Every request must include:

• Content-Type: application/json header
• Authorization: Bearer <api-token> header
• A JSON request body (even for operations that take no parameters, send {})

curl -X POST https://<your-instance-url>/publisher.v1/member/get \
  -H "Authorization: Bearer <your-api-token>" \
  -H "Content-Type: application/json" \
  -d '{"member_base_id": "mb_abc123", "ref": "user_001"}'

Response Format

Successful responses return the requested data directly as JSON. List endpoints return a standard envelope with data and page fields.

Single resource:

{
  "id": "mb_abc123",
  "name": "My Audience",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

List response:

{
  "data": [...],
  "page": {
    "page_size": 500,
    "cursor": "eyJpZCI6...",
    "more": true
  }
}

Error Format

Error responses are wrapped in an error object containing a machine-readable code, a human-readable message, additional data, and a trace ID for support requests.

{
  "error": {
    "code": "not_found",
    "message": "The requested resource was not found",
    "data": { "resource": "member" },
    "trace_id": "abc123"
  }
}

Error Codes

Code	HTTP Status	Description
bad_request	400	Invalid request body or parameters
authentication_error	401	Missing or invalid API token
authorization_error	403	Token lacks required permissions
not_found	404	Requested resource does not exist
conflict	409	Operation conflicts with current state

Typical Integration Flow

A complete Publisher integration involves these steps:

1. Create API tokens for your services (read and write access)
2. Create a memberbase - your audience container
3. Define an attribute schema for targeting metadata
4. Sync members into the memberbase via bulk upsert
5. Set member attributes for targeting and segmentation
6. Create ad units defining your advertising surfaces
7. Ingest transactions as card payment events occur
8. Deliver ads by calling the list-eligible endpoint for a member + ad unit
9. Record impressions when creatives are displayed
10. Manage clips when members activate deals
11. Enroll members in loyalty programs via stamp collections

Each section of this guide covers one of these areas in detail.

Key Concepts

• Memberbase - A named container for members (your audience pool)
• Member - An individual user, identified by an external ref you control
• Attribute - A typed key-value pair on a member, used for targeting
• Ad Unit - A named advertising slot with a format and channel
• Deal - An advertising offer configured on the K42 platform and delivered to eligible members
• Clip - A member's activation of a deal (like clipping a coupon)
• Impression - A recorded view of a deal creative by a member
• Stamp Collection - A member's enrollment in a loyalty program