Evaluate flags for an end user
Evaluates the project's flags in use for one end user, as their app would in an environment, and says why each came out as it did.
Name the end user by any of personId, distinctId, email or externalIds. Safe to repeat. It changes no flag; as an app's read does, it places the end user in an arm of a running experiment that sets one of the flags, when they are named by personId or distinctId and are in none yet. Send isPreview: true to look at an end user without placing them.
Guide: Feature flags and A/B tests
A project secret key: vh_sk_... for production, vh_sk_test_... for test. Keep it on your servers.
In: header
Path parameters
The project's id, proj_.... A secret key works only in the project it belongs to.
Request body
application/json
TypeScript definitions
Use the request body type in TypeScript.
The end user's person id, person_....
A distinct id your app knows the end user by; when it belongs to a person, their other identities match too.
The end user's email address, for overrides and rules that name it.
The end user's external ids, for overrides and rules that name them.
The environment to evaluate in. Omitted, a project key evaluates in its own environment, and a person's token in production.
The keys of the flags to evaluate; omitted, every flag in use is.
What your server knows of the end user's app, for rules with conditions on it. An SDK reports these itself; here, a field left out counts as not set, so a condition that needs it does not hold. Conditions on traits read the person's stored traits and need nothing here.
Whether to only look: true says what the end user would get without placing them in an arm of a running experiment that sets one of the flags. Omitted or false, the evaluation counts as the end user's own, as your server's does when it decides what to serve them.
Examples
curl -X POST "https://api.voidhash.com/api/v1/projects/proj_tz4a98xxat96iws9zmbrgj3a/feature-flags/evaluate" \ -H "Authorization: Bearer vh_sk_..." \ -H "Content-Type: application/json" \ -d '{ "distinctId": "user_8231", "keys": [ "new-checkout" ], "context": { "platform": "ios", "appVersion": "2.4.1", "country": "DE" } }'{ "flags": [ { "featureFlagId": "ff_v8b3n5q0w2e7h7d2k9m4x1c6", "key": "new-checkout", "isEnabled": true, "variantKey": null, "value": null, "reason": "default", "ruleId": null } ]}{ "error": { "type": "invalid_request", "code": "identity_required", "message": "Name the end user by personId, distinctId, email or externalIds." }}{ "error": { "type": "unauthenticated", "code": "invalid_api_key", "message": "This secret key is not valid." }}{ "error": { "type": "permission_denied", "code": "permission_denied", "message": "Insufficient permissions." }}{ "error": { "type": "not_found", "code": "project_not_found", "message": "There is no project proj_tz4a98xxat96iws9zmbrgj3a, or this credential cannot use it.", "param": "projectId" }}{ "error": { "type": "internal", "code": "internal_error", "message": "Something went wrong on our side. Try again, and contact support with the Request-Id header if it keeps failing." }}Response body
application/json
application/json
application/json
application/json
application/json
application/json
Errors
| Status | type | code | When |
|---|---|---|---|
| 400 | invalid_request | identity_required | Without one. |
It can also fail with the errors every operation shares, such as unauthenticated; see Errors.
More in Feature flags
- List feature flags
GET - Create a feature flag
POST - Retrieve a feature flag
GET - Update a feature flag
PATCH - Archive a feature flag
POST - Unarchive a feature flag
POST - List a flag's variants
GET - Replace a flag's variants
PUT - Set who gets a flag in an environment
PUT - Make test follow production
DELETE - List a flag's overrides
GET - Set an override
PUT - Remove an override
DELETE - List an end user's overrides
GET
Something wrong or missing on this page? Tell us by email or on Discord.