Skip to main content

Async callback responses

Informed will POST the relevant asynchronous callback responses to the webhook that you specify.  If your webhook does not respond with a 2xx (success), Informed will re-submit the request to your endpoint up to 5 times using a delay strategy.

info

Informed will retry as mentioned above if your endpoint returns a 429, 500, 502, 503 or 504 status.

The key attributes of your callback endpoint are shown below:

  • Your endpoint must support the HTTPS protocol, with a valid certificate.
  • Your endpoint should return a 200 response status upon receiving the callback payload.
  • If your endpoint returns any body in the success response, it must be json-formatted.
  • If you have authentication configured on your endpoint (recommended), you must provide that information to Informed.
  • If you need to whitelist any IP addresses on your side for the callback, you can find those here.

Process Flow​

Please reference the full sequence diagram.

Callback types​

All callbacks will have an event_type node that specifies what type of callback it is. The event types are as follows:

  • extractions
  • verifications
  • error

The sections below provide more detail on the contents of the various callbacks.

Extractions Callbacks​

The extraction service provides the extracted data from the document types found in a submitted image file. Bear in mind that Informed can separate out multiple documents from a single PDF or TIFF file. At the present time, you will receive one extraction callback per original file submitted (provided you specify the extract service when registering the application).

tip

While you will only receive one extraction callback per original file submitted, if that single file contains multiple documents of different types, you can expect to receive a response containing multiple classified documents and the associated extracted data (see the example below).

In the example callback payload below, there are a couple things to note:

  • The application_id will be the same one provided in the synchronous response to the original application registration.
  • The application_reference_id will be the same reference id that you provided when you registered the application.
  • The documents object will contain keys for each document classification type encountered in the file.
  • Each of those document types will contain a list of the documents of that type found in the file.
  • Every individual derived document identified will receive a unique document_id.
  • Every individual derived document will also contain a reference to the original file_ids (from the synchronous response) and file_reference_ids (the file name you assigned at the time of upload).
  • The url provided for each derived document is a time-bound, pre-signed S3 URL, which you can use via a GET call to retrieve the indexed document image.
  • Details about what items are extracted (in extracted_data) for a given document type can be found in the here.
danger

There is no guarantee that the file download URL's (typically AWS S3 pre-signed URL's) will remain exactly the same for all future time. Informed reserves the right to use whatever infrastructure is most secure and efficient.

If you are trying to whitelist the download URL's, at the current time, as Amazon AWS pre-signed URL's, they will have a base domain of amazonaws.com, so the most restrictive that you should make your whitelist is *.amazonaws.com.

Extractions Callback Structure
{
  "event_type": "extractions",
  "application_id": "unique-Informed-app-id",
  "application_reference_id": "partner application id",
  "documents": {
    "document_type_id": [
      {
        "data_action": "create",
        "document_id": "a65ec788-d68e-4827-9bdd-70f1ede3bca7",
        "file_ids": [
          "c988a854-0425-4920-a241-605661daa87e"
        ],
        "file_reference_ids": [
          "your-submitted-file-name.pdf"
        ],
        "url": "https://informed-techno-core-<env>-downloads.s3.amazonaws.com/123...",
        "extracted_data": {
          "applicants": {
            "applicant1": {
              "address": {
                "street_address": "8717 S 4th Ave",
                "street_2": null,
                "city": "Inglewood",
                "state": "CA",
                "zip": "90305"
              },
              "first_name": "Jo",
              "middle_name": null,
              "last_name": "Boren",
              "suffix": null,
              "ssn": "3906"
            }
          },
          ...
        },
        "updated_at": "2023-09-18T17:59:18Z"
      }
    ]
  }
}

Full Extractions Schema​

View extended example of extractions schema for all major document types.

Verifications Callbacks​

The verification service provides the analysis of the specified verifications based on the extracted data from the document types found in the aggregate of the submitted image files.

If you only want the verification analysis, then you would simply specify the verify service at time of application registration, but most likely, you will also want the extracted data, which means that you will want to specify the extract service in addition to the verify service.

Unlike the extractions service, for which we can predict one callback per original submitted file, it is not as straight forward for the verification callbacks. The number of verification callbacks will depend on several factors, such as the time gap between uploading the original files and the size and complexity of the uploaded files. The important thing to remember is that the verification callbacks will always represent the aggregate analysis across all associated documents available at the time the verifications are run.

tip

In order to help eliminate any confusion in the case of multiple verifications callbacks, we have added the data_sources element, which specifies the uploaded files and structured data that were available/present at the time of generating that specific verifications response. This element will also allow you to track that all previously uploaded documents for an application have been analyzed.

In the example callback payload below, there are a couple things to note:

  • The application_id will be the same one provided in the synchronous response to the original application registration.
  • The application_reference_id will be the same reference id that you provided when you registered the application.
  • If you included an application_update_reference_id in the application update PUT request that is generating the verifications response, then that key/value pair will be returned in your verifications response.
  • The verifications object will contain keys for each requested verification type for the application.
  • Each of those verification types will contain a list of the verifications based on how many belongs_to were specified. For example, if you stipped both applicant1 and applicant2 for income, then there would be two objects in the list for the income key inside verifications.

Because verifcations are somewhat involved themselves, we'll separate out some important points about them here:

  • The overall verification status options are pass, fail, missing or review.
  • The belongs_to node indicates which applicant (or the application overall) this verification applies to.
  • The updated_at node provides a timestamp for the last update to this verification.
  • The description is a more "human-friendly" narrative of the current condition of the verification.
  • More complex verifications, like income, will have a verification_questions section with overarching questions pertaining to determining its overall status.
  • The acceptable_documents object breaks down the document or documents that were used to satisfy the verification.

Acceptable documents for clearing a verification have a structure designed to identify both the document itself, as well as details about the questions used to determine its impact on the overall verification status.

  • The document will have its unique document_id present so you can reference it back to the extractions callback.
  • Each document will also contain a reference to the original file_ids (from the synchronous response) and file_reference_ids (the file name you assigned at the time of upload).
  • The category node identifies the document grouping.
  • The heart and soul of the this section though, are the document_questions. This is what ultimately will determine the overall verification status. The document questions will vary by document type and can be modified to align with your verification needs.
Verifications Callback Structure
{
  "event_type": "verifications",
  "application_id": "unique-Informed-app-id",
  "application_reference_id": "partner application id",
  "application_update_reference_id": "your_unique_update_identifier",
  "data_sources": {
    "image_files": [
      {
        "file_id": "38d03f0e-215a-4b03-8fb5-bb2f089f67db",
        "file_reference_id": "your-submitted-file-name.pdf"
      },
      {
        "file_id": "efef2d00-59e2-446d-8279-1cacf607ea35",
        "file_reference_id": "your-submitted-file-name-2.pdf"
      },
      ...
    ],
    "structured_data": [
      {
        "document_id": "85a8e2ee-453b-4769-8d42-25b3ae40be11",
        "document_reference_id": "your_unique_reference_for_this_edoc"
      },
      ...
    ]
  },
  "verifications": {
    "verification_name": [
      {
        "status": "fail",
        "belongs_to": "applicant1",
        "updated_at": "2023-09-18 18:02:17 +0000",
        "description": "The applicant's income is in-line with what s/he stated. ...",
        "verification_questions": {
          "poi_income_from_employer": {
            "question": "What is the income from the employer?",
            "expected": "",
            "answer": "$xx,xxx.xx",
            "status": "pass"
          },
          "poi_income_from_second_employer": {
            "question": "What is the income from the second employer?",
            "expected": "",
            "answer": "$20,596.80",
            "status": "pass"
          },
          ...
        },
        "acceptable_documents": {
          "paystub": [
            {
              "document_id": "32f3be93-e771-4677-8471-f81ad4a932d6",
              "file_ids": [
                "38d03f0e-215a-4b03-8fb5-bb2f089f67db"
              ],
              "file_reference_ids": [
                "your-submitted-file-name.pdf"
              ],
              "category": "Current Paystub",
              "document_questions": {
                "matches_applicant_name": {
                  "question": "Matches the applicant's name?",
                  "expected": "Jo Boren",
                  "answer": "Jo Boren",
                  "status": "pass"
                },
                "is_issued_recently": {
                  "question": "Issued within 60 days of the contract date?",
                  "expected": ">=03/10/2021",
                  "answer": "04/04/2021",
                  "status": "pass"
                },
                "working_days_elapsed": {
                  "question": "Working days elapsed?",
                  "expected": "",
                  "answer": 86,
                  "status": "pass"
                },
                "matches_employer_name": {
                  "question": "Matches the applicant's employer's name?",
                  "expected": "American Airlines",
                  "answer": "American Airlines",
                  "status": "pass"
                },
                ...
              }
            }
          ],
        },
        "recommendations": [
          "Jo Boren's Military LES must be issued within 60 days of the contract date.",
          "Jo Boren's SSI Award Letter must be issued within 365 days of the contract date."
        ]
      },
      {
        "status": "fail",
        "belongs_to": "applicant2",
        "updated_at": "2023-09-18 18:02:17 +0000",
        "description": "True The applicant's income is in-line with what s/he stated...",
        "verification_questions": {
          "poi_income_from_employer": {
            "question": "What is the income from the employer?",
            "expected": "",
            "answer": "$xx,xxx.xx",
            "status": "pass"
          },
          "poi_income_from_second_employer": {
            "question": "What is the income from the second employer?",
            "expected": "",
            "answer": "$20,596.80",
            "status": "pass"
          },
          ...
        },
        "acceptable_documents": {
          "bank_statement": [
            {
              "document_id": "9615152f-85af-4350-9591-bef161623642",
              "file_ids": [
                "efef2d00-59e2-446d-8279-1cacf607ea35"
              ],
              "file_reference_ids": [
                "your-submitted-file-name-2.pdf"
              ],
              "category": "Bank Statement(s) From Last Month",
              "document_questions": {
                "matches_applicant_name": {
                  "question": "Matches the applicant's name?",
                  "expected": "Jo Boren",
                  "answer": "Jo Boren",
                  "status": "pass"
                },
                "is_issued_recently": {
                  "question": "Issued within 120 days of the contract date?",
                  "expected": ">=01/09/2021",
                  "answer": "03/31/2021",
                  "status": "pass"
                },
                "has_excessive_overdrafts": {
                  "question": "Excessive overdrafts?",
                  "expected": "<=1000",
                  "answer": "0.0",
                  "status": "pass"
                },
                "salient_deposits": {
                  "question": "What are the salient deposits from last month?",
                  "expected": "",
                  "answer": "$5,880.59",
                  "status": "pass"
                }
              }
            },
            ...
          ],
          ...
        },
        "recommendations": [
          "Lucinda Bonadio's Bank Statement(s) From Last Month must be issued within 120 days of the contract date.",
          "Lucinda Bonadio must supply required number of consecutive Bank Statements."
        ]
      }
    ],
    ...
  }
}

Full Verifications Schema​

View extended example of verifications schema for all the verifications with their major supporting document types.

Error Callbacks​

If something goes wrong during the processing of the application such that a normal asynchronous callback cannot be returned, Informed will return an asynchronous error callback.

caution

These error callbacks should not be confused with the aspect of Informed pointing out stipulation defects in submitted documents. Any and all stipulation defects identified during analysis will be present in the valid verifications callback response.

Physical image defects​

If you were to upload a corrupted file, password-protected file or non-image file (e.g., .txt file), then you should expect to receive an asynchronous callback response similar to the examples below, instead of the normal extractions response.

Generic issues​

{
  "event_type": "error",
  "application_id": "unique-Informed-app-id",
  "application_reference_id": "partner application id",
  "error_message": "unable to process this file",
  "file_id": "unique-Informed-file-id",
  "file_reference_id": "partner file name or id",
  "webhook_url": "https://your.callback.com/here"
}
{
  "event_type": "error",
  "application_id": "unique-Informed-app-id",
  "application_reference_id": "partner application id",
  "error_message": "The file type is invalid. The valid file types are .pdf, .tiff, .jpeg, .jpg, .png.",
  "file_id": "unique-Informed-file-id",
  "file_reference_id": "partner file name or id",
  "webhook_url": "https://your.callback.com/here"
}

Corrupted file​

{
  "event_type": "error",
  "application_id": "unique-Informed-app-id",
  "application_reference_id": "partner application id",
  "error_message": "identify: no decode delegate for this image format `' @ error/constitute",
  "file_id": "unique-Informed-file-id",
  "file_reference_id": "partner file name or id",
  "webhook_url": "https://your.callback.com/here"
}

Password-protected file​

{
  "event_type": "error",
  "application_id": "unique-Informed-app-id",
  "application_reference_id": "partner application id",
  "error_message": "**** This file requires a password for access",
  "file_id": "unique-Informed-file-id",
  "file_reference_id": "partner file name or id",
  "webhook_url": "https://your.callback.com/here"
}

Physical image dimensions​

If you were to upload a file with dimensions of less than 100x100 pixels, then you should expect to receive an asynchronous callback response like the one below, instead of the normal extractions response.

{
  "event_type": "error",
  "application_id": "unique-Informed-app-id",
  "application_reference_id": "partner application id",
  "error_message": "The image dimension is invalid.",
  "file_id": "unique-Informed-file-id",
  "file_reference_id": "partner file name or id",
  "webhook_url": "https://your.callback.com/here"
}

Physical image size​

If you were to upload a file over 80 MB in size, then you should expect to receive an asynchronous callback response like the one below, instead of the normal extractions response.

{
  "event_type": "error",
  "application_id": "unique-Informed-app-id",
  "application_reference_id": "partner application id",
  "error_message": "The file size is too large. It should be less than 80MB.",
  "file_id": "unique-Informed-file-id",
  "file_reference_id": "partner file name or id",
  "webhook_url": "https://your.callback.com/here"
}

Verifications error​

If the verifications process encounters an error, then you should expect to receive an asynchronous callback response like the one below, instead of the normal verifications response. Note that the error message says the response is delayed, but in reality the verifications response will not be coming if you get this message.

{
  "event_type": "error",
  "application_id": "unique-Informed-app-id",
  "application_reference_id": "partner application id",
  "webhook_url": "https://your.callback.com/here",
  "error_message": "Verification response is delayed"
}