GET Referred Customers

Endpoint

GET /api/affiliate/v1/customers

Requires an affiliate API token with customers:read.

GET /api/affiliate/v1/customers?limit=100&offset=0&from_time=1789344000&to_time=1791936000
Authorization: {JWT_TOKEN}

A customer is returned only when its brand matches the token brand and its affiliate attribution matches the authenticated affiliate code. The response includes the customer display name and masked email and phone values. Full contact values, addresses, identity documents, and other sensitive customer data are not returned.

Query parameters

Name	Type	Required	Description
limit	int	Yes	Page size from 1 to 500
offset	int	Yes	Number of matching records to skip; minimum 0
from_time	int64	No	Minimum created_time, inclusive. 0 or omitted means no lower bound
to_time	int64	No	Maximum created_time, inclusive. 0 or omitted means no upper bound

from_time and to_time filter on the created_time field returned in every row, and count reflects the filtered set. An invalid bound is refused with 400; see Time filtering.

Response

{
  "rows": [
    {
      "customer_id": 12041,
      "name": "Jane Doe",
      "email": "j***@example.com",
      "phone": "+357******44",
      "status": 0,
      "status_text": "Active",
      "sale_status": 17,
      "sale_status_text": "Qualified",
      "lifecycle_flags": 6,
      "lifecycle_flags_text": "KYC pending, KYC approved",
      "customer_kind": 1,
      "kyc_status": 2,
      "kyc_status_text": "Pending",
      "country": "CY",
      "campaign": "summer-2026",
      "utm_source": "partner-site",
      "utm_campaign": "summer-2026",
      "created_time": 1789344000
    }
  ],
  "count": 247
}

Customer fields

Field	Type	Description
customer_id	int	Customer identifier
name	string	Customer display name
email	string	Masked email address
phone	string	Masked phone number
status	int	Numeric customer account status
status_text	string	Human-readable value of status
sale_status	int	Brand sales-status dictionary identifier; 0 means not assigned
sale_status_text	string	Brand-configured sales-status name, Not set, or Unknown when the referenced entry is unavailable or invalid
lifecycle_flags	int64	Milestone bit mask
lifecycle_flags_text	string	The raised flags as labels separated by commas, in a fixed order. Empty when the mask is 0
customer_kind	int	0 lead, 1 client
kyc_status	int	Numeric KYC profile status
kyc_status_text	string	Human-readable value of kyc_status
country	string	Customer country of residence
campaign	string	Attribution campaign
utm_source	string	UTM source captured during attribution
utm_campaign	string	UTM campaign captured during attribution
created_time	int64	Customer creation time as Unix timestamp in seconds

Status values

status values:

Value	status_text
0	Active
1	Blocked
2	Archived

lifecycle_flags bits:

Bit	Value	Label
1 << 0	1	Registered
1 << 1	2	KYC pending
1 << 2	4	KYC approved
1 << 3	8	First deposit
1 << 4	16	Active trader
1 << 5	32	Dormant

The flags are independent, so any combination is valid, and the maximum mask for the six defined flags is 63. lifecycle_flags_text lists the raised ones in the order above.

This is the only place where the server returns the mask as ready text; the CRM commands return the number alone.

customer_kind values:

Value	Meaning
0	Lead
1	Client

kyc_status values:

Value	kyc_status_text
0	None
1	Draft
2	Pending
3	Approved
4	Rejected
5	Expired
6	Review required

sale_status_text is not a fixed enum. It is resolved from the sales-status dictionary configured for the customer's brand.

Errors

HTTP	Error	Description
401	INCORRECT_TOKEN	JWT signature or format is invalid
401	INVALID_AFFILIATE_API_TOKEN	Token record, owner, brand, scope, expiration, or active access check failed
403	INVALID_AFFILIATE_API_HOST	Request host is neither the configured affiliate host nor terminal host for the token brand
400	INVALID_DATA	limit or offset is missing or invalid, or from_time / to_time is not a non-negative integer or forms an inverted range