API Reference: overview and base URL

Overview of the MeerPartners REST API: base URL and the /api/v1 version, response and error format, authentication, pagination, Swagger and endpoint groups.

This reference describes the REST API of the MeerPartners platform — for business integration (postback, keys, deposits) and for the influencer embed-SDK. This is a technical section: the examples are exact, and the endpoints and fields are taken from production code. If you are just getting started, first read Authentication and Postback.

Base URL and version

All versioned methods live under the /api/v1 prefix:

https://api.meerpartners.com/api/v1

The address depends on the operator

https://api.meerpartners.com is an example. The base domain is set by the platform operator (on a self-hosted installation it will be your own). Get the exact address for your integration from the business cabinet on the Integration page or from your manager. Further in this reference we show only the path (/api/v1/...).

Only the tracking edge endpoints work outside the version — they have short paths for speed and compatibility with advertising systems:

Path	Purpose
`GET /r/{code}`	Redirect via a tracking link (302).
`GET /p/{code}.gif`	Pixel fallback (1×1 GIF) for attribution without a redirect.

Details are on the Tracking and postback page.

Response format

Request and response bodies are JSON (Content-Type: application/json), UTF-8 encoded.
Monetary amounts and rates are passed as strings (NUMERIC), not floating-point numbers — so as not to lose cents. For example "amount": "1500.00".
Currencies are a three-letter ISO code in uppercase: RUB, USD, EUR.
Dates and times are ISO 8601 in UTC (for example 2026-06-14T12:30:00Z).

Error format

Any error is returned in a single envelope. Every error has a stable machine-readable code — tie your logic to it, not to the message text (the text may change and is localized).

Error example

{
  "error": {
    "code": "POSTBACK_BAD_SIGNATURE",
    "message": "Invalid signature",
    "details": {}
  }
}

error.codestringrequired

Stable error code (for example KYC_REQUIRED, INSUFFICIENT_BALANCE). Does not change between releases.

error.messagestringrequired

Human-readable description. May change and be localized — do not parse it.

error.detailsobjectoptional

Additional error context. Not always present (for example on 429 — { "limit": ..., "window_seconds": ... }). If there is no context, the field may be absent.

Request-body validation errors are returned with HTTP 422 and the code VALIDATION_ERROR; details contains the list of problematic fields.

Common HTTP status codes

Code	When
`200` / `201` / `202` / `204`	Success (created / accepted for processing / no body).
`400`	Bad request (for example a stale `X-Timestamp`).
`401`	Missing/invalid authentication (token, signature).
`403`	No permission (another tenant, insufficient role, embed scope).
`404`	Resource not found.
`409`	Conflict (duplicate, taken slug, repeated signature).
`422`	Request-body validation error.
`429`	Rate limit exceeded (see Rate limits).
`5xx`	Platform-side error or temporary unavailability of a dependency.

Authentication

The API uses three mechanisms — the choice depends on who is calling and why:

Mechanism	Who uses it	How it is passed
MeerID OIDC → JWT	People signing in to the cabinets	Exchanged for a JWT via `POST /api/v1/auth/meerid/exchange`
JWT Bearer	Cabinets and embed-SDK	`Authorization: Bearer <access_token>`
tenant_api_key (HMAC)	S2S: postback, token-exchange	Headers `X-Api-Key-Id`, `X-Timestamp`, `X-Signature` (+ `X-Tenant-Id`)

The access token lives for 15 minutes, the refresh token for 30 days; rotation is via POST /api/v1/auth/refresh. A full description of the schemes, the HMAC signature and examples are on the Authentication page and in the Auth section.

Pagination

List endpoints use offset pagination via query parameters:

skipintegeroptional

How many records to skip from the beginning. Defaults to 0, minimum 0.

limitintegeroptional

Page size. Defaults to 50 (for some lists — 100), the maximum depends on the endpoint (usually 200, for links — 500).

In the response of list methods, alongside the data array, total is returned — the total number of records matching the filter (for computing the number of pages).

Shape of a list response

{
  "items": [ /* ... */ ],
  "total": 137
}

items or data

The array name depends on the group: influencer endpoints return items, business endpoints more often return data. The total field is present in both cases. The exact shape is specified on each group's page.

Interactive documentation (Swagger)

When the platform is running in debug mode (DEBUG), an interactive Swagger UI and the OpenAPI schema are available:

Path	What it is
`GET /api/docs`	Swagger UI (Try it out).
`GET /api/openapi.json`	Machine-readable OpenAPI schema.

Swagger is disabled in production

In the production environment DEBUG is turned off, so /api/docs is unavailable (404) — this is intentional, to avoid exposing the schema publicly. Rely on this reference.

Endpoint groups

🔑Auth

Открыть

📣Affiliate (self-service)

Influencer profile and KYC, offer catalog, tracking links, balance, statistics, payout methods.

Открыть

🏢Merchant (self-service)

Offers, escrow balance and deposit, integration keys, analytics, publishers and grants, profile.

Открыть

🎯Tracking and postback

Redirect /r/{code}, pixel /p/{code}.gif, conversion intake POST /api/v1/postback.

Открыть

💸Payouts

Withdrawal request and influencer payout history, statuses and error codes.

Открыть

⏱️Rate limits and idempotency

Rate limiting, the Retry-After header, Idempotency-Key, postback deduplication.

Открыть

What's next

🔐Authentication

Step by step: obtaining a JWT, the HMAC signature, S2S headers.

Открыть

🔁Postback setup

How to send conversions S2S and not lose accruals.

Открыть

PreviousExamples: cURL, Node, Python NextAuth