Retrieve the person

Reads the person x-distinct-id names, with the perks they can use and their subscriptions and purchases.

Fails with Api/SdkPersonNotFoundError when no person has the distinct id. The SDKs call the client API for you; prefer them.

Guide: Install an SDK

Errors

This operation adds no error codes of its own. It can fail with the errors every operation shares, such as unauthenticated; see Errors.

More in SDK

Something wrong or missing on this page? Tell us by email or on Discord.

Header parameters

x-distinct-id*string

The distinct id of the end user the request acts for: the anonymous vh_anon_… id the SDK generated, or the id the app identified them with. At most 255 characters.

x-distinct-id-encoding?"percent"

percent when x-distinct-id holds the RFC 3986 percent-encoded UTF-8 form of an id that is not printable ASCII; leave it out when the header holds the id as is.

Value in

"percent"

x-publishable-key*string

The project's publishable key, vh_pk_…. A test key, vh_pk_test_…, works with store sandbox and test purchases.

x-client-bundle-id*string

The app's bundle id on iOS or package name on Android, which picks the project's store configuration for purchases and promotional offers.

x-client-locale?string

The end user's most preferred locale, such as en-US.

x-client-version?string

The app's version, such as 2.4.1.

x-is-backgrounded*string

true when the app sent the request from the background, otherwise false.

Value in

"true"
"false"

x-is-debug-build*string

true when the app is a debug build, otherwise false. Only debug builds can make simulated development purchases.

Value in

"true"
"false"

x-nonce?string

A random id, new for every request, such as a lowercase UUID.

x-observer-mode*string

true when the SDK runs in observer mode: another billing integration owns purchases and the SDK only reports them. Otherwise false.

Value in

"true"
"false"

x-platform*string

The platform the app runs on, such as ios, android or web. Records where a new person signed up.

x-platform-brand?string

The device's manufacturer, such as Apple or Google.

x-platform-device?string

The device's model, such as iPhone15,2; in a browser, its navigator.platform.

x-platform-flavor*string

native in an app, browser in a web page.

Value in

"native"
"browser"

x-platform-flavor-version?string

The version of the app hosting the SDK; native SDKs send the app's version, the web SDK leaves it out.

x-platform-version?string

The operating system's version, such as 17.4; in a browser, its user agent.

x-preferred-locales?string

The end user's preferred locales, most preferred first, separated by commas, such as en-US,de-DE.

x-sdk*string

The SDK making the request: ios, android, react-native or web. A native SDK driven by another reports the outer one, such as react-native.

Value in

"react-native"
"web"
"ios"
"android"

x-sdk-version*string

The version of the SDK making the request, such as 1.4.0.

x-storefront?string

The app store storefront (country) the end user buys from, when the SDK knows it.

Examples

curl -X GET "https://api.voidhash.com/api/v1/sdk/person" \  -H "x-distinct-id: user_8231" \  -H "x-publishable-key: vh_pk_..." \  -H "x-client-bundle-id: com.example.app" \  -H "x-is-backgrounded: true" \  -H "x-is-debug-build: true" \  -H "x-observer-mode: true" \  -H "x-platform: ios" \  -H "x-platform-flavor: native" \  -H "x-sdk: react-native" \  -H "x-sdk-version: 0.0.1-alpha.1"

{  "personId": "person_h7d2k9m4x1c6v8b3n5q0w2e7",  "distinctId": "user_8231",  "email": "ada@example.com",  "name": "Ada Lovelace",  "entitlements": {    "grants": [      {        "perkId": "perk_c4v7b1n9m2x5z8q3w6e0r4t7",        "perkSlug": "premium",        "source": "subscription",        "sourceId": "sub_p9o3i7u1y5t8r2e6w0q4a8s2",        "sourcePersonId": "person_h7d2k9m4x1c6v8b3n5q0w2e7",        "expiresAt": "2026-04-14T09:26:53.000Z",        "status": "active"      }    ]  },  "subscriptions": {    "all": [      {        "subscriptionId": "sub_p9o3i7u1y5t8r2e6w0q4a8s2",        "productId": "prod_x8k2m5q9v3n7c1z4w6e0r2t5",        "productSlug": "pro_monthly",        "store": "app_store",        "environment": "production",        "status": "active",        "periodType": "regular",        "startsAt": "2026-03-14T09:26:53.000Z",        "expiresAt": "2026-04-14T09:26:53.000Z",        "willRenew": true,        "canceledAt": null,        "renewsToProductSlug": null,        "gracePeriodExpiresAt": null,        "billingIssueDetectedAt": null,        "resumesAt": null,        "pendingPrice": {          "amountMicros": 12990000,          "currency": "USD",          "effectiveAt": "2026-04-14T09:26:53.000Z",          "consent": "accepted"        },        "offerId": null,        "isFamilyShared": false,        "refundedAt": null,        "revokedAt": null      }    ],    "current": {      "subscriptionId": "sub_p9o3i7u1y5t8r2e6w0q4a8s2",      "productId": "prod_x8k2m5q9v3n7c1z4w6e0r2t5",      "productSlug": "pro_monthly",      "store": "app_store",      "environment": "production",      "status": "active",      "periodType": "regular",      "startsAt": "2026-03-14T09:26:53.000Z",      "expiresAt": "2026-04-14T09:26:53.000Z",      "willRenew": true,      "canceledAt": null,      "renewsToProductSlug": null,      "gracePeriodExpiresAt": null,      "billingIssueDetectedAt": null,      "resumesAt": null,      "pendingPrice": {        "amountMicros": 12990000,        "currency": "USD",        "effectiveAt": "2026-04-14T09:26:53.000Z",        "consent": "accepted"      },      "offerId": null,      "isFamilyShared": false,      "refundedAt": null,      "revokedAt": null    },    "history": [      {        "subscriptionId": "sub_p9o3i7u1y5t8r2e6w0q4a8s2",        "productId": "prod_x8k2m5q9v3n7c1z4w6e0r2t5",        "productSlug": "pro_monthly",        "store": "app_store",        "sourcePersonId": "person_h7d2k9m4x1c6v8b3n5q0w2e7",        "status": "active",        "isTrial": false,        "startsAt": "2026-03-14T09:26:53.000Z",        "expiresAt": "2026-04-14T09:26:53.000Z",        "canceledAt": null,        "refundedAt": null      }    ]  },  "purchases": {    "history": [      {        "purchaseId": "pur_a3s7d1f5g9h2j6k0l4z8x2c6",        "productId": "prod_x8k2m5q9v3n7c1z4w6e0r2t5",        "productSlug": "pro_monthly",        "providerKey": "2000000123456789",        "sourcePersonId": "person_h7d2k9m4x1c6v8b3n5q0w2e7",        "type": "subscription",        "createdAt": "2026-03-14T09:26:53.000Z",        "refundedAt": null,        "revokedAt": null      }    ]  },  "snapshotContext": {    "includedPersonIds": [      "person_h7d2k9m4x1c6v8b3n5q0w2e7"    ],    "migrationJobId": null,    "mode": "persisted"  }}

{  "_tag": "Api/SdkValidationError",  "message": "string"}

{  "_tag": "Api/AuthenticationError",  "cause": "string",  "message": "string"}

{  "_tag": "Api/SdkPersonNotFoundError",  "message": "string"}

{  "_tag": "Api/SdkServiceError",  "cause": "string"}

Retrieve the person

Errors

More in SDK

Retrieve the person

Errors

More in SDK

Authorization

Header parameters

Examples

Response body

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

Retrieve the person

Retrieve the person

200application/json

400application/json

401application/json

404application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`