API reference

Sessions

The v3 Sessions API.

#Create a session

POST/v3/session/

Field	Type	Description
`workflow_id`	string	The workflow to run. Uses your default workflow if left out
`vendor_data`	string	Your user ID. Links sessions to a user
`callback`	string	Where to send the user when they finish
`metadata`	object	Your own data, returned in webhooks. Workflow conditions can read `metadata.<key>`
`contact_details`	object	`email`, `phone`
`expected_details`	object	`first_name`, `last_name`, `date_of_birth`, `nationality` to compare with the document
`send_email`	boolean	Email the link to `contact_details.email`
`ongoing_aml`	boolean	Keep screening this user after approval
`type`	string	`authentication` for biometric re-authentication
`flash_check`	boolean	Add the colour-flash liveness check

bash

curl -X POST https://{{HOST}}/v3/session/ -H "x-api-key: sk_test_..." -H "Content-Type: application/json" \
  -d '{"workflow_id":"wf_...","vendor_data":"user-123","callback":"https://yourapp.com/done","metadata":{"plan":"gold"}}'

Returns 201:

json

{ "session_id": "ver_...", "session_number": 1042, "session_token": "vs_...", "url": "https://{{HOST}}/verify/?token=vs_...", "status": "Not Started" }

#Get a session

GET/v3/session/{id}/Summary and status

#Get the decision

GET/v3/session/{id}/decision/

Returns status, risk_score, features[] and an array per check type. Each item has a node_id and its own status: id_verifications[], liveness_checks[], face_matches[], aml_screenings[], poa_verifications[], database_validations[], ip_analyses[], biometric_authentications[], questionnaires[], plus list_matches, reviews[] and workflow_path. Image URLs are signed and expire after 60 minutes.

#List sessions

GET/v3/sessions/?status=Approved&vendor_data=&workflow_id=&limit=&offset=

#Update the status

PATCH/v3/session/{id}/update-status/

Field	Description
`new_status`	`Approved`, `Declined` or `Resubmitted`
`comment`	Note for the audit log
`nodes_to_resubmit`	For `Resubmitted`: such as `["liveness_1","id_verification_1","face_match_1","poa_1"]`. Returns a fresh `url`

#Decision PDF

GET/v3/session/{id}/generate-pdf

#Session media

GET/v3/media/{fid}Signed image URLs in decisions point here

#Delete

DELETE/v3/session/{id}/delete/Erase one session and its files

POST/v3/sessions/delete/{session_ids: [...]}