Skip to main content
GET
/
{projectApiKey}
/
customers
Get customers list
curl --request GET \
  --url https://api.qonversion.io/v1/analytics/{projectApiKey}/customers
{
  "data": {
    "total_count": 1542,
    "items": [
      {
        "client_id": 12345,
        "client_uid": "QON_abc123def456",
        "external_identity": "user_42",
        "custom_uid": "user_42",
        "since": 1699000000,
        "last_payment_at": 1701000000,
        "first_transaction_purchase_at": 1700000000,
        "payments_count": 3,
        "purchase_currency": "USD",
        "purchase_product_id": "premium_monthly",
        "net_payments_usd": 49.99,
        "status": 2,
        "trial_status": 2,
        "client_country": "US",
        "device_model": "iPhone15,2",
        "device_id": "ABCDEF12-3456",
        "target_platform": "iOS",
        "device_os_version": "17.4"
      }
    ],
    "page": 1
  }
}

Documentation Index

Fetch the complete documentation index at: https://documentation.qonversion.io/llms.txt

Use this file to discover all available pages before exploring further.

Path Parameters

​
projectApiKey
string
required

Project API Key for authentication and project identification. A 32-character alphanumeric string copied from Project Settings -> Project Keys -> API Key in https://dash.qonversion.io/. The key has no fixed prefix.

Minimum string length: 1
Example:

"JFPATc4VaaWYsfurml3qZ4zsmNw0VfWH"

Query Parameters

​
page
integer
default:1

Page number (1-based). Page 1 is the first page.

Required range: x >= 1
​
limit
integer
default:20

Items per page. Capped at 100.

Required range: 1 <= x <= 100
​
sort_by
enum<string>
default:since

Field to sort by. Allowed values are tied to the underlying customer index.

Available options:
since,
status,
last_payment_at,
purchase_currency,
payments_count,
net_payments_usd,
purchase_product_id
​
sort_order
enum<string>
default:desc

Sort direction.

Available options:
asc,
desc
​
environment
enum<integer>
default:1

Environment type (0=Sandbox, 1=Production). Sandbox keys are not supported by this API; production keys returning environment=0 will yield no data.

Available options:
0,
1
​
search
string

Universal search across email, transaction id, firebase id, custom user id, device id, and Qonversion user id. Forwarded to the backend as search_all.

Maximum string length: 255
​
search_key
enum<string>

Targeted search field. Use together with search_value. Forwarded as advanced_key.

Available options:
email,
firebaseID,
transactionID,
customerUserID,
deviceID
​
search_value
string

Value to match for the targeted search_key. Forwarded as advanced_value.

​
filter[since][]
integer<int64>[]

Date-range filter on customer first-seen time. Pass exactly two values: filter[since][]=<from_unix_ts>&filter[since][]=<to_unix_ts>. If omitted, both bounds default to the current time and the result will be empty.

Required array length: 2 elements
​
filter[status][]
enum<string>[]

Filter by customer status. Numeric codes:

  • 1 = Trial / Intro
  • 2 = Active
  • 3 = Canceled
  • 4 = Billing Retry
Available options:
1,
2,
3,
4
​
filter[target_platform][]
enum<string>[]

Filter by platforms.

Available options:
iOS,
Android,
Stripe
​
filter[country][]
string[]

Filter by countries (ISO 3166-1 alpha-2).

Pattern: ^[A-Z]{2}$
​
filter[product_id][]
string[]

Filter by product IDs.

​
filter[purchase_currency][]
string[]

Filter by purchase currencies (ISO 4217).

Pattern: ^[A-Z]{3}$
​
filter[locale][]
string[]

Filter by locales.

​
filter[model][]
string[]

Filter by device models.

​
filter[os_version][]
string[]

Filter by OS versions.

​
filter[app_version][]
string[]

Filter by app versions.

​
filter[sdk_version][]
string[]

Filter by SDK versions.

​
filter[media_source_name][]
string[]

Filter by media source names.

​
filter[campaign_name][]
string[]

Filter by campaign names.

​
filter[ad_set_name][]
string[]

Filter by ad set names.

​
filter[ad_name][]
string[]

Filter by ad names.

​
filter[experiment_uid][]
string[]

Filter by experiment UIDs.

​
filter[experiment_group_uid][]
string[]

Filter by experiment group UIDs.

Response

Successful response with paginated customer list

Top-level envelope for /customers. Pagination is reported inside data as total_count and the echoed page; clients compute total_pages from ceil(total_count / limit).

​
data
object
required