Skip to main content

Campaigns

What this page solves​

Create a campaign with its initial link, add tracking links and read the campaign configuration.

When to use it​

Use campaigns to organize acquisition sources and compare report metrics where campaign filters are available.

Before you start​

Use an active signed API key and the access required by the selected operation. See Authentication and Partnership permissions. Use write access for campaign changes. Obtain campaign_code from the campaign list or a create response. Creating a campaign requires title.

  1. 1
    Read existing campaigns.
  2. 2
    Create a campaign with its title and, when needed, reward model.
  3. 3
    Save the returned campaign_code and link identifiers.
  4. 4
    Add links using that campaign code and a required domain.
  5. 5
    Read the campaign and use supported Performance statistics API variants.
  6. 6
    Update title, description or archive state through the campaign PATCH operation.

Main endpoints​

Example request​

Request-shape example; replace the authentication placeholders with a fresh signature.

POST /v1/partnership/campaigns HTTP/1.1
Host: <your-api-host>
EXN-API-KEY: <your-api-key>
EXN-TIMESTAMP: <fresh-unix-milliseconds>
EXN-SIGN-VERSION: 1
EXN-DATA: <base64url-signed-data>
EXN-SIGN: <base64url-signature>
Content-Type: application/json

{
  "title": "Summer campaign",
  "reward_schema": "revenue_share"
}

What to expect in return​

HTTP 200 returns a campaign with its required link fields. This create response does not define a top-level is_blocked; individual links carry that field. reward_schema accepts revenue_share or cpa and defaults to revenue_share when omitted.

{
  "campaign_code": "campaign22",
  "title": "Summer campaign",
  "link_count": 1,
  "archived": false,
  "base_link": "https://www.exness.com/a/demo22",
  "link_code": "demo22",
  "created": "2026-07-30T10:30:00Z",
  "links": [
    {
      "link": "https://www.exness.com/a/demo22",
      "platform": "mobile",
      "os": "ios",
      "tags": [
        "summer"
      ],
      "link_code": "demo22",
      "is_blocked": false,
      "is_custom": false
    }
  ],
  "reward_schema": "revenue_share"
}

Common errors​

The following errors apply to the example operation. Other operations can declare a different subset; follow their API Reference links.

HTTP status / codeWhat It MeansHow to Fix It
429 / ThrottledA Partnership operation rate limit was exceeded.Slow down the request rate and honor Retry-After when it is returned.
504 / ServiceTransportErrorA service required by the Partnership operation could not be reached or timed out.For an uncertain write, read the affected resource before deciding whether to send another write.
500 / ErrorA Partnership operation failed because a required service could not complete the request.For an uncertain write, read current state before deciding whether to send another write.
401 / AuthenticationFailedA Partnership service rejected the authenticated request after request authentication. API-key and request-signature failures use the numeric authentication errors.Check the request authorization context. When the response uses the numeric envelope, follow the action for its error_message.
403 / PermissionDeniedThe authenticated identity cannot perform the operation or access the requested partner data.Use credentials with the required Partnership permission and resource access.
400 / ValidationErrorRequest validation failed, including bad-request or conflict conditions returned as validation errors.Correct the request using the schema and safe validation details; read current state first when a write outcome is uncertain.
404 / NotFoundThe resource does not exist or is not available to the partner.Verify the identifier and current resource list.
400 / NotUniqueA campaign or campaign-link value conflicts with an existing value.Choose a different unique value or read the existing campaign or link.
400 / ManyItemsA campaign or campaign-link limit was reached.Review the existing campaigns or links and reuse an existing resource where possible. Do not retry the same create request until the limit has been resolved.
502 / 1 — SYSTEM_BAD_GATEWAYThe API could not complete the request to the Partnership service.For an uncertain write, read current state before deciding whether to send another write.
503 / 2 — SYSTEM_TEMPORARY_UNAVAILABLEA required service is temporarily unavailable or the request deadline was exceeded.For an uncertain write, read current state before deciding whether to send another write.
500 / 3 — SYSTEM_INTERNAL_ERRORThe API encountered an unexpected internal error.For an uncertain write, read current state before deciding whether to send another write.
401 / 1000 — AUTH_INVALID_API_KEYThe API key is invalid, expired, revoked, or not allowed for the request source.Check the API key, its state, and its allowed source IP.
401 / 1001 — AUTH_INVALID_SIGNATUREThe request signature or signed timestamp is invalid.Rebuild the signature from the exact request and a fresh timestamp.
403 / 1002 — AUTH_FORBIDDENThe API key does not have a required operation scope.Use an API key with the required Partnership scope.
429 / 1003 — AUTH_RATE_LIMITThe authentication rate limit was exceeded.Honor Retry-After and reduce request rate.
400 / 3001 — REQUEST_INVALID_PARAMETERSRequired headers or signed request data are malformed or inconsistent.Correct the headers or signed values named by description, then sign the exact request again.

Recovery and reconciliation​

Write recovery

Campaign writes have no idempotent replay guarantee. If a response is lost, list or read campaigns and compare the fields available in that response before deciding whether to resubmit. Campaign reads do not expose description, so they cannot confirm whether a description update took effect.

NotUnique and ManyItems are HTTP 400 operation errors; correct the request or inspect existing resources. Report data can appear later than a campaign change.