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

# Create User

> Create or fetch a publisher-linked widget user.

## Description

Provisions a user in ZBD for your project. Idempotent — if a user with the same `reference_id` or `email` already exists for your project, the existing user is returned.

Call this from your server before creating a widget session.

<Note>
  Some cashout methods require the user to accept the latest disclosure before cashout can proceed. The hosted widget can collect this during the session. If your integration records disclosure acceptance before opening the widget, see [Disclosure Agreements](/widget/disclosures).
</Note>

## Configuration

### Header Parameters

<ParamField required header="apikey" type="string">
  Your ZBD project API key (production scope).
</ParamField>

<ParamField initialValue="application/json" header="Content-Type" type="string">
  Content Type
</ParamField>

### Body Parameters

<ParamField required body="reference_id" type="string">
  Your stable internal user identifier. Must be unique per project.
</ParamField>

<ParamField required body="email" type="string">
  User's email address. Used for OTP verification in the widget.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.zbdpay.com/api/v1/widget/users \
    -H "apikey: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "reference_id": "player-42",
      "email": "player@example.com"
    }'
  ```
</RequestExample>

## Response

The response `data` includes the new (or existing) user plus an `outstanding_disclosures` array — the disclosure versions this user still needs to accept. This is returned on the **first user request**, so you have the user's outstanding disclosures immediately, with no extra call.

<ResponseField name="outstanding_disclosures" type="array">
  Disclosure versions the user has not yet accepted. Empty when the user is current on all disclosures. Each entry includes `id`, `type_id`, `name`, `description`, `version`, `content_uri`, `created_at`, and `due_date`.
</ResponseField>

<Note>
  `outstanding_disclosures` lists only what is still outstanding. To list a user's full acceptance state (including what they have **already accepted**), call [Get Disclosure Status](/widget/get-disclosure-status) at any time. See [Disclosure Agreements](/widget/disclosures) for the full model.
</Note>

<ResponseExample>
  ```json 201 theme={null}
  {
    "success": true,
    "data": {
      "id": "4ac4fd8a-cc2c-4d03-af09-a76f4e89d652",
      "reference_id": "player-42",
      "email": "player@example.com",
      "outstanding_disclosures": [
        {
          "id": 12,
          "type_id": 2,
          "name": "Terms of Service",
          "description": "ZBD Terms of Service Document.",
          "version": "1.4.0",
          "content_uri": "https://...",
          "created_at": "2026-06-24T20:11:45Z",
          "due_date": "2025-08-11T00:00:00"
        }
      ]
    }
  }
  ```
</ResponseExample>