Create a session

Starts a verification and returns the `url` to send the person to. A live key sets the tier's price aside, which is kept only if the session reaches a decision.

POST

/v1/verify/sessions

Starts a verification and returns the url to send the person to. A live key sets the tier's price aside, which is kept only if the session reaches a decision.

Authorization

apiKey

headerAuthorizationBearer <token>

Your API key, starting with upsky_test_ or upsky_live_.

Request Body

application/json

body

tier?string

age: selfie with liveness and an age estimate. identity: adds an ID, front and back, and a face match. identity_plus isn't available yet.

Default"identity"

Value in"age""identity""identity_plus"

reference?string

Your own ID for this person. Only your team sees it.

Length1 <= length <= 200

return_url?string

Where to send the person once they're done: a web page, or your app through its own scheme (myapp://verified) to bring them back from an in-app browser. The page goes there by itself a few seconds after they submit, or after the result when show_result is on, and also shows a button.

Lengthlength <= 2000

minimum_age?integer

Range13 <= value <= 25

Default18

allow_selfie_upload?boolean

Let the person send a selfie from their photos instead of taking it with the camera. Camera only by default. Live sessions always take the selfie with the camera, through the liveness check.

Defaultfalse

show_result?boolean

Show the person the result on the link right after they send it: approved, rejected or in review, never why. Off by default, so you tell them yourself.

Defaultfalse

expires_in?integer

Seconds the link works for, from an hour to seven days. A day by default.

Range3600 <= value <= 604800

Default86400

project_id?string

One of your team's projects, to group sessions by. The session uses the project's Verify settings where it has its own.

Formatuuid

options?

Anything this session should do differently from its project's Verify settings, or your team's. Leave a key out to keep the setting.

expected?

What you expect the ID to say. Names match whatever their accents, case or middle names. identity tier only. The result is in checks.data_match; by default a difference sends the session to review.

metadata?

Up to 20 keys of your own, returned as given.

Response Body

The new session.

application/json

response

id*string

Formatuuid

object*"verify.session"

Value in"verify.session"

livemode*boolean

tier*string

Value in"age""identity""identity_plus"

status*string

pending until the person opens the link, in_progress while they take photos, processing once submitted, then approved, rejected or needs_review. A link that's never finished ends expired or canceled, and isn't charged.

Value in"pending""in_progress""processing""approved""rejected""needs_review""expired""canceled"

url*|

The link to send the person to. Null once it can't be used anymore.

reference*string|null

metadata*

project_id*|

Formatuuid

return_url*string|null

minimum_age*integer

allow_selfie_upload*boolean

Whether the person may send a selfie from their photos. When false, it has to be taken with the camera on the page.

show_result*boolean

Whether the link shows the person the result once it's decided.

thresholds*

How sure each check had to be, copied when the session was created from its project's Verify settings, or your team's if the project has none. A score at or above a pass mark passes; from its review mark up to the pass mark goes to review; below the review mark is rejected.

options*

What the session runs by, copied when it was created from its project's Verify settings, or your team's, with anything you set in the request on top.

reasons*array<>

Why the session ended as it did.

checks*

What each check found. Empty until the session is decided.

document_type*|

Value in"mx_ine""passport""us_drivers_license""id_card"null

verified_outputs*|

What was read from the ID. Identity tier and above, once decided. Only returned when you read one session, never in lists or webhooks.

expires_at*string

created_at*string

started_at*string|null

submitted_at*string|null

decided_at*string|null

reviewed_at*string|null

redacted_at*|

When the person's data was deleted from the session with the redact endpoint.

Example Request

curl -X POST 'https://api.upsky.dev/v1/verify/sessions' \
  -H 'Content-Type: application/json' \
  -d '{}'

Example Request

curl -X POST 'https://api.upsky.dev/v1/verify/sessions' \  -H 'Content-Type: application/json' \  -d '{}'

Example ResponseSchema

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "object": "verify.session",
  "livemode": true,
  "tier": "age",
  "status": "pending",
  "url": "string",
  "reference": "string",
  "metadata": {
    "property1": "string",
    "property2": "string"
  },
  "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",
  "return_url": "string",
  "minimum_age": 0,
  "allow_selfie_upload": true,
  "show_result": true,
  "thresholds": {
    "preset": "relaxed",
    "liveness_pass": 0,
    "liveness_review": 0,
    "face_match_pass": 0,
    "face_match_review": 0,
    "age_buffer_years": 0
  },
  "options": {
    "documents": {
      "allowed_types": [
        "mx_ine"
      ],
      "allowed_countries": [
        "string"
      ],
      "max_attempts": 0
    },
    "rules": {
      "liveness_inconclusive": "reject",
      "age_inconclusive": "reject",
      "document_unreadable": "reject",
      "document_expired": "reject",
      "document_checksum_failed": "reject",
      "document_type_mismatch": "reject",
      "document_country_not_accepted": "reject",
      "date_of_birth_missing": "reject",
      "face_match_inconclusive": "reject",
      "age_estimate_mismatch": "reject",
      "name_mismatch": "reject",
      "date_of_birth_mismatch": "reject"
    },
    "retention_days": 0
  },
  "reasons": [
    "liveness_failed"
  ],
  "checks": {
    "liveness": {
      "status": "passed",
      "confidence": 0,
      "feedback": [
        "face_not_visible"
      ]
    },
    "age": {
      "status": "passed",
      "minimum_age": 0,
      "estimated_low": 0,
      "estimated_high": 0,
      "estimated_age": 0,
      "age_from_document": 0
    },
    "document": {
      "status": "passed",
      "document_type": "mx_ine",
      "expired": true,
      "checksums_valid": true,
      "type_matches": true,
      "country_accepted": true
    },
    "face_match": {
      "status": "passed",
      "similarity": 0
    },
    "data_match": {
      "status": "passed",
      "first_name": "match",
      "last_name": "match",
      "date_of_birth": "match"
    }
  },
  "document_type": "mx_ine",
  "verified_outputs": {
    "first_name": "string",
    "last_name": "string",
    "date_of_birth": "string",
    "document_type": "mx_ine",
    "document_number": "string",
    "issuing_country": "string",
    "expires_on": "string"
  },
  "expires_at": "string",
  "created_at": "string",
  "started_at": "string",
  "submitted_at": "string",
  "decided_at": "string",
  "reviewed_at": "string",
  "redacted_at": "string"
}

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "object": "verify.session",  "livemode": true,  "tier": "age",  "status": "pending",  "url": "string",  "reference": "string",  "metadata": {    "property1": "string",    "property2": "string"  },  "project_id": "405d8375-3514-403b-8c43-83ae74cfe0e9",  "return_url": "string",  "minimum_age": 0,  "allow_selfie_upload": true,  "show_result": true,  "thresholds": {    "preset": "relaxed",    "liveness_pass": 0,    "liveness_review": 0,    "face_match_pass": 0,    "face_match_review": 0,    "age_buffer_years": 0  },  "options": {    "documents": {      "allowed_types": [        "mx_ine"      ],      "allowed_countries": [        "string"      ],      "max_attempts": 0    },    "rules": {      "liveness_inconclusive": "reject",      "age_inconclusive": "reject",      "document_unreadable": "reject",      "document_expired": "reject",      "document_checksum_failed": "reject",      "document_type_mismatch": "reject",      "document_country_not_accepted": "reject",      "date_of_birth_missing": "reject",      "face_match_inconclusive": "reject",      "age_estimate_mismatch": "reject",      "name_mismatch": "reject",      "date_of_birth_mismatch": "reject"    },    "retention_days": 0  },  "reasons": [    "liveness_failed"  ],  "checks": {    "liveness": {      "status": "passed",      "confidence": 0,      "feedback": [        "face_not_visible"      ]    },    "age": {      "status": "passed",      "minimum_age": 0,      "estimated_low": 0,      "estimated_high": 0,      "estimated_age": 0,      "age_from_document": 0    },    "document": {      "status": "passed",      "document_type": "mx_ine",      "expired": true,      "checksums_valid": true,      "type_matches": true,      "country_accepted": true    },    "face_match": {      "status": "passed",      "similarity": 0    },    "data_match": {      "status": "passed",      "first_name": "match",      "last_name": "match",      "date_of_birth": "match"    }  },  "document_type": "mx_ine",  "verified_outputs": {    "first_name": "string",    "last_name": "string",    "date_of_birth": "string",    "document_type": "mx_ine",    "document_number": "string",    "issuing_country": "string",    "expires_on": "string"  },  "expires_at": "string",  "created_at": "string",  "started_at": "string",  "submitted_at": "string",  "decided_at": "string",  "reviewed_at": "string",  "redacted_at": "string"}

AuthorizationCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

Authorization

Request Body

Response Body