# 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’s idCheckCreated 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

# 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 includes first_name and last_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 Check
• customer_id: Your ID as provided when creating the ID Check
• checked_on: UTC timestamp of when the ID Check took place
• confidence:
  • 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 name
  • first_name: first name
  • sex: sex - optional if requested in the fields query parameter
  • dob: date of birth - ISO Date string - optional if requested in the fields query paramter
  • expires_on: Document expiration date - ISO Date string - optional if requested in the fields query parameter
  • address: address if requested in the fields query parameter
    • street: street address, including house number / apartment number (typically called address 1 and and address 2)
    • city: city
    • state: state
    • zip: 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 mismatch

  • 102 Date of birth mismatch

  • 104 ID number mismatch

  • 105 Sex mismatch

  • 106 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, 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