Skip to main content

​
Before you start

  • You have a service account.
  • You have an API key for that service account.

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

Register a user, specify the data you want back, and get an invite URL to send them through verification. 
curl -X POST "$CONNECT_API_BASE/v1/business_connect_user/register" \
  -H "Content-Type: application/json" \
  -H "API-KEY: $CONNECT_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 "$CONNECT_API_BASE/v1/business_connect_user/register" \
  -H "Content-Type: application/json" \
  -H "API-KEY: $CONNECT_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

The data_request.type field on /register determines what data you receive back about the user.
TypeDescription
GET_HUMANNESS_SCORE_AND_UNIQUE_HUMAN_IDReturns a humanness score plus a unique human identifier
IS_PHONE_NUMBER_VERIFIEDReturns 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 "$CONNECT_API_BASE/v1/business_connect_user/get_status" \
  -H "Content-Type: application/json" \
  -H "API-KEY: $CONNECT_API_KEY" \
  -d '{
    "reference_user_id": "user_123"
  }'
Success response: 
{
  "status": "success",
  "has_connection": true,
  "simple_data_request_response": {
    "humanness_score": 97,
    "fulfillment_time_s": 12
  }
}
The simple_data_request_response is a plaintext JSON object containing the verification results for the data request type you specified during registration. 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 "$CONNECT_API_BASE/v1/webhook/admin/config/create_or_edit" \
  -H "Content-Type: application/json" \
  -H "API-KEY: $CONNECT_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.

​
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.