---
title: "Create Identity Verification Page"
source_url: https://docs.rapyd.net/en/create-identity-verification-page.html
lang: en
---

# Create Identity Verification Page

Create a hosted page for verifying the identity of a personal contact for a Rapyd Wallet.

The customer completes the process by accessing the URL returned in the response.

After the customer submits the identity verification request on the hosted page, Rapyd verifies the information and sends you a webhook with a summary of the identity check. See:

- [Identity Verification Webhook - Sandbox Approved](https://docs.rapyd.net/en/identity-verification-webhook---sandbox-approved.md "Identity Verification Webhook - Sandbox Approved")
- [Identity Verification Webhook - Production Approved](https://docs.rapyd.net/en/identity-verification-webhook---production-approved.md "Identity Verification Webhook - Production Approved")
- [Identity Verification Webhook - Production Not Approved](https://docs.rapyd.net/en/identity-verification-webhook---production-not-approved.md "Identity Verification Webhook - Production Not Approved")

> **Note:**
>
> - The code samples include successful requests (200) and bad requests (400).
>
>   - For error messages that appear due to bad requests (400), see:
>
>     - [General Errors](https://docs.rapyd.net/en/general-errors.md "General Errors")
>     - [Hosted Page Identity Verification Errors](https://docs.rapyd.net/en/hosted-page-identity-verification-errors.md "Hosted Page Identity Verification Errors")
>   - For information about unauthorized request (401) and other authentication errors, see [Troubleshooting Authentication and Authorization Errors](https://docs.rapyd.net/en/troubleshooting-authentication-and-authorization-errors.md "Troubleshooting Authentication and Authorization Errors").

**Prerequisites**

- Rapyd Wallet. See [Create Wallet](https://docs.rapyd.net/en/create-wallet.md "Create Wallet").

### Parameters

### Request Header Parameters

- - access_key
  - Unique access key provided by Rapyd for each authorized user.

    See [Developers](https://docs.rapyd.net/en/developers.md "Developers").
- - Content-Type
  - Indicates that the data appears in JSON format. Set to **application/json**.
- - idempotency
  - A unique key that prevents the platform from creating the same object twice.

    See [Idempotency](https://docs.rapyd.net/en/idempotency.md "Idempotency").
- - salt
  - Random string. Recommended length: 8-16 characters.
- - signature
  - Signature calculated for each request individually.

    See [Request Signatures](https://docs.rapyd.net/en/request-signatures.md "Request Signatures").
- - timestamp
  - Timestamp for the request, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time") (seconds).

### Request Body Parameters

- - cancel_url
  - URL where the customer is redirected after pressing **Back to Website** to exit the hosted page. This URL overrides the `merchant_website` URL. Does not support localhost URLs.
- - complete_url
  - URL where the customer is redirected after pressing **Close** to exit the hosted page. This URL overrides the `merchant_website` URL. Does not support localhost URLs.
- - contact
  - ID of the wallet contact. String starting with **cont_**.
- - country
  - The two-letter ISO 3166-1 ALPHA-2 code for the country of the identification document. Must match the wallet contact country.
- - document_type
  - Type of identification document. Two-letter code.

    See [List Official Identification Documents](https://docs.rapyd.net/en/list-official-identification-documents.md "List Official Identification Documents").
- - ewallet
  - ID of the Rapyd Wallet. String starting with **ewallet_**.
- - force_camera
  - Requires the applicant to use the device's camera for a current face image, and prohibits uploading an existing image file. Default is **false**.
- - language
  - Determines the default language of the hosted page. For a list of values, see [List Supported Languages](https://docs.rapyd.net/en/list-supported-languages.md "List Supported Languages").

    - When this parameter is null, the language of the user's browser is used.
    - If the language of the user's browser cannot be determined, the default language is English.
- - page_expiration
  - End of the time when the customer can use the hosted page, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). If `page_expiration` is not set, the hosted page expires 14 days after creation.

    **Range:** 1 minute to 30 days.
- - reference_id
  - ID of the identity verification request. Must be unique for each request. Defined by the client.
- - request_type
  - Determines the action that is taken on the request. One of the following:

    - **store** - Store the images on the Rapyd platform.
    - **verify** - Verify the identity of the person in the images.

### Response Parameters

- - cancel_url
  - URL where the customer is redirected after pressing **Back to Website** to exit the hosted page. This URL overrides the `merchant_website` URL. Does not support localhost URLs.
- - complete_url
  - URL where the customer is redirected after pressing **Close** to exit the hosted page. This URL overrides the `merchant_website` URL. Does not support localhost URLs.
- - contact
  - ID of a wallet contact. String starting with **cont_**.
- - country
  - The two-letter ISO 3166-1 ALPHA-2 code for the country of the identification document.
- - id
  - ID of the Hosted Page Identity Verification object, a string starting with **hp_idv_**.
- - language
  - Determines the default language of the hosted page. For a list of values, see [List Supported Languages](https://docs.rapyd.net/en/list-supported-languages.md "List Supported Languages").

    - When this parameter is null, the language of the user's browser is used.
    - If the language of the user's browser cannot be determined, the default language is English.
- - merchant_alias
  - Client's name.

    Rapyd
- - merchant_color
  - Color of the call-to-action (CTA) button on the hosted page.

    To configure this field, use the Client Portal. See [Customizing Your Hosted Page](https://docs.rapyd.net/en/customizing-your-hosted-page.md "Customizing Your Hosted Page").
- - merchant_customer_support
  - Contains details of the client’s customer support. To configure these fields, use the Client Portal. See [Customizing Your Hosted Page](https://docs.rapyd.net/en/customizing-your-hosted-page.md "Customizing Your Hosted Page").

    - - email
      - Email address.
    - - url
      - URL for the client's customer support service.
    - - phone_number
      - Phone number for contacting the client's customer support service.
- - merchant_logo
  - URL for the image of the client's logo.

    To configure this field, use the Client Portal. See [Customizing Your Hosted Page](https://docs.rapyd.net/en/customizing-your-hosted-page.md "Customizing Your Hosted Page").
- - merchant_privacy_policy
  - URL for the terms and conditions of the agreement between the client and the client’s customers.

    To configure this field, use the Client Portal. See [Customizing Your Hosted Page](https://docs.rapyd.net/en/customizing-your-hosted-page.md "Customizing Your Hosted Page").
- - merchant_terms
  - URL for the terms and conditions of the agreement between the client and the client’s customers. To configure this field, use the Client Portal.
- - merchant_website
  - The URL where the customer is redirected after exiting the hosted page.

    Relevant when one or both of the following fields is unset:

    - `cancel_url`
    - `complete_url`

    To configure this field, use the Client Portal. See [Customizing Your Hosted Page](https://docs.rapyd.net/en/customizing-your-hosted-page.md "Customizing Your Hosted Page").
- - page_expiration
  - End of the time when the customer can use the hosted page, in [Unix time](https://docs.rapyd.net/en/glossary.md#UUID-945d98cf-adae-e1cf-2606-c7fae8b4a7e1_unix_time "Unix time"). If `page_expiration` is not set, the hosted page expires 14 days after creation.

    **Range:** 1 minute to 30 days.
- - redirect_url
  - URL of the hosted page that is shown to the customer.
- - reference_id
  - ID of the identity verification request. Must be unique for each request. Defined by the client.
- - request_type
  - Determines the action that is taken on the request. One of the following:

    - **store** - Store the images on the Rapyd platform.
    - **verify** - Verify the identity of the person in the images.
- - status
  - Status of the hosted page. One of the following:

    - **NEW** - The hosted page was created.
    - **DON** - Done. The identity verification request was submitted.
    - **EXP** - Expired. The hosted page expired.
- - wallet
  - ID of the Rapyd Wallet. String starting with **ewallet_**.

- /v1/hosted/idv

- Create Identity Verification Page
- ```curl
  curl -X post 'https://sandboxapi.rapyd.net/v1/hosted/idv' \
  -H 'access_key: your-access-key-here' \
  -H 'Content-Type: application/json' \
  -H 'idempotency: your-idempotency-parameter-here' \
  -H 'salt: your-random-string-here' \
  -H 'signature: your-calculated-signature-here' \
  -H 'timestamp: your-unix-timestamp-here' \
  --data-raw '{
      "contact": "cont_c34bd6bfd9575f6f7b06647999a93126",
      "ewallet": "ewallet_755b0fd11fd22b33328fff7d30f3ce30",
      "reference_id": "2025-10-12a"
  }'
  ```
- ```json
  {
      "status": {
          "error_code": "",
          "status": "SUCCESS",
          "message": "",
          "response_code": "",
          "operation_id": "bf6312fb-2390-4aef-89f9-c5e95719b796"
      },
      "data": {
          "status": "NEW",
          "cancel_url": "https://example1234.net",
          "complete_url": "https://example1234.net",
          "merchant_color": "323fff",
          "merchant_logo": null,
          "merchant_website": "https://example1234.net",
          "merchant_customer_support": {
              "url": "https://example1234.net",
              "email": "support@example1234.net",
              "phone_number": "121255551213"
          },
          "merchant_alias": "Doc Team",
          "merchant_terms": "https://example1234.net/terms_and_conditions",
          "merchant_privacy_policy": "https://example1234.net/privacy_policy",
          "page_expiration": 1761483927,
          "redirect_url": "https://sandboxhosted.rapyd.net/idv?token=hp_idv_99daeb3bd90be6fa13a2b5821ed89f30",
          "id": "hp_idv_99daeb3bd90be6fa13a2b5821ed89f30",
          "reference_id": "2025-10-12a",
          "wallet": "ewallet_755b0fd11fd22b33328fff7d30f3ce30",
          "contact": "cont_c34bd6bfd9575f6f7b06647999a93126",
          "country": null,
          "request_type": "verify",
          "force_camera": false,
          "document_type": null,
          "language": null
      }
  }
  ```

- Bad Request - Non-Unique Reference ID
- ```curl
  curl -X post 'https://sandboxapi.rapyd.net/v1/hosted/idv' \
  -H 'access_key: your-access-key-here' \
  -H 'Content-Type: application/json' \
  -H 'idempotency: your-idempotency-parameter-here' \
  -H 'salt: your-random-string-here' \
  -H 'signature: your-calculated-signature-here' \
  -H 'timestamp: your-unix-timestamp-here' \
  --data-raw '{
      "contact": "cont_c34bd6bfd9575f6f7b06647999a93126",
      "ewallet": "ewallet_755b0fd11fd22b33328fff7d30f3ce30",
      "reference_id": "2025-10-12a"
  }'
  ```
- ```json
  {
      "status": {
          "error_code": "ERROR_ID_VERIFICATION_DUPLICATE_REFERENCE_ID",
          "status": "ERROR",
          "message": "The request tried to validate identity, but the 'reference_id' body parameter was previously used. The request was rejected. Corrective action: Provide a unique reference ID for each identity verification operation, whether successful or unsuccessful.",
          "response_code": "ERROR_ID_VERIFICATION_DUPLICATE_REFERENCE_ID",
          "operation_id": "95a2ec6e-d118-44a0-adc0-f413fa79bd5a"
      }
  }
  ```

- Bad Request - Unknown Document Type
- ```curl
  curl -X post 'https://sandboxapi.rapyd.net/v1/hosted/idv' \
  -H 'access_key: your-access-key-here' \
  -H 'Content-Type: application/json' \
  -H 'idempotency: your-idempotency-parameter-here' \
  -H 'salt: your-random-string-here' \
  -H 'signature: your-calculated-signature-here' \
  -H 'timestamp: your-unix-timestamp-here' \
  --data-raw '{
      "contact": "cont_c34bd6bfd9575f6f7b06647999a93126",
      "ewallet": "ewallet_755b0fd11fd22b33328fff7d30f3ce30",
      "reference_id": "2026-01-08a",
      "document_type": "abcd"
  }'
  ```
- ```json
  {
      "status": {
          "error_code": "ERROR_HOSTED_PAGE_VERIFY_IDENTITY_DOCUMENT_TYPE_NOT_VALID",
          "status": "ERROR",
          "message": "The request tried to create a hosted page for identity verification, but the type of identification document is not correct for the country specified. The request was rejected. Corrective action: In the 'document_type' field, provide the code for the document type, as appears in the response to 'List Official Identification Documents'.",
          "response_code": "ERROR_HOSTED_PAGE_VERIFY_IDENTITY_DOCUMENT_TYPE_NOT_VALID",
          "operation_id": "b647010f-de54-4b38-ad98-c0a373e986f4"
      }
  }
  ```