Creator Links endpoints

Two endpoints power creator affiliate links: mint the links for a creator, and read that creator’s performance. Both authenticate with the publishable key only; no HMAC.

For the scenario (surfacing links in your creator dashboard, link semantics, geo guidance), see the Creator Links guide.

Authentication

Pass your publishable key in the X-API-Key header (pk_live_* for production, pk_test_* for development). Multi-app projects also send X-Platform: api (requires an API-platform app in the project; without one the response is 401 Invalid API key). A test key mints links and returns stats. The environment is captured when the link is minted, not when it is clicked, because the click is an end user opening a short URL with no key attached. So a link minted with pk_test_* carries the test flag and its clicks are excluded from your analytics, the same as the rest of test-key traffic. A test mint and a live mint of the same creator and campaign are separate links with separate slugs, so testing a creator never taints that creator’s live link. Full model: overview’s Authentication section.

POST /creators/links

Mints (or fetches) the tracking links for one creator. Idempotent: the same creatorId always returns the same linkUrl per campaign, so it is safe to call on every dashboard load. Links are minted for the campaigns enabled for your app, in your configured campaign order (both controlled from the dashboard).

POST https://api.encorekit.com/encore/publisher/sdk/v1/creators/links

Request

interface CreateCreatorLinksRequest {
  creatorId: string;   // required: your own opaque creator identifier, 1-128 chars
}

Field	Type	Required	Description
`creatorId`	string	Yes	Your own opaque identifier for the creator: any stable id from your system (1 to 128 chars). It’s the key everything attributes to; reuse the same value to get the same links back and to read the creator’s stats. Never end-user-visible.

Response

Each entry carries the same presentation fields as POST /offers/catalog (name, perk, badge, prices, the advertiser organization, and the creatives set), plus a payout block, categories, and the creator’s entry-level linkUrl. The one catalog field it drops is the per-creative clickUrl: for creator links the tracking link lives once at the entry level.

interface CreateCreatorLinksResponse {
  creatorId: string;                // echoes the creatorId you sent
  links: Array<{
    campaignId: string;             // campaign this link points to
    linkUrl: string;                // permanent branded short link on link.encorekit.com
    payout: {
      amount: number;               // publisher's share per completion
      currency: string;             // ISO-4217; currently always "USD"
      model: 'CPA' | 'CPC' | 'CPI' | 'CPM';
    };
    name: string;                   // offer name
    perk: string | null;            // value proposition
    badgeLabel: 'free_trial' | 'discount' | null;
    oldPrice: string | null;        // display price before the offer
    newPrice: string | null;        // display price with the offer
    categories: Array<{ id: string; name: string }>;  // filter-tab categories; may be empty
    targetCountries: string[];      // where this campaign converts (ISO 3166-1 alpha-2)
    organization?: {                // the advertiser
      id: string;
      name: string;
      description: string | null;
      url: string | null;
      logoUrl: string | null;
    };
    creatives?: Array<{             // full active set; client picks the primary
      id: string;
      title: string;
      subtitle: string | null;
      description: string | null;
      primaryImageUrl: string | null;
      logoUrl: string | null;
      additionalImages: string[];
      ctaText: string;
      supportedPlatforms: string[]; // 'ios' | 'android' | 'web'
    }>;
  }>;
}

Field	Type	Description
`links`	array	One entry per campaign enabled for your app, in your configured order. Empty array when your app has no eligible campaigns.
`links[].campaignId`	UUID	The campaign this link points to. Correlate with the stats endpoint, which is keyed by the same `campaignId`.
`links[].linkUrl`	URL	The creator’s permanent tracking link on the fixed host `link.encorekit.com` (10-char slug). Stable per `creatorId` per campaign; safe to cache and render on every load. Never expires. Replaces the catalog’s per-creative `clickUrl` at the entry level.
`links[].payout`	object	What you earn on this campaign: `amount` (the publisher’s share per completion, same semantics as `earnings` on the stats endpoint), `currency` (currently always `"USD"`), and `model` (`CPA` \| `CPC` \| `CPI` \| `CPM`). Not present in the catalog response.
`links[].categories`	array	The campaign’s categories (`id` + `name`), for filter tabs on your surface. Additive beyond catalog parity; may be empty.
`links[].targetCountries`	array	Where this campaign converts. Surface it so creators can pick offers matching their audience.
`links[].organization`	object	The advertiser (catalog parity): `id`, `name`, `description`, `url`, `logoUrl`.
`links[].creatives[]`	array	The full active creative set for this offer (catalog parity, minus each creative’s `clickUrl`). Your client picks which to render as primary; use `supportedPlatforms` to curate per surface.

Example

# X-Platform is only needed for multi-app projects; single-app keys can omit it.
curl --location --request POST 'https://api.encorekit.com/encore/publisher/sdk/v1/creators/links' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'X-Platform: api' \
  --header 'Content-Type: application/json' \
  --data '{ "creatorId": "creator_abc123" }'

{
  "creatorId": "creator_abc123",
  "links": [
    {
      "campaignId": "550e8400-e29b-41d4-a716-446655440000",
      "linkUrl": "https://link.encorekit.com/aB3xK9mQ2p",
      "payout": { "amount": 5.00, "currency": "USD", "model": "CPA" },
      "name": "Summer Sale",
      "perk": "3 months of Hulu free",
      "badgeLabel": "free_trial",
      "oldPrice": "$9.99",
      "newPrice": "$0.00",
      "categories": [
        { "id": "d4e5f6a7-0000-4000-8000-000000000001", "name": "Streaming" }
      ],
      "targetCountries": ["US", "GB"],
      "organization": {
        "id": "a1b2c3d4-0000-4000-8000-000000000001",
        "name": "Acme Corp",
        "description": "Streaming, music, and more.",
        "url": "https://acme.com",
        "logoUrl": "https://cdn.encorekit.com/org/acme/logo.png"
      },
      "creatives": [
        {
          "id": "c1d2e3f4-0000-4000-8000-000000000001",
          "title": "Get 3 months of Hulu free",
          "subtitle": "Summer Sale",
          "description": "Limited-time offer for new subscribers.",
          "primaryImageUrl": "https://cdn.encorekit.com/creative/hero.png",
          "logoUrl": "https://cdn.encorekit.com/creative/logo.png",
          "additionalImages": ["https://cdn.encorekit.com/creative/alt.png"],
          "ctaText": "Claim now",
          "supportedPlatforms": ["ios", "android"]
        }
      ]
    }
  ]
}

GET /creators//stats

Reads a creator’s real-time performance: per-campaign aggregates, totals, and a chart-ready daily series.

GET https://api.encorekit.com/encore/publisher/sdk/v1/creators/{creatorId}/stats

Path parameters

Parameter	Type	Description
`creatorId`	string	The same opaque creator identifier you mint links with (1 to 128 chars).

Query parameters

Both date bounds are optional. Omit them for all-time stats, or pass a window to scope everything the endpoint returns: per-campaign aggregates, totals, and the daily series are all filtered to the range.

Param	Type	Required	Description
`startDate`	`YYYY-MM-DD`	No	Inclusive lower bound (UTC date).
`endDate`	`YYYY-MM-DD`	No	Inclusive upper bound (UTC date).

A malformed date or a startDate later than endDate returns a 400.

Response

interface CreatorStatsResponse {
  creatorId: string;      // echoes the creatorId from the path
  startDate?: string;     // echoed only when you supplied one
  endDate?: string;       // echoed only when you supplied one
  currency: string;       // ISO-4217 for EVERY earnings value; currently always "USD"
  campaigns: Array<{
    campaignId: string;   // same id as links[].campaignId from the mint endpoint
    campaignTitle: string;
    clicks: number;       // link opens; each open creates a transaction
    completions: number;  // verified conversions attributed to this creator
    earnings: number;     // your revenue share, in `currency`
  }>;
  totals: {
    clicks: number;
    completions: number;
    earnings: number;
  };
  daily: Array<{          // per-day series across all campaigns, ascending by date
    date: string;         // UTC day, YYYY-MM-DD
    clicks: number;
    completions: number;
    earnings: number;
  }>;
}

Field	Type	Description
`campaigns`	array	Per-campaign breakdown, filtered to the date range when provided. Campaigns with zero activity in range are dropped. Empty array for a creator with no activity in range, or an unknown `creatorId` (a 200, never a 404), so you can render an empty dashboard without special-casing.
`campaigns[].clicks`	integer	Link opens for this creator on this campaign. Each open creates a transaction, so this counts every click, not unique users.
`campaigns[].completions`	integer	Verified conversions attributed to this creator on this campaign.
`campaigns[].earnings`	number	Your revenue share attributed to this creator on this campaign, in the top-level `currency`.
`totals`	object	Sums of `clicks`, `completions`, and `earnings` across all campaigns, within the date range.
`daily`	array	Per-day time series aggregated across all campaigns, within the date range. One entry per day that has activity (zero-activity days are omitted), ascending by `date`. Empty array when there is no activity in range.

Which day a metric lands on. clicks count on the transaction’s created date. completions and earnings count on the completion (verification) date. So a click on the 1st that completes on the 3rd shows its click on the 1st and its completion plus earnings on the 3rd. All dates are UTC, and this is what the daily series and the startDate/endDate filter operate on.

Example

# startDate / endDate are optional; omit both for all-time stats.
curl --location --request GET \
  'https://api.encorekit.com/encore/publisher/sdk/v1/creators/creator_abc123/stats?startDate=2026-07-01&endDate=2026-07-16' \
  --header 'X-API-Key: YOUR_API_KEY'

{
  "creatorId": "creator_abc123",
  "startDate": "2026-07-01",
  "endDate": "2026-07-16",
  "currency": "USD",
  "campaigns": [
    {
      "campaignId": "550e8400-e29b-41d4-a716-446655440000",
      "campaignTitle": "Acme Pro - 3 months free",
      "clicks": 1204,
      "completions": 87,
      "earnings": 261.00
    }
  ],
  "totals": { "clicks": 1204, "completions": 87, "earnings": 261.00 },
  "daily": [
    { "date": "2026-07-15", "clicks": 312, "completions": 21, "earnings": 63.00 },
    { "date": "2026-07-16", "clicks": 289, "completions": 19, "earnings": 57.00 }
  ]
}

Status codes

Code	Meaning
`200`	Success. On `/creators/links`, `links` may be empty if your app has no eligible campaigns. On `/creators/{creatorId}/stats`, an unknown `creatorId` returns 200 with empty `campaigns`/`daily` and zeroed `totals`, never a 404.
`400`	Malformed request: `creatorId` missing or longer than 128 chars, a malformed `startDate` / `endDate`, or `startDate` later than `endDate`. Don’t retry; fix the request.
`401`	Missing or invalid `X-API-Key`. Also returned as `X-Platform header required for multi-app projects` when a multi-app key omits the `X-Platform` header; the key itself is fine, so add the header rather than rotating the key.
`429`	Rate-limited. Back off and retry.
`5xx`	Encore-side failure. Surface a soft error in your dashboard and retry.

Creator Links guide: the dashboard scenario, link semantics, and an end-to-end example.
POST /offers/catalog: the catalog projection these display fields mirror.
API Reference overview: auth and the claim model.

​Authentication

​POST /creators/links

​Request

​Response

​Example

​GET /creators//stats

​Path parameters

​Query parameters

​Response

​Example

​Status codes

​Related

Authentication

POST /creators/links

Request

Response

Example

GET /creators//stats

Path parameters

Query parameters

Response

Example

Status codes

Related