> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.
# Mobile-ID
> Start Mobile-ID identity verification through the standalone API, without a workflow.
Start Mobile-ID verification from your backend using your application API key.
You do not need a workflow or a `workflow_id`.
The start response describes the next authentication action; it is not an approved identity result.
## Coverage and activation
| Property | Value |
| - | - |
| Wallet | Mobile-ID |
| Wallet ID | `mobile_id` |
| Countries | 
Estonia, 
Lithuania |
| Production wallet activation | ✅ Available |
| Published wallet price | \$0.20 per completed verification |
Wallet activation is separate from API deployment and your application's eligibility.
A documented endpoint does not activate a wallet that is marked Coming soon.
For current published rates, see [digital ID wallet pricing](/getting-started/pricing#digital-id-wallet-pricing).
## What the person does
Display the comparison code in your application and wait for the person to approve on their phone.
The person enters their PIN on their phone, never in your application or API request.
The all-zero identifiers in the request example are for Didit sandbox simulation only; use the person's registered details for live authentication.
## Receive the result
Follow the [Digital ID wallet API guide](/standalone-apis/digital-id-wallets) to track the verification and retrieve its result.
Treat only a completed, verified result as proof that the wallet authenticated the person.
Returned identity attributes vary by wallet; do not assume an address, portrait or every requested attribute is present.
## Related
* [Digital ID wallet APIs](/standalone-apis/digital-id-wallets)
* [Wallet coverage and attributes](/core-technology/id-verification/digital-id-wallets)
* [Pricing](/getting-started/pricing#digital-id-wallet-pricing)
## OpenAPI
````yaml POST /v3/id-verification/wallets/mobile-id/
openapi: 3.0.0
info:
version: 3.0.0
title: Didit Verification API
description: Identity verification API. Authenticate with x-api-key header.
servers:
- url: https://verification.didit.me
security: []
tags: []
paths:
/v3/id-verification/wallets/mobile-id/:
post:
tags:
- Digital ID wallets
summary: Start Mobile-ID verification
description: >-
Start a Mobile-ID sign-in (SK ID Solutions with the national mobile
operators; EST, LTU) without any workflow. Billed once, only when the
identity is verified. The response carries
next_action.type=confirm_in_app with the comparison code to show the
user; the user confirms it and enters their PIN in the app (never
collect the PIN). Poll POST
/v3/id-verification/wallets/verifications/{request_id}/poll/ every
poll_interval_seconds, or rely on the webhook: Didit polls in the
background too. Sandbox applications get a deterministic simulation
(simulated: true) that never contacts the provider.
operationId: start_mobile_id_wallet_verification
parameters:
- in: header
name: Idempotency-Key
schema:
type: string
description: >-
Optional retry-safety key (max 255 characters). Retrying with the
same key, wallet and body returns the original verification without
starting a second sign-in; the same key with another wallet or body
returns 409 idempotency_key_reused.
requestBody:
content:
application/json:
schema:
$ref: >-
#/components/schemas/DigitalIdWalletApiMobileIdWalletVerificationStartRequest
example:
country: EST
vendor_data: your-customer-reference
metadata:
reference: example
personal_code: '00000000000'
phone_number: '+37200000000'
application/x-www-form-urlencoded:
schema:
$ref: >-
#/components/schemas/DigitalIdWalletApiMobileIdWalletVerificationStartRequest
multipart/form-data:
schema:
$ref: >-
#/components/schemas/DigitalIdWalletApiMobileIdWalletVerificationStartRequest
required: true
responses:
'201':
content:
application/json:
schema:
$ref: >-
#/components/schemas/DigitalIdWalletApiWalletVerificationResponse
example:
request_id: 00000000-0000-4000-8000-000000000001
wallet_verification:
wallet:
id: mobile_id
name: Mobile-ID
issuing_authority: SK ID Solutions with the national mobile operators
country: EST
status: Not Finished
outcome: pending
error: null
interaction: in_app
simulated: true
expires_at: '2026-01-01T10:10:00Z'
next_action:
type: confirm_in_app
verification_code: '1234'
poll_interval_seconds: 2
identity: null
attributes: null
level_of_assurance: null
verified_at: null
signature_valid: null
credential_type: person_identification
vendor_data: your-customer-reference
metadata:
reference: example
created_at: '2026-01-01T10:00:00Z'
description: ''
'400':
content:
application/json:
schema:
$ref: >-
#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest
description: >-
Field validation errors ({field: [messages]}), or error
return_url_invalid, return_url_not_allowed, invalid_personal_code,
invalid_phone_number or idempotency_key_invalid.
'403':
content:
application/json:
schema:
$ref: >-
#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden
description: >-
Missing or invalid credentials ({detail}), or error
wallet_unavailable, insufficient_credits or contract_rate_missing.
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/DigitalIdWalletApiWalletVerificationError'
description: >-
error idempotency_key_reused or idempotency_key_in_progress (with
Retry-After).
'502':
content:
application/json:
schema:
$ref: '#/components/schemas/DigitalIdWalletApiWalletVerificationError'
description: >-
error wallet_provider_unavailable: the provider could not start;
nothing was created.
'503':
content:
application/json:
schema:
$ref: '#/components/schemas/DigitalIdWalletApiWalletVerificationError'
description: >-
error wallet_not_configured: this environment cannot reach the
wallet.
security:
- ApiKeyAuth: []
- BearerAuth: []
x-codeSamples:
- lang: curl
label: cURL
source: |-
curl --request POST \
--url https://verification.didit.me/v3/id-verification/wallets/mobile-id/ \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Idempotency-Key: your-unique-attempt-key' \
--header 'Content-Type: application/json' \
--data '{
"country": "EST",
"vendor_data": "your-customer-reference",
"metadata": {
"reference": "example"
},
"personal_code": "00000000000",
"phone_number": "+37200000000"
}'
- lang: python
label: Python
source: |
import os
import requests
headers = {
"x-api-key": os.environ["DIDIT_API_KEY"],
"Idempotency-Key": "your-unique-attempt-key"
}
payload = {'country': 'EST',
'vendor_data': 'your-customer-reference',
'metadata': {'reference': 'example'},
'personal_code': '00000000000',
'phone_number': '+37200000000'}
response = requests.post(
"https://verification.didit.me/v3/id-verification/wallets/mobile-id/",
headers=headers,
json=payload,
timeout=30,
)
response.raise_for_status()
print(response.json())
components:
schemas:
DigitalIdWalletApiMobileIdWalletVerificationStartRequest:
type: object
description: Start a Mobile-ID verification (EST, LTU).
properties:
vendor_data:
type: string
nullable: true
description: >-
Your own reference for this verification (e.g. your user id).
Returned in results and webhooks.
metadata:
type: object
additionalProperties: {}
nullable: true
description: >-
Optional JSON object stored with the verification and returned in
results and webhooks.
sandbox_scenario:
type: string
minLength: 1
description: >-
Sandbox applications only: the simulated outcome -
'wallet_cancelled', 'wallet_timeout' or 'wallet_provider_error'; any
other scenario (or none) verifies. Rejected on live applications.
The full catalog is available at GET /v1/sandbox/scenarios/.
country:
allOf:
- $ref: >-
#/components/schemas/DigitalIdWalletApiMobileIdWalletVerificationStartCountryEnum
description: |-
ISO 3166-1 alpha-3 country of the Mobile-ID identity.
* `EST` - EST
* `LTU` - LTU
personal_code:
type: string
minLength: 1
description: >-
The user's national personal identification code. It addresses the
user's Mobile-ID app; the user confirms the comparison code and
enters their PIN in the app. Never collect the PIN.
pattern: ^[0-9-]{6,20}$
phone_number:
type: string
minLength: 1
description: The Mobile-ID phone number in E.164 format (+372... or +370...).
maxLength: 16
required:
- country
- personal_code
- phone_number
DigitalIdWalletApiWalletVerificationResponse:
type: object
description: One standalone wallet verification, as every wallet endpoint answers it.
properties:
request_id:
type: string
format: uuid
wallet_verification:
$ref: '#/components/schemas/DigitalIdWalletApiWalletVerificationResult'
vendor_data:
type: string
nullable: true
metadata:
type: object
additionalProperties: {}
nullable: true
description: The metadata object sent at start, or null.
created_at:
type: string
format: date-time
required:
- created_at
- metadata
- request_id
- vendor_data
- wallet_verification
DigitalIdWalletApiWalletVerificationStartBadRequest:
oneOf:
- $ref: '#/components/schemas/DigitalIdWalletApiWalletVerificationError'
- $ref: '#/components/schemas/DigitalIdWalletApiWalletVerificationFieldErrors'
DigitalIdWalletApiWalletVerificationStartForbidden:
oneOf:
- $ref: >-
#/components/schemas/DigitalIdWalletApiClientCredentialsForbiddenErrorMessage
- $ref: '#/components/schemas/DigitalIdWalletApiWalletVerificationError'
DigitalIdWalletApiWalletVerificationError:
type: object
properties:
error:
type: string
description: Stable machine-readable code, e.g. wallet_unavailable.
detail:
type: string
required:
- detail
- error
DigitalIdWalletApiMobileIdWalletVerificationStartCountryEnum:
enum:
- EST
- LTU
type: string
description: |-
* `EST` - EST
* `LTU` - LTU
DigitalIdWalletApiWalletVerificationResult:
type: object
properties:
wallet:
allOf:
- $ref: '#/components/schemas/DigitalIdWalletApiWallet'
readOnly: true
country:
type: string
status:
type: string
description: Not Finished while pending, then Approved (verified) or Declined.
outcome:
$ref: >-
#/components/schemas/DigitalIdWalletApiWalletVerificationResultOutcomeEnum
error:
type: string
nullable: true
readOnly: true
interaction:
allOf:
- $ref: '#/components/schemas/DigitalIdWalletApiInteractionEnum'
readOnly: true
simulated:
type: boolean
readOnly: true
expires_at:
type: string
format: date-time
next_action:
allOf:
- $ref: '#/components/schemas/DigitalIdWalletApiWalletNextAction'
nullable: true
readOnly: true
identity:
allOf:
- $ref: '#/components/schemas/DigitalIdWalletApiWalletIdentity'
nullable: true
readOnly: true
attributes:
type: object
additionalProperties: {}
nullable: true
readOnly: true
level_of_assurance:
type: string
nullable: true
verified_at:
type: string
format: date-time
nullable: true
signature_valid:
type: boolean
nullable: true
description: >-
True once the credential's signature was verified; null for a
simulated one.
credential_type:
type: string
nullable: true
required:
- attributes
- country
- credential_type
- error
- expires_at
- identity
- interaction
- level_of_assurance
- next_action
- outcome
- signature_valid
- simulated
- status
- verified_at
- wallet
DigitalIdWalletApiWalletVerificationFieldErrors:
type: object
description: 'Request validation errors: each rejected field with its messages.'
additionalProperties:
type: array
items:
type: string
DigitalIdWalletApiClientCredentialsForbiddenErrorMessage:
type: object
properties:
detail:
type: string
default: Forbidden - User doesn't have permission
DigitalIdWalletApiWallet:
type: object
properties:
id:
type: string
description: Catalog id of the wallet, e.g. bankid_se.
name:
type: string
issuing_authority:
type: string
nullable: true
required:
- id
- issuing_authority
- name
DigitalIdWalletApiWalletVerificationResultOutcomeEnum:
enum:
- pending
- verified
- cancelled
- timeout
- failed
type: string
description: |-
* `pending` - Pending
* `verified` - Verified
* `cancelled` - Cancelled by the user
* `timeout` - Timed out
* `failed` - Failed
DigitalIdWalletApiInteractionEnum:
enum:
- redirect
- in_app
type: string
description: |-
* `redirect` - redirect
* `in_app` - in_app
DigitalIdWalletApiWalletNextAction:
type: object
properties:
type:
allOf:
- $ref: '#/components/schemas/DigitalIdWalletApiWalletNextActionTypeEnum'
description: >-
redirect: send the user's browser to url. confirm_in_app: show
verification_code to the user, who checks it matches the code in
their wallet app and confirms there; then poll.
* `redirect` - redirect
* `confirm_in_app` - confirm_in_app
url:
type: string
format: uri
description: 'redirect only: where the user signs in with the wallet.'
verification_code:
type: string
description: >-
confirm_in_app only: the 4-digit comparison code the wallet app
shows too.
poll_interval_seconds:
type: integer
description: >-
confirm_in_app only: how often to call POST
.../verifications/{request_id}/poll/ for prompt feedback. Didit also
polls pending sign-ins in the background, so the webhook reports the
outcome even when you do not poll.
required:
- type
DigitalIdWalletApiWalletIdentity:
type: object
properties:
full_name:
type: string
nullable: true
first_name:
type: string
nullable: true
last_name:
type: string
nullable: true
date_of_birth:
type: string
format: date
nullable: true
nationality:
type: string
nullable: true
description: ISO3 nationality, only when the wallet asserts one (never inferred).
issuing_state:
type: string
description: ISO3 country whose scheme issued the identity.
required:
- date_of_birth
- first_name
- full_name
- issuing_state
- last_name
- nationality
DigitalIdWalletApiWalletNextActionTypeEnum:
enum:
- redirect
- confirm_in_app
type: string
description: |-
* `redirect` - redirect
* `confirm_in_app` - confirm_in_app
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: >-
Your application's API key, from Developers -> API keys in the Business
Console. The primary key has full access. A named key can be scoped:
none, read or write per resource, limited to some workflows or to
approved sessions, to a list of IP addresses, and to an expiry date. 401
means the key is missing, wrong, revoked or expired; 403 means the key
has no access to this resource or action, or the request came from an
address outside its IP list; 404 on a session route means the session is
outside the key's workflows or statuses. A key without media access
receives image, video and PDF URLs as null, and a key without sessions
write receives session links and tokens as null. See
https://docs.didit.me/console/api-keys.
BearerAuth:
type: http
scheme: bearer
description: The application's client-credentials access token.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.