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:

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
  - Hosted Page Identity Verification Errors
- For information about unauthorized request (401) and other authentication errors, see Troubleshooting Authentication and Authorization Errors.

Prerequisites

Rapyd Wallet. See Create Wallet.

Parameters

Request Header Parameters

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.
- 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.
  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. 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.
  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.
- merchant_customer_support
- Contains details of the client’s customer support. To configure these fields, use the Client Portal. See 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.
- 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.
- 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.
- page_expiration
- End of the time when the customer can use the hosted page, in 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 -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"
}'

{
    "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 -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"
}'

{
    "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 -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"
}'

{
    "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"
    }
}

In this section:

Documentation