# Create a VerificationSession

Creates a VerificationSession object.

After the VerificationSession is created, display a verification modal using the session `client_secret` or send your users to the session’s `url`.

If your API key is in test mode, verification checks won’t actually process, though everything else will occur as if in live mode.

Related guide: [Verify your users’ identity documents](https://docs.stripe.com/docs/identity/verify-identity-documents.md)

## Request

```curl
curl https://api.stripe.com/v1/identity/verification_sessions \
  -u "<<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2025-06-30.basil" \
  -d type=document
```

### Response

```json
{
  "id": "vs_1NuN4zLkdIwHu7ixleE6HvkI",
  "object": "identity.verification_session",
  "client_secret": "...",
  "created": 1695680197,
  "last_error": null,
  "last_verification_report": null,
  "livemode": false,
  "metadata": {},
  "options": {},
  "redaction": null,
  "status": "requires_input",
  "type": "document",
  "url": "..."
}
```

## Returns

Returns the created VerificationSession object

## Parameters

- `client_reference_id` (string, optional)
  A string to reference this user. This can be a customer ID, a session ID, or similar, and can be used to reconcile this verification with your internal systems.

- `metadata` (object, optional)
  Set of [key-value pairs](https://docs.stripe.com/docs/api/metadata.md) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`.

- [`options`](https://docs.stripe.com/api/identity/verification_sessions/create.md?query=options) (object, optional)
  A set of options for the session’s verification checks.

- [`provided_details`](https://docs.stripe.com/api/identity/verification_sessions/create.md?query=provided_details) (object, optional)
  Details provided about the user being verified. These details may be shown to the user.

- `related_customer` (string, optional)
  Customer ID

- `related_customer_account` (string, optional)
  Token referencing a Customer Account resource.

- [`related_person`](https://docs.stripe.com/api/identity/verification_sessions/create.md?query=related_person) (object, optional)
  Tokens referencing a Person resource and it’s associated account.

- `return_url` (string, optional)
  The URL that the user will be redirected to upon completing the verification flow.

- `type` (enum, optional)
  The type of [verification check](https://docs.stripe.com/docs/identity/verification-checks.md) to be performed. You must provide a `type` if not passing `verification_flow`.
Possible enum values:
  - `document`
    [Document check](https://docs.stripe.com/docs/identity/verification-checks.md?type=document).

  - `id_number`
    [ID number check](https://docs.stripe.com/docs/identity/verification-checks.md?type=id-number).

- `verification_flow` (string, optional)
  The ID of a verification flow from the Dashboard. See https://docs.stripe.com/identity/verification-flows.