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

# Create a Verification

> Initiate a new contact details verification via email and OTP.

<Card title="Contact Verification Guide" icon="book" href="/additional-functions/contact-verification">
  How the email + OTP verification flow works end-to-end
</Card>

Initiates a new contact details verification. PCI Booking sends an email containing a secure link to the provided address. When the recipient clicks the link, they verify their phone number using a one-time passcode (OTP) sent via SMS or voice call.

## Error Responses

| HTTP Status | Error Code | Description                                                                                                                            |
| ----------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| 400         | -125       | Validation error. Required fields are missing or have invalid format (e.g. invalid email, phone number, or `ttlMinutes` out of range). |
| 401         | -1003      | Not authenticated. The API key is missing or invalid.                                                                                  |
| 500         | -150       | Internal system error. Identity could not be resolved after authentication.                                                            |

## Parameter Constraints

| Parameter     | Constraint                                                                                                                                                                                   |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `email`       | Required. Must be a valid email address.                                                                                                                                                     |
| `phone`       | Required. International format with country code, no leading `+` sign. Must contain 8 to 20 digits.                                                                                          |
| `personName`  | Optional. Max 100 characters.                                                                                                                                                                |
| `language`    | Optional. Defaults to `en`. Supported: `en`, `es`, `fr`, `de`, `it`, `pt`, `nl`, `pl`, `ru`, `ja`, `ko`, `zh`, `ar`, `hi`, `tr`, `sv`, `da`, `nb`, `no`, `ro`, `is`, plus regional variants. |
| `ttlMinutes`  | Optional. Integer from 1 to 30. Defaults to 10.                                                                                                                                              |
| `callbackUrl` | Optional. Must be a valid URL.                                                                                                                                                               |

<Info>
  Phone numbers must be in international format, including the country code, without a leading `+` sign (e.g. `972544735557`).
</Info>

## Parameters

### Headers

<ParamField header="Authorization" type="string" required>
  Your API key prefixed with `APIKEY`. Example: `APIKEY your-api-key`. See the [Authentication guide](/getting-started/authentication).
</ParamField>

### Contact Details

<ParamField body="email" type="string" required>
  The email address to send the verification link to.
</ParamField>

<ParamField body="phone" type="string" required>
  The phone number to verify via OTP, in international format without a leading `+` sign (e.g. `972544735557`).
</ParamField>

<ParamField body="personName" type="string">
  The name of the recipient. Shown in the email greeting and verification screens.
</ParamField>

### Message Options

<ParamField body="senderName" type="string">
  The name that appears as the SMS sender (supported in most countries).
</ParamField>

<ParamField body="language" type="string" default="en">
  The language for the email and verification page, as a two-letter ISO 639-1 code (e.g. `en`).
</ParamField>

<ParamField body="ttlMinutes" type="number" default="10">
  How long the verification link stays valid, in minutes. Allowed range: 1 to 30.
</ParamField>

### Callback & Tracking

<ParamField body="callbackUrl" type="string">
  A URL to which PCI Booking will POST the result when the session reaches a terminal state. See [Receive Result Notification](/api-reference/additional/receive-result-notification).
</ParamField>

<ParamField body="metadata" type="string">
  A free-form reference string stored with the session and echoed back in all responses and callbacks.
</ParamField>

<RequestExample>
  ```javascript Node.js theme={null}
  const response = await fetch('https://service.pcibooking.net/api/verify', {
    method: 'POST',
    headers: {
      'Authorization': 'APIKEY your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      email: 'john.doe@example.com',
      phone: '972544735557',
      personName: 'John Doe',
      language: 'en',
      ttlMinutes: 15,
      callbackUrl: 'https://yourplatform.com/verify-callback',
      metadata: 'MY-REFERENCE_098'
    })
  });

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://service.pcibooking.net/api/verify',
      headers={
          'Authorization': 'APIKEY your-api-key',
          'Content-Type': 'application/json'
      },
      json={
          'email': 'john.doe@example.com',
          'phone': '972544735557',
          'personName': 'John Doe',
          'language': 'en',
          'ttlMinutes': 15,
          'callbackUrl': 'https://yourplatform.com/verify-callback',
          'metadata': 'MY-REFERENCE_098'
      }
  )

  print(response.json())
  ```
</RequestExample>

## Response

| Field       | Type     | Description                                                                                      |
| ----------- | -------- | ------------------------------------------------------------------------------------------------ |
| `verifyId`  | string   | The unique ID of the verification session. Use this in all subsequent status and results calls.  |
| `status`    | string   | The initial status. Always `Pending` on creation.                                                |
| `expiresAt` | datetime | The UTC datetime at which the verification link expires, based on `ttlMinutes`. ISO 8601 format. |

<ResponseExample>
  ```json 200 theme={null}
  {
      "verifyId": "xLoat3F385vvFRbgI2usOeuXKXQoB8kv",
      "status": "Pending",
      "expiresAt": "2026-03-15T18:44:21Z"
  }
  ```

  ```json 400 theme={null}
  {
      "code": -125,
      "message": "Bad input data",
      "moreInfo": "...",
      "errorList": null
  }
  ```
</ResponseExample>