Skip to main content

Reports

What this page solves​

Choose the report that matches the entity, payout cycle and level of detail you need.

When to use it​

Use Clients, Client accounts, Reward history, Client transactions, Transactions pending payment and Performance statistics, plus additional reports for registrations, subpartners and progress rewards.

Before you start​

Use an active signed API key and the access required by the selected operation. See Authentication and Partnership permissions. Read reports with read access. The separate client-comment POST operation requires write access. For Reward history, supply the required aggregate_by; for Client transactions, supply date_from and date_to. Use the precise parameters listed below.

  1. 1
    Choose a report using the selection matrix.
  2. 2
    Set the required filters and grouping for that report.
  3. 3
    Keep filters and ordering unchanged while advancing limit and offset where supported.
  4. 4
    Use the totals returned by the selected report endpoint for the same filters, where available.
  5. 5
    Reconcile recent data through repeated reads; do not assume pages or report families share one snapshot.

Report selection​

ReportUse it whenWhat it returns / API Reference
ClientsUnderstand who your referred clients are.Client-level registration, activity, reward, KYC and available contact-sharing information; not a list of trading accounts. GET /reports/clients
Client accountsInspect the trading accounts associated with referred clients.Account-level activity and reward figures. Choose the second-level endpoint for the corresponding master-partner reporting level. GET /reports/clients/accounts; GET /reports/clients/accounts/second-level
Reward historyReview partner rewards at the requested aggregation level.Aggregated reward and trading-volume figures. Choose the first- or second-level endpoint; supply its required aggregate_by. GET /reports/rewards; GET /reports/rewards/secondlevel
Client transactionsInvestigate the closed orders behind partner rewards.Order-level trading and reward details for the requested date range. GET /reports/orders
Transactions pending paymentCheck activity whose partner reward has not yet been credited.Pending figures aggregated by account; not an individual-order list or a rebate-payment report. GET /reports/orders/pending
Performance statisticsCompare acquisition and conversion performance.Use the IB performance endpoint for Performance statistics. The conversion and campaign-specific conversion reports provide related metrics with their own filters and grouping options. GET /reports/ib/performance; GET /reports/conversion; GET /reports/conversion/campaign/{campaign_code}
Progress rewardsInspect progress-reward compensation and its supporting detail.Compensation records and a detail report selected by compensation_id; payment_date alone does not prove payment success. GET /reports/progress-reward; GET /reports/progress-reward/{compensation_id}/detailed
Daily registrationsTrack how client registrations vary by day.Registration counts grouped by registration date. GET /reports/clients/registrations/byday
SubpartnersInspect reporting for your subpartners.Subpartner-level client activity and reward figures, with returned subpartner identifiers. GET /reports/clients/subpartners

Some report names cover multiple API endpoints with different filters and grouping options. Follow each endpoint link for the complete filters, grouping values, identifiers and totals. Choose Clients for the person, Client accounts for the account, and Client transactions for individual orders. For rebate payout status, use the Rebates guide. limit, offset and ordering are available only where declared. Check API Configuration and Limits for page-size and date-range settings before starting an export.

Grouping and interpretation​

Use the IB performance endpoint for Performance statistics. It requires one or two group_by dimensions and returns group_fields as objects, for example [{"day":"2026-07-30"},{"country":"CY"}]. Conversion uses its own grouping choices. Use the encoding declared for each query parameter. Most array filters use a comma-separated list. For conversion tags, repeat the key, for example tags=spring&tags=email. Sign the query exactly as transmitted.

Reward history reports require aggregate_by. The same order or account can contribute to different aggregations; a display row is not necessarily a distinct payment. Client transactions does not accept campaign or link filters. Progress-reward payment_date does not prove successful payment.

Some account-level report fields can be null: partner_code and client_account_type in the first-level Client accounts report, client_account and client_account_type in both Reward history variants, and client_account in the second-level Client accounts report. Use populated identifiers when joining rows.

Conversion tags example​

Repeat tags for multiple values. This request groups and sorts results by country for the specified dates. Generate fresh authentication headers and sign the complete request path, including the query string shown here.

GET /v1/partnership/reports/conversion?group_by=country&ordering=country&date_from=2026-07-01&date_to=2026-07-30&tags=spring&tags=email 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>

Main endpoints​

Example request​

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

GET /v1/partnership/reports/clients?limit=100&offset=0 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 client rows and totals. The illustrative empty result is valid; real rows can include nullable and optional fields as defined in API Reference. In the Clients report, reward_usd is returned as a decimal string; volume_lots and volume_mln_usd are numbers. reg_date is a calendar date; trade_fn is a calendar date or null.

{
  "data": [],
  "totals": {
    "count": 0,
    "volume_lots": 0,
    "volume_mln_usd": 0,
    "reward_usd": "0.00",
    "server_dt": "2026-07-30T10:30:00Z",
    "available_for_request": 0
  }
}

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.Retry the request with exponential backoff.
500 / ErrorA Partnership operation failed because a required service could not complete the request.Retry the request with backoff.
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.Do not retry unchanged. Correct the request using details, then sign the corrected request again.
502 / 1 — SYSTEM_BAD_GATEWAYThe API could not complete the request to the Partnership service.Retry the request with backoff.
503 / 2 — SYSTEM_TEMPORARY_UNAVAILABLEA required service is temporarily unavailable or the request deadline was exceeded.Retry the request with backoff.
500 / 3 — SYSTEM_INTERNAL_ERRORThe API encountered an unexpected internal error.Retry the request with backoff.
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​

Reconciliation

A report can lag behind a write or payment. Match the returned identifiers to their documented entities; the contract does not define a universal stable row key or a deduplication algorithm. Do not deduplicate by display fields. Keep client-level attribution separate from trading-account attribution.

The API returns only resources available to the partner associated with the key. Do not interpret KYC, contact-sharing, deposit or balance classifications as permission to contact a client or share an export. This guide does not infer internal classification rules.

Export handling (not API permission rules)

Restrict exports to the people who need them, avoid copying contact and financial data into general application logs, and use your organization’s approved storage and retention policy. The API contract does not define a retention period or authorize onward sharing.