API Deprecations

We try our best to make Flow as stable and predictable as all of our products. Flow is still in beta though, and sometimes this means we will need to change parts of the API for the sake of clarity, consistency, and compatibility with new features.

When we make changes to Flow's public API during the beta, we will notify you if a breaking change is planned. For each breaking change, we will try our best to provide a 4 week compatibility window for you to update your code without disturbing your integration.

This section of the guide covers "ongoing deprecations." In other words, if you're seeing this section of the guide, a deprecation is in progress. For each deprecation, we provide the following details:

  • Soft deprecation date – the date the change we announced the change and introduced a non-breaking change to our API
  • Hard deprecation date - the future date for when we will remove the deprecate behavior
  • Change description - an overview of what behavior specifically is being removed and what the new behavior is

Renaming "inputs" to "user"

  • Soft deprecation date: August 27th, 2021
  • Hard deprecation date: September 24th, 2021

For every response under the /flow_sessions API route, we currently return a response body like this:

{
  "id": "flwses_52xR9LKo77r1Np",
  "customer_reference": "your-db-id-3b24110",

  // Truncated for brevity

  "inputs": {
    "phone": "+19876543212",
    "date_of_birth": "1975-01-18",

    // Truncated for brevity
  }
}

We are changing the name of the inputs key to user to match the structure used in Flow's JS client as well as the JSON structure provided to POST /flow_sessions. The change will look like this:

{
  "id": "flwses_52xR9LKo77r1Np",
  "customer_reference": "your-db-id-3b24110",

  // Truncated for brevity

  "user": {
    "phone": "+19876543212",
    "date_of_birth": "1975-01-18",
    
    // Truncated for brevity
  }
}

During the soft deprecation window, we will return both inputs and user from the API.

Renaming "identity_document" to "id_number"

  • Soft deprecation date: August 27th, 2021
  • Hard deprecation date: September 24th, 2021

Within the Flow Session response bodies, we expose ID number data collected under the identity_document. For example, consider this response body:

{
  "id": "flwses_52xR9LKo77r1Np",
  "customer_reference": "your-db-id-3b24110",
  
  // Truncated for brevity

  "inputs": {
    "phone": "+19876543212",
    "country_code": "CA",

    // Truncated for brevity

    "identity_document": {
      "value": "123456789",
      "type": "tax_id"
    }
  }
}

To avoid confusion with the documents data from the documentary_verification step, we are renaming this field to id_number. We are also changing the schema of the id_number body, so see the following section for an example of the new structure.

During the soft deprecation window, we will continue to return inputs.identity_document field with the exact same schema as before the deprecation. Under the new user response field, we will expose the id_number field using the new schema.

Renaming "id_number.type" to "id_number.category" and adding a new id_number.type

  • Soft deprecation date: August 27th, 2021
  • Hard deprecation date: September 24th, 2021

Flow's lightning verification currently supports 34 different ID number types from 31 different countries. Currently, we return a type field with each ID number with the following possible values:

  • personal_identification
  • tax_id
  • ssn
  • ssn_last4
  • drivers_license
  • internal_passport
  • passport
  • voter_id

We are renaming this type field to category and introducing a new enum value for id_number.type. Each enum value is globally unique, human readable, and scoped to the ID's issuing country. You can see a full table of these values in the Flow Hybrid Input Validation guide.

The new response format for id_number will look like this:

{
  "id": "flwses_52xR9LKo77r1Np",
  "customer_reference": "your-db-id-3b24110",
  
  // Truncated for brevity

  "user": {
    "phone": "+19876543212",
    "country_code": "CA",

    // Truncated for brevity

    "id_number": {
      "value": "123456789",
      "category": "tax_id",
      "type": "ca_sin"
    }
  }
}

Soft deprecation format

During the soft deprecation, we will serve Flow Sessions responses like so:

{
  "id": "flwses_52xR9LKo77r1Np",
  "customer_reference": "your-db-id-3b24110",
  "created_at": "2020-07-24T03:26:02Z",
  "completed_at": "2020-07-24T03:26:02Z",
  "previous_session_id": "flwses_42cF1MNo42r9Xj",
  "shareable_url": "https://flow.cognitohq.com/verify/flwtmp_4FrXJvfQU3zGUR?key=e004115db797f7cc3083bff3167cba30644ef630fb46f5b086cde6cc3b86a36f",
  "template": {
    "id": "flwtmp_4FrXJvfQU3zGUR",
    "version": 2
  },

  // The schema under `inputs` will remain unchanged until it is removed
  "inputs": {
    "phone": "+19876543212",
    "date_of_birth": "1975-01-18",
    "email": "user@example.com",
    "name": {
      "first": "Leslie",
      "last": "Knope"
    },
    "address": {
      "street": "123 Main St.",
      "street2": "Unit 42",
      "city": "Pawnee",
      "subdivision": "IN",
      "postal_code": "46001",
      "country_code": "US"
    },
    // Note that `identity_document` has not changed within this section
    "identity_document": {
      "value": "123456789",
      "type": "ssn"
    }
  },

  // The `user` section will replace `inputs`. It contains the updated schema changes
  "user": {
    "phone": "+19876543212",
    "date_of_birth": "1975-01-18",
    "email": "user@example.com",
    "name": {
      "first": "Leslie",
      "last": "Knope"
    },
    "address": {
      "street": "123 Main St.",
      "street2": "Unit 42",
      "city": "Pawnee",
      "subdivision": "IN",
      "postal_code": "46001",
      "country_code": "US"
    },
    // `identity_document` is removed in this section and is replaced with `id_number`
    "id_number": {
      "value": "123456789",

      // The old `type` enum has been renamed to `category`
      "category": "tax_id",

      // The `type` value now corresponds to a globally unique identifier
      "type": "us_ssn",
    }
  },

  "status": "success",
  "steps": {
    "accept_tos": "success",
    "verify_sms": "success",
    "kyc_screen": "not_applicable",
    "kyc_check": "active",
    "documentary_verification": "waiting_for_prerequisite",
    "selfie_check": "waiting_for_prerequisite",
    "screening": "waiting_for_prerequisite",
    "risk_check": "waiting_for_prerequisite"
  },
  "documentary_verification": {
    "status": "success",
    "documents": [
      {
        "status": "success",
        "images": {
          "original_front": "https://example.cognitohq.com/flow_sessions/flwses_52xR9LKo77r1Np/documents/1/orignial_front.jpeg",
          "original_back": "https://example.cognitohq.com/flow_sessions/flwses_52xR9LKo77r1Np/documents/1/original_back.jpeg",
          "cropped_front": "https://example.cognitohq.com/flow_sessions/flwses_52xR9LKo77r1Np/documents/1/cropped_front.jpeg",
          "cropped_back": "https://example.cognitohq.com/flow_sessions/flwses_52xR9LKo77r1Np/documents/1/cropped_back.jpeg",
          "face": "https://example.cognitohq.com/flow_sessions/flwses_52xR9LKo77r1Np/documents/1/face.jpeg"
        }
      }
    ]
  },
  "screening_id": "scr_52xR9LKo77r1Np",
  "_meta": "This API format is not v1.0 and is subject to change."
}