Partners REST

Read the authenticated partner's performance summary, check which clients are tagged to them, and track the markup their apps earn. Endpoints marked Beta may change without notice.

Overview

The Partners APIs let an application read how the authenticated partner is performing, confirm who belongs to them, and track what their apps earn. Summarise sign-ups, master-partner earnings, and commission activity for a reporting period via the analytics overview endpoint, confirm which of your client IDs are tagged to the partner via the client-tags check endpoint, and read the markup your registered apps collected via the markup statistics endpoint. All three are standard REST calls and require the application_read OAuth2 scope.

Typical Workflow

1. Authorise your application for the application_read scope, then send the resulting Bearer token with every call.
2. Read the partner's summary cards with GET /partners/analytics/v1/overview. Pass start_date and end_date as YYYY-MM-DD to set the inclusive reporting period, which may span at most 730 days.
3. Confirm which of your clients belong to the partner with POST /partners/client-tags/check. Send up to 100 IDs in client_ids and read is_tagged for each one in the response.
4. Track what the partner's registered apps earned with GET /applications/v1/markup-statistics. Pass date_from and date_to as YYYY-MM-DD in UTC to set the reporting period, which includes both dates.

Available Endpoints

Authentication

All endpoints require an Authorization: Bearer YOUR_OAUTH_TOKEN header carrying the application_read scope; otherwise the API returns 403 Forbidden. When authenticating with a Personal Access Token (PAT), the Deriv-App-ID header is also required (see Authentication).

OAuth2 Scopes

1curl -X GET "https://api.derivws.com/partners/analytics/v1/overview?start_date=2026-07-01&end_date=2026-07-21" \
2  -H "Authorization: Bearer YOUR_OAUTH_TOKEN"
3# Add -H "Deriv-App-ID: YOUR_APP_ID" when authenticating with a Personal Access Token (PAT).

Response Status Codes

The API uses standard HTTP status codes to indicate success or failure:

Error Response Format

All error responses follow a consistent envelope with an errors array. Each entry carries a numeric status, a machine-readable code, and a human-readable message:

1{
2  "errors": [
3    {
4      "status": 422,
5      "code": "ValidationError",
6      "message": "end_date must be on or after start_date"
7    }
8  ]
9}