Skip to main content
GET
/
{projectApiKey}
/
customers
Get customers list
curl --request GET \
  --url https://api.qonversion.io/v1/analytics/{projectApiKey}/customers
import requests

url = "https://api.qonversion.io/v1/analytics/{projectApiKey}/customers"

response = requests.get(url)

print(response.text)
const options = {method: 'GET'};

fetch('https://api.qonversion.io/v1/analytics/{projectApiKey}/customers', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
CURLOPT_URL => "https://api.qonversion.io/v1/analytics/{projectApiKey}/customers",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
require 'uri'
require 'net/http'

url = URI("https://api.qonversion.io/v1/analytics/{projectApiKey}/customers")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
package main

import (
"fmt"
"net/http"
"io"
)

func main() {

url := "https://api.qonversion.io/v1/analytics/{projectApiKey}/customers"

req, _ := http.NewRequest("GET", url, nil)

res, _ := http.DefaultClient.Do(req)

defer res.Body.Close()
body, _ := io.ReadAll(res.Body)

fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.get("https://api.qonversion.io/v1/analytics/{projectApiKey}/customers")
.asString();
{
  "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
  }
}
{
"error": {
"code": "validation_error",
"message": "Unprocessable request params",
"type": "request"
},
"meta": {
"reference": "https://documentation.qonversion.io/reference/handling-api-errors"
}
}
{
"error": {
"code": "validation_error",
"message": "Unprocessable request params",
"type": "request"
},
"meta": {
"reference": "https://documentation.qonversion.io/reference/handling-api-errors"
}
}
{
"error": {
"code": "validation_error",
"message": "Unprocessable request params",
"type": "request"
},
"meta": {
"reference": "https://documentation.qonversion.io/reference/handling-api-errors"
}
}
{
"error": {
"code": "validation_error",
"message": "Unprocessable request params",
"type": "request"
},
"meta": {
"reference": "https://documentation.qonversion.io/reference/handling-api-errors"
}
}

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

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