Quick start - VerifyYou

Before you start

You have a service account.
You have an API key for that service account.
Set your base URL:

export VERIFYYOU_API_BASE=https://api.connect.verifyyou.com

Step 1: Register a user and request a humanness check

curl -X POST "$VERIFYYOU_API_BASE/v1/business_connect_user/register" \
  -H "Content-Type: application/json" \
  -H "API-KEY: $VERIFYYOU_API_KEY" \
  -d '{
    "reference_user_id": "user_123",
    "redirect_url": "https://yourapp.com/verify/return",
    "data_request": [
      {
        "type": "GET_HUMANNESS_SCORE_AND_UNIQUE_HUMAN_ID"
      }
    ]
  }'

Success response:

{
  "status": "success",
  "invite_url": "https://verifyyou.com/invite/...",
  "user_id": "bcu_123",
  "connection_verified": false
}

Failure response:

{
  "status": "failure",
  "failure_code": "INVALID_REQUEST",
  "failure_reason": "Missing required field: reference_user_id"
}

Present the invite_url to the user. On desktop, it will be faster to render as a QR code, but otherwise it will open a tab to show the QR code. On mobile, link to it directly.

Step 2: Wait for the user to verify

The user completes the humanness check on their mobile device. You can either:

Poll the /get_status endpoint (see Check connection status below).
Listen for a USER_VERIFICATION_COMPLETED webhook. (Recommended)

If you provided a redirect_url during registration, the user will be sent back to your app/website automatically when verification finishes.

Step 3: Retrieve the results

Once the user has verified, call /get_status to get the simple_data_request_response containing the humanness score and other verification data. See Check connection status below.

Enforcing uniqueness with `uniqueness_region_id`

By default, unique human ID uniqueness is enforced at the service account level: each real person can only verify once across your entire account. If you don’t have a persistent reference_user_id for the user (e.g. anonymous surveys), you can pass an ephemeral session or token ID as the reference_user_id and use uniqueness_region_id to scope uniqueness to a specific context instead. For example, passing a survey ID as the uniqueness_region_id ensures each person can only complete that particular survey once, without requiring you to track users across surveys.

curl -X POST "$VERIFYYOU_API_BASE/v1/business_connect_user/register" \
  -H "Content-Type: application/json" \
  -H "API-KEY: $VERIFYYOU_API_KEY" \
  -d '{
    "reference_user_id": "session_abc123",
    "redirect_url": "https://yourapp.com/survey/done",
    "uniqueness_region_id": "survey_456",
    "data_request": [
      {
        "type": "GET_HUMANNESS_SCORE_AND_UNIQUE_HUMAN_ID"
      }
    ]
  }'

Data request types

Each object in the data_request array on /register determines what data you receive back about the user.

Type	Description
`GET_HUMANNESS_SCORE_AND_UNIQUE_HUMAN_ID`	Returns a humanness score plus a unique human identifier
`IS_PHONE_NUMBER_VERIFIED`	Returns whether the user’s phone number is verified - always true, placeholder request for testing

Check connection status

Poll for a user’s connection status and retrieve verification results.

curl -X POST "$VERIFYYOU_API_BASE/v1/business_connect_user/get_status" \
  -H "Content-Type: application/json" \
  -H "API-KEY: $VERIFYYOU_API_KEY" \
  -d '{
    "reference_user_id": "user_123"
  }'

Success response:

{
  "status": "success",
  "has_connection": true,
  "simple_data_request_response": [
    {
      "result": {
        "humanness_score": 21
      },
      "type": "GET_HUMANNESS_SCORE_AND_UNIQUE_HUMAN_ID"
    }
  ]
}

The simple_data_request_response is an array of result objects, one per data request type you specified during registration. Each object contains a type and a result with the corresponding verification data. If the user does not exist, the response returns a DOES_NOT_EXIST failure code.

Set up a webhook

Subscribe to USER_VERIFICATION_COMPLETED to get notified when a user finishes verification.

curl -X POST "$VERIFYYOU_API_BASE/v1/webhook/admin/config/create_or_edit" \
  -H "Content-Type: application/json" \
  -H "API-KEY: $VERIFYYOU_API_KEY" \
  -d '{
    "webhook_type": "USER_VERIFICATION_COMPLETED",
    "destination_url": "https://yourapp.com/webhooks/verifyyou"
  }'

See Webhooks for event types, payload format, signature verification, admin endpoints, and more.

Handling maintenance downtime

During scheduled maintenance, all API endpoints will return a 503 Service Unavailable HTTP status with the following response:

{
  "status": "failure",
  "failure_code": "SERVICE_TEMPORARILY_UNAVAILABLE",
  "failure_reason": "Service is temporarily unavailable for maintenance. Please try again later."
}

Consider implementing a “fail open” approach to handle maintenance periods gracefully:

Fail open: Allow user registration to proceed without VerifyYou verification when the service is unavailable
Fail closed: Block user registration until VerifyYou is available again
Graceful fallback: Display a user-friendly message explaining the temporary delay

This approach ensures your application remains operational during VerifyYou maintenance windows.

Next steps

Read the full Webhooks guide to handle all event types and verify signatures.
Explore the different data request types to request the verification signals you need.

​Before you start

​Step 1: Register a user and request a humanness check

​Step 2: Wait for the user to verify

​Step 3: Retrieve the results

​Enforcing uniqueness with uniqueness_region_id

​Data request types

​Check connection status

​Set up a webhook

​Handling maintenance downtime

​Next steps