Getting started with the affiliate tracking API

At some point most growing affiliate programs want their data somewhere other than a dashboard — in a data warehouse, a BI tool, an internal ops panel, or a workflow that creates partners automatically when they sign up on the program's own website. That is what the API is for. It gives your own systems read access to your reports and records, plus the ability to create affiliates programmatically. It is a standard HTTPS-and-JSON API, so any language or tool that can make a web request can use it — no SDK required, though one certainly helps. This guide is the orientation: your first call, how authentication works, what the v1 endpoints do, and the response shape they all share.

There is a complete, interactive reference with every endpoint, its parameters and responses, and a live "try it" console you can run with your own key. This article is the map; that reference is the territory. Read this to understand the shape of the API, then use the reference for the exact fields.

Before you start: create a key

Every request is authenticated with an API key, so the first step is creating one in your account's security settings under API access. Copy the key the moment it is shown — for security it appears only once, and if you lose it you create a new one rather than recovering the old. Treat the key like a password: it belongs on your server, never in client-side code, a mobile app, or a public repository.

Keys carry permissions. Read access is included with every key, while the ability to create affiliates is a separate permission you grant deliberately. This means you can hand a read-only key to a reporting integration with no risk that it can modify anything, and reserve write-capable keys for the specific systems that need them.

Authentication

Send your key on every request in the X-Api-Key header. A minimal first call looks like this — a GET request to the ping endpoint with the key in the header: curl "https://YOUR_API_BASE/v1/ping" -H "X-Api-Key: llj_live_...". If your HTTP tooling only supports a standard authorization header, Authorization: Bearer llj_live_... works exactly the same way.

The ping endpoint is the connection test, and it should be the first call you make from any new integration. It returns your account name and the key's permissions, so a successful ping confirms three things at once: the key is valid, your network can reach the API, and the key has the scopes you expect. Get ping working before you write another line — most integration problems are really authentication problems, and ping isolates them immediately.

The read endpoints

Every key can read. The read endpoints fall into two groups: row-level reports and record lookups.

The row-level report endpoints return the raw activity behind your numbers. The clicks report returns row-level clicks newest first, and the conversions report returns row-level conversions the same way. These are what you pull into a warehouse to build your own dashboards, or query to reconcile against your ad spend. The reports guide explains what each field means and which report answers which question — the API returns the same underlying data the interface shows, so that guide is the best companion to the report endpoints.

The record endpoints return your program's objects: offers, affiliates, and campaigns, each available both as a list and as a single record by ID. These let you mirror your program structure into your own systems — syncing your partner list into a CRM, for instance, or checking a campaign's terms from an internal tool.

The write endpoint: creating affiliates

If a key has the create-affiliates permission, it can create affiliates programmatically. This is the endpoint most programs reach for, because it lets partners who sign up on your own website flow straight into the platform without anyone re-keying them.

At minimum a new affiliate needs a name and a contact email. Beyond that you can send a fuller profile — contact name, website, notes, traffic details like media type and traffic source, target countries, and a mailing address — and everything you send is stored on the affiliate's record for your team to review. There is a thoughtful safety property here: if the email already belongs to one of your affiliates, the API returns a conflict response carrying the existing affiliate's ID rather than creating a duplicate. That makes the call safe to retry — a network hiccup that leaves you unsure whether the create succeeded can be retried without risk of creating the partner twice.

You can also control whether a new affiliate goes live immediately or lands in a review queue. Sending a pending status creates the affiliate for review rather than making them active — they appear in your program's pending queue, where your team accepts them (they go active and receive a welcome email) or declines them with a reason. Leaving the status out, or sending active, creates a ready-to-use affiliate immediately. This is the mechanism behind "sign up on our site, we'll review you" — your website posts the signup with a pending status, and your team works the queue in the dashboard. The affiliate-facing consequences of being approved — building a link, grabbing creatives — are covered in getting your tracking link.

Filters and pagination

The report endpoints accept a date range with from and to dates, defaulting to the last thirty days if you omit them, plus filters to narrow by affiliate, offer, or campaign. Every list endpoint paginates with a page number and a per-page size, and the response carries a metadata block with the total count and total pages so you always know how much more there is to fetch.

The practical pattern for pulling a full dataset is to loop: request the first page, read the total pages from the metadata, and keep requesting until you have them all. Because the reports are ordered newest first and the economics are frozen at click time, historical pages are stable — a page you fetched yesterday returns the same rows today, which makes incremental syncing straightforward.

The response envelope

Every endpoint answers with the same envelope, which makes error handling uniform across your whole integration. A success carries a success flag set true, a data payload, and — for lists — a metadata block with the paging counts. A failure carries the flag set false and an error object with a stable code and a human-readable message.

Those error codes are strings you can branch on rather than parsing prose. They cover the cases you would expect: an unauthorized key, an expired key, a caller whose IP is not on the key's allowlist, a key lacking the required permission, invalid input, a missing record, a conflict, and an internal error. The HTTP status codes line up with them — 200 and 201 for success, 400 for bad input, 401 for authentication, 403 for permission, 404 for a missing record, 409 for a conflict. Branching on the stable code rather than the message means your integration keeps working even if the wording of a message is ever refined.

Good practices for building on the API

A few habits will save you time:

• Ping first, always. Before debugging anything else, confirm ping returns your account and the expected permissions.
• Watch the request log while you build. Every call and every denial is recorded with its reason, so when a call fails, the log usually tells you exactly why before you have to reach for a debugger.
• Keep the key server-side, and once your caller's address is stable, lock the key to it with the IP allowlist. A key that only works from your server's IP is far less dangerous if it ever leaks.
• Respect rate limits. Requests are rate limited; if you start receiving too-many-requests responses, slow down and retry with a backoff rather than hammering.

If your integration is fundamentally about pulling reporting data, it is worth pairing the API with an understanding of what the numbers mean — the reports guide and the way conversions are reported in the conversion pixels guide together explain the data you will be querying. And if you want a partner to help design the integration, the reporting feature overview shows what the platform exposes — a demo can walk a developer through a live "try it" call on your own account.