Referral Agents

What this page solves

As a master partner, create and manage dedicated links for your referral agents.

When to use it

Use this workflow to display links and their current commercial configuration, change an alias, or archive an active link.

Before you start

Use an active signed API key and the access required by the selected operation. See Authentication and Partnership permissions. Creating a link requires alias and the email of an existing registered user. The alias must be unique within the partner’s referral-agent links. These requirements are documented in the request schema. Read the returned ID for detail, alias and archive operations.

Recommended flow

1
Read existing referral-agent links.
2
Create a dedicated link with an alias and email.
3
Read the returned status, reward-share and shared-report configuration.
4
Update only the alias through PATCH.
5
Archive an ACTIVE link when it should no longer be used for new referrals.

Main endpoints

GET /v1/partnership/referral-agent-links — Lists referral-agent links with status, client counts, and current reward share.
POST /v1/partnership/referral-agent-links — Adds a referral agent and creates their dedicated partner link.
GET /v1/partnership/referral-agent-links/{agent_link_id} — Retrieves a referral-agent link, account details, and reward-share configuration.
PATCH /v1/partnership/referral-agent-links/{agent_link_id} — Updates the alias of a referral-agent link.
POST /v1/partnership/referral-agent-links/{agent_link_id}/archive — Archives a referral-agent link to stop new client acquisition.

Example request

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

GET /v1/partnership/referral-agent-links 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>

What to expect in return

HTTP 200 returns data and totals. Agent commission and reward amounts are numbers or null.

API scope

Returned terms and shared_reports are configuration; this API does not change commission terms or retrieve shared-report data.

{
  "data": [
    {
      "id": 1,
      "uid": "00000000-0000-4000-8000-000000000001",
      "alias": "Regional agent",
      "account": "8066808",
      "partner_account": "7055707",
      "link_code": "demo22",
      "status": "ACTIVE",
      "share_perc": 1,
      "clients": 1,
      "shared_reports": [
        "REWARD_HISTORY"
      ],
      "agent_commission_usd": null,
      "reward_usd": null,
      "created": "2026-07-30T10:30:00Z"
    }
  ],
  "totals": {
    "count": 1
  }
}

Common errors

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

HTTP status / code	What It Means	How to Fix It
429 / `Throttled`	A Partnership operation rate limit was exceeded.	Slow down the request rate and honor Retry-After when it is returned.
504 / `ServiceTransportError`	A service required by the Partnership operation could not be reached or timed out.	Retry the request with exponential backoff.
500 / `Error`	A Partnership operation failed because a required service could not complete the request.	Retry the request with backoff.
401 / `AuthenticationFailed`	A 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 / `PermissionDenied`	The authenticated identity cannot perform the operation or access the requested partner data.	Use credentials with the required Partnership permission and resource access.
400 / `ValidationError`	Request validation failed, including bad-request or conflict conditions returned as validation errors.	Do not retry unchanged. Correct the request using details, then sign the corrected request again.
502 / `1` — `SYSTEM_BAD_GATEWAY`	The API could not complete the request to the Partnership service.	Retry the request with backoff.
503 / `2` — `SYSTEM_TEMPORARY_UNAVAILABLE`	A required service is temporarily unavailable or the request deadline was exceeded.	Retry the request with backoff.
500 / `3` — `SYSTEM_INTERNAL_ERROR`	The API encountered an unexpected internal error.	Retry the request with backoff.
401 / `1000` — `AUTH_INVALID_API_KEY`	The 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_SIGNATURE`	The request signature or signed timestamp is invalid.	Rebuild the signature from the exact request and a fresh timestamp.
403 / `1002` — `AUTH_FORBIDDEN`	The API key does not have a required operation scope.	Use an API key with the required Partnership scope.
429 / `1003` — `AUTH_RATE_LIMIT`	The authentication rate limit was exceeded.	Honor Retry-After and reduce request rate.
400 / `3001` — `REQUEST_INVALID_PARAMETERS`	Required 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

After a lost create or update response, read the list or known link ID before repeating the write.

Alias changes allow ACTIVE, ARCHIVED and COMMISSION_RESTRICTED links; archive requires ACTIVE. Treat a validation error according to its returned details. Do not infer additional KYC failure reasons from a link status.

What this page solves​

When to use it​

Before you start​

Recommended flow​

Main endpoints​

Example request​

What to expect in return​

Common errors​

Recovery and reconciliation​

Related pages​