---
title: "Create phone session"
method: POST
path: "/api/v1/sessions"
tags: ["Sessions"]
---

# Create phone session

`POST /api/v1/sessions`

## Request

- Base URL: `https://api.proof.holdings`
- URL: `https://api.proof.holdings/api/v1/sessions`
- Auth: HTTP bearer

Create a phone verification session (phone-first flow).

## Request body

- CreateSessionRequest: Request body for creating a phone verification session
  - `profile_id` string: The sub-account (project) this is for; its branding and templates are used for every message. An account-wide key may name any project of its account; a project-bound key acts for its own project only (naming another answers `403 profile_mismatch`). Omitted: the key's project, else the primary project.
  - `phone` string, required: Phone number in E.164 format
  - `channel` 'whatsapp' | 'telegram' | 'sms': Preferred messaging channel

## Response `201`

Session created

- Session: Phone verification session
  - `id` string, required: MongoDB ObjectId
  - `status` 'pending' | 'verified' | 'expired', required
  - `challenge` Challenge: Challenge details for verification
    - `code` string: Challenge code to send/enter
    - `instruction` string: Human-readable instruction for the user
    - `expires_at` string, date-time: When the challenge expires
  - `proof` Proof: Proof token after successful verification
    - `token` string, required: Signed JWT proof token (ES256; verify against the JWKS key named by the token's `kid`)
    - `expires_at` string, date-time, required: When the proof expires
    - `confidence` 'high' | 'standard' | 'degraded': Verification confidence level (present for SMS verifications)
  - `created_at` string, date-time, required
  - `expires_at` string, date-time, required

## Other responses

- `400`: Validation error
- `402`: card_required. Only once billing is live: a free account with no card on file that has used its included proofs and the 50-proof grace this month is refused new proof requests until a card is added (add_card_url). Proofs already issued keep working. The error carries add_card_url, used, included and hard_limit.
- `403`: profile_mismatch — a project-bound API key named another project (it acts for its own project only); profile_not_owned — the named project does not belong to the account (h-subaccount-branding-per-project)

---

[API](https://skmtc.dev/proof/apis/proof-holdings-api.md) · [All operations](https://skmtc.dev/proof/apis/proof-holdings-api/llms.txt) · [OpenAPI document](https://skmtc.dev/proof/apis/proof-holdings-api/revisions/b15f506de696?raw)