> ## Documentation Index
> Fetch the complete documentation index at: https://docs.verifyyou.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick start

> Perform a humanness check on your users with the VerifyYou API

## Before you start

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

```bash theme={null}
export VERIFYYOU_API_BASE=https://api.connect.verifyyou.com
```

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

```bash theme={null}
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:**

```json theme={null}
{
  "status": "success",
  "invite_url": "https://verifyyou.com/invite/...",
  "user_id": "bcu_123",
  "connection_verified": false
}
```

**Failure response:**

```json theme={null}
{
  "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](#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](#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.

```bash theme={null}
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.

```bash theme={null}
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:**

```json theme={null}
{
  "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.

```bash theme={null}
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](/v1/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:

```json theme={null}
{
  "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](/v1/webhooks) guide to handle all event types and verify signatures.
* Explore the different [data request types](#data-request-types) to request the verification signals you need.