Docs

# 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

  • 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 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".
  • 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

# 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_ABANDONED/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

  • 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",
          },
      }
  }

← Webhook →