Verification Sessions#

A Verification Session represents a verification flow where a tenant connects bank accounts, uploads documents, or authorizes data access. Each session can include multiple verification products.

The Verification Session object#

Attribute	Type	Description
`id`	string	Unique identifier with `vs_` prefix
`object`	string	Always `"verification_session"`
`status`	enum	One of `created`, `pending`, `processing`, `completed`, `expired`, `failed`
`applicant`	object	Applicant details: `first_name`, `last_name`, `email`, `date_of_birth`, `phone`, `address`
`products`	array	Checks to run: `identity`, `income`, `credit`, `cash_flow`, `documents`
`redirect_url`	string	Where to send applicant after completion
`webhook_url`	string	Override default webhook endpoint
`client_secret`	string	Secret for client-side widget initialization
`report`	string	ID of the generated Verification Report (when completed)
`metadata`	hash	Set of key-value pairs for storing additional information
`expires_at`	timestamp	When this session expires (default: 7 days)
`created`	timestamp	Time at which the object was created (Unix timestamp)
`livemode`	boolean	Whether this is a live mode object

{
  "id": "vs_1a2b3c4d5e6f",
  "object": "verification_session",
  "status": "completed",
  "applicant": {
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "jane.doe@example.com",
    "date_of_birth": "1990-05-15",
    "phone": "+44 7700 900123",
    "address": {
      "line1": "123 High Street",
      "city": "London",
      "postal_code": "SW1A 1AA",
      "country": "GB"
    }
  },
  "products": ["identity", "income", "credit", "cash_flow"],
  "redirect_url": "https://your-app.com/verification/complete",
  "client_secret": "vs_secret_abc123def456",
  "report": "vr_9z8y7x6w5v",
  "metadata": {
    "property_id": "prop_456",
    "unit": "4B"
  },
  "expires_at": 1706745600,
  "created": 1706140800,
  "livemode": false
}

Create a Verification Session#

Creates a new verification session for a tenant applicant.

POST /v1/verification_sessions

Parameters#

Parameter	Type	Required	Description
`applicant`	object	Yes	Applicant details
`applicant.first_name`	string	Yes	Applicant's first name
`applicant.last_name`	string	Yes	Applicant's last name
`applicant.email`	string	Yes	Applicant's email address
`applicant.date_of_birth`	string	No	Date of birth (YYYY-MM-DD)
`applicant.phone`	string	No	Phone number in E.164 format
`applicant.address`	object	No	Applicant's address
`products`	array	Yes	Verification products to run
`redirect_url`	string	No	URL to redirect after completion
`webhook_url`	string	No	Override webhook endpoint
`metadata`	hash	No	Key-value pairs

Returns#

Returns the Verification Session object.

curl https://api.casapay.com/v1/verification_sessions \
  -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc" \
  -H "Content-Type: application/json" \
  -d '{
    "applicant": {
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane.doe@example.com",
      "date_of_birth": "1990-05-15"
    },
    "products": ["identity", "income", "credit", "cash_flow"],
    "redirect_url": "https://your-app.com/verification/complete"
  }'

{
  "id": "vs_1a2b3c4d5e6f",
  "object": "verification_session",
  "status": "created",
  "client_secret": "vs_secret_abc123def456",
  "redirect_url": "https://verify.casapay.com/session/vs_1a2b3c4d5e6f",
  "created": 1706140800
}

Retrieve a Verification Session#

Retrieves the details of an existing verification session.

GET /v1/verification_sessions/:id

Parameters#

Parameter	Type	Required	Description
`id`	string	Yes	The ID of the verification session

curl https://api.casapay.com/v1/verification_sessions/vs_1a2b3c4d5e6f \
  -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc"

List Verification Sessions#

Returns a list of verification sessions. Sessions are returned sorted by creation date, with the most recent first.

GET /v1/verification_sessions

Parameters#

Parameter	Type	Required	Description
`status`	string	No	Filter by status
`applicant_email`	string	No	Filter by applicant email
`limit`	integer	No	Number of objects to return (1–100, default 10)
`starting_after`	string	No	Cursor for forward pagination
`ending_before`	string	No	Cursor for backward pagination

curl https://api.casapay.com/v1/verification_sessions?status=completed&limit=5 \
  -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc"

{
  "object": "list",
  "data": [
    {
      "id": "vs_1a2b3c4d5e6f",
      "object": "verification_session",
      "status": "completed",
      "applicant": { "first_name": "Jane", "last_name": "Doe" },
      "created": 1706140800
    }
  ],
  "has_more": false,
  "url": "/v1/verification_sessions"
}

Cancel a Verification Session#

Cancels a verification session that has not yet completed.

POST /v1/verification_sessions/:id/cancel

Parameters#

Parameter	Type	Required	Description
`id`	string	Yes	The ID of the verification session
`cancellation_reason`	string	No	Reason for cancellation

curl -X POST https://api.casapay.com/v1/verification_sessions/vs_1a2b3c4d5e6f/cancel \
  -H "Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc" \
  -H "Content-Type: application/json" \
  -d '{"cancellation_reason": "applicant_withdrawn"}'

{
  "id": "vs_1a2b3c4d5e6f",
  "object": "verification_session",
  "status": "canceled",
  "created": 1706140800
}