A session is one verification attempt for one applicant.
link Statuses
| Status | Means | Ends the session |
|---|---|---|
created | The link exists. Your customer hasn't opened it yet. | No |
handed_off | They've opened it, and moved to their phone if they started on a computer. | No |
capturing | They've agreed to the check and are taking photos. | No |
submitted | Everything is uploaded and waiting to be checked. | No |
processing | Our checks are running. | No |
clear | Verified. The checks found nothing wrong. | Yes |
consider | Something needs a person to look at it. See the reasons. Your team's review makes it clear or rejected, and you get session.completed. | Until reviewed |
rejected | Not verified. The checks found a clear problem. | Yes |
expired | Not finished within 24 hours. | Yes |
cancelled | You cancelled it. | Yes |
error | The checks failed for a technical reason after every retry. It says nothing about your customer; we run the checks again. | Until rerun |
link References
Every session has your reference for the customer, such as a user or account ID. Use the same reference each time the same customer verifies: their sessions are grouped under it in the dashboard, so you can see every attempt they've made. A reference has at most one session that hasn't finished: creating another returns that one, with a new link.
Don't put names, email addresses or anything personal in the reference. Your own internal ID is all we need, and it keeps personal details out of our records.
link Expiry
A session's link works for 24 hours from when you create it (expires_at). After that the session becomes expired and the link stops working. Create a new session if your customer comes back later.
link Retries inside a session
If a photo isn't good enough, your customer can take it again, a few times, without starting over. Only the latest attempt counts. If they run out of attempts, create a new session.
link Cancelling
Cancel a session that hasn't finished, for example if the customer closes their account. Its link stops working at once. Sessions that have already ended can't be cancelled.
link Bringing customers back
Set redirect_url when you create a session and your customer gets a button back to your app when they finish. Don't treat arriving at that URL as proof of anything: anyone can open it. Always read the session from the API, or wait for the webhook.