# REST API
The read API endpoints in the Caisson REST API. If you're looking to build a custom integration with the write or create API's, contact us, we're here to help!
# Exchange Check Token for Check ID
A check_exchange_token
is returned when a new ID Check is created using the Javascript Button API. You must exchange that token for a permanent check_id
that you can use to fetch the ID Check result and receive webhook notifications. Store the check_id
with your user’s record.
NOTE: You must exchange the token within 2 hours of the ID Check creation. Once exchanged, the token will live for 5 minutes to allow for retries in case of failure. After that grace period, the exchange token will expire.
# POST /v1/idcheck/exchangetoken
# Required Headers
Authorization:
Caisson <your_secret_api_key>
# JSON Request Body
check_exchange_token
: The exchange token returned from the Javascript Button’sidCheckCreated
event.
# JSON Response Body
check_id
: A unique identifier of the ID Check. This identifier will be used when we notify your application of completion through a webhook, and by your server to fetch the result of the associated user’s ID Check.
# Error Handling
The following fields will be returned in case of error. Absence of error
in the response means successful completion.
error
: Error code as a string. Possbile values:INTERNAL_ERROR
,INVALID_INPUT
.error_description
: String describing the error.
POST https://api.caisson.com/v1/idcheck/exchangetoken
Request (application/json)
Headers
Authorization: Caisson <your_secret_api_key>
Body
{ "check_exchange_token": "chk_xchg_UeRXDryTTpvU24CTre8W2Q" }
Response 200 (application/json)
+ Body { "check_id": "chk_priv_ceSB3MdzNm8M5FdEM4wSXw", }
# Get an ID Check Result
Returns the result of an ID Check.
# GET /v1/idcheck
# Required Headers
Authorization:
Caisson <your_secret_api_key>
X-Caisson-CheckID:
<check_id>
The check_id you'd like to query
Note: The check_id
is passed in X-Caisson-CheckID
rather than a query parameter for security reasons.
# Query paramter:
fields
(Optional): The response always includesfirst_name
andlast_name
, but you may also request the following additional fields as a comma seperated list:sex
,dob
,address
,expires_on
.
# JSON Response Body
check_id
: An identifier of the ID Checkcustomer_id
: Your ID as provided when creating the ID Checkchecked_on
: UTC timestamp of when the ID Check took placeconfidence
:document
: An overall ranking of the match between the front and the back of the license. Possible values are"high"
,"medium"
,"low"
:face
: A ranking of the match between the photo on the document and the user’s selfie. Possible values are are"high"
,"medium"
,"low"
.reasons
: An array of reasons for the confidence, if the confidence was not high. See Confidence Reasons below
info
last_name
: last namefirst_name
: first namesex
: sex - optional if requested in thefields
query parameterdob
: date of birth - ISO Date string - optional if requested in thefields
query paramterexpires_on
: Document expiration date - ISO Date string - optional if requested in thefields
query parameteraddress
: address if requested in thefields
query parameterstreet
: street address, including house number / apartment number (typically called address 1 and and address 2)city
: citystate
: statezip
: zipcode
# Confidence Reasons
When the confidence in the accuracy of the document or the face are not high, we provide an array of reasons why we didn't score it high. The reasons array is in the format { "code": <number>, "description": <string> }
. Possible reasons are:
Data mismatch between encoded and printed data:
101
Name mismatch102
Date of birth mismatch104
ID number mismatch105
Sex mismatch106
Address mismatch
Selfie related reasons:
201
: The selfie was not positioned properly (e.g. only showing part of the face, face is too close/far).202
: Face could not be detected in the uploaded selfie.299
: An error occurred while processing the selfie image.
Document front image related reasons:
301
: The face detected on the document was not properly positioned (e.g. face too small, to large or partial).302
: Face could not be detected in the uploaded document.303
: Some data is missing in from the document (e.g. address was expected but could not be detected).304
: Document is not supported.305
: Passports only The encoded data on the passport is invalid.306
: Passports only Could not detect the passport's encoded data.307
: Could not detect document in the uploaded image.308
: The document expired.309
: The document is not fully in the frame.399
: An error occurred while processing the document.
Barcode related reasons:
401
The encoded data on the barcode is invalid.402
Could not detect barcode.499
An error occurred while processing the barcode.
# Error Handling
The following fields will be returned in case of error. Absence of error
in the response means successful completion.
error
: Error code as a string. Possbile values:IDCHECK_EXPIRED
,IDCHECK_DELETED
,INVALID_INPUT
,NOT_VERIFIED
,PENDING_REVIEW
,INTERNAL_ERROR
.error_description
: String describing the error.
GET https://api.caisson.com/v1/idcheck?fields=sex,dob,address,expires_on
Parameters
- fields (optional, string) - comma-separated list of optional fields to return
Request
Headers
Authorization: Caisson <your_secret_api_key> X-Caisson-CheckID: chk_priv_SMgso2KGzXLxT2I-g7oD2w
Response 200 (application/json)
+ Body { "check_id": "chk_priv_SMgso2KGzXLxT2I-g7oD2w", "customer_id": "1234321 - Doe, Jamie", "checked_on": "2019-07-19T15:00:42.274684-04:00", "confidence": { "document": "high", "face": "high" }, "info": { "last_name": "DOE", "first_name": "JAMIE", "sex": "M", "dob": "1989-06-30T00:00:00Z", "expires_on": "2025-06-24T00:00:00Z", "address": { "street": "6 CROWN DR # 11B", "city": "NEW YORK", "state": "NY", "zip": "10001", }, } }
← React Native Webhook →