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 initial 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 will have a data_action with a value of create or update.

info

Documents found in the initial extractions callback after the file is uploaded will have a data_action of create.

But, if a document is edited using the Human in the Loop or HITL interface, then an updated extractions callback response will be sent for that document, and the data_action for that document will be update to indicate that it is not the original extractions.

And, because new information is now available in the updated extractions, verifications will run again and an updated verifications callback response will be sent as well.

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

info

Every implementation should include the ability to retrieve the individual, indexed documents via the url provided whether you believe you have an immediate use for them or not. For users of CollectIQ, this is absolutely imperative because you will have no other way of obtaining the images uploaded by applicants.

• Details about what items are extracted (in extracted_data) for a given document type can be found in the reference library for common consumer documents and dealer documents.

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"
      }
    ]
  }
}

Common Type Values

In many of the dealer documents, there are collections of transactions related to things like taxes, fees, ancillary products and other charges that all have a type property and an amount or premium property. The table below provides an overview of some of the more common type values that are returned in extractions.

Taxes	Fees (cont.)	Insurance Charges
sales_tax	registration_fee	other
stamp_tax	acquisition_fee	vsc
state_tax	license_fee	gap
county_tax	title_fee	anti_theft
government_tax	filing_fee	tire_wheel_plan
dealer_inventory_tax	public_official_fee	maintenance_plan
other_tax	inspection_fee	appearance_plan
	emissions_fee	paintless_dent_repair
	delivery_fee	key_replacement
Fees	electronic_vehicle_fee	windshield_protection
pre_delivery_fee	state_emissions_fee	bundled_product
plate_transfer_fee	administrative_fee
convenience_fee	stamp_fee
lien_fee	deputy_service_fee	Other Charges
documentation_fee	notary_fee	contract_cancellation_option
other_fee	messenger_fee	prior_credit_or_lease_balance
lemon_law_fee	road_and_bridge_fee
smog_abatement_fee	county_fee
tire_battery_fee	ert_fee

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.
• NEW:  The initial_status reflects the original application-level aggregate verifications status. This value is set based on the first verifications run and will never change after that. This property is helpful for tracking things like straight-through processing (STP) metrics and determining what factors are impacting your STP.
• NEW:  The current_status reflects the application-level aggregate verifications status of the current verifications run. This value will be subject to change on every verifications run as the situation changes.
• The application_status is tied to the value that you send in application registration/update payloads (or update via the VerifyIQ portal) reflecting the current status of the application, e.g., active, funded, declined, held, etc.
• 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 described here.
• 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. More details can be found in the reference library.
• 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 for a given document type can be found in the reference library.

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",
  "initial_status": "fail",
  "current_status": "fail",
  "application_status": "active",
  "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.

Verifications Summary PDF

If you have seen the instructions for downloading a Verifications Summary PDF in the UI section of the documentation and wished that you could do that programmatically-- well, now you can.

It is a three-step process:

• Send a POST request to cause the PDF to be created
• Wait for an asynchronous webhook call to say the PDF is ready
• Make a GET request to retrieve the summary PDF

Initial request

To initiate the process of obtaining the Verification Summary PDF, make a POST call to the appropriate URL for the environment that you are working in as shown below.

Environment	URL
Staging	https://pdf.staging.informediq-infra.com/v1/applications/<informed-app-id>
Production	https://pdf.prod.informediq.com/v1/applications/<informed-app-id>

info

Note that you do not need any "body" with your request. In the near future, we will be adding the ability to provide an indicator in the body of the request to only retrieve the verification summary or only retrieve the documents (similar to what you can do in the UI). Backwards compatibility will be maintained in that the absence of a request body will continue to return the combined verification summary and documents as described here.

If this funcitonality is important to you, please let your account representative know and they can work with you on that feature.

This call kicks off a process in the background to create the summary report with the latest verifications and documents relating to the application ID that you used in the URL.

Asynchronous webhook

After a short period of time, you will receive an asynchronous webhook callback (POST) to the same webhook callback URL that you submitted at the time of application registration.

The body of the callback will look like this:

{
  "event_type": "PDFGenerationComplete",
  "application_id": "informed-app-id",
  "application_reference_id": "your-unique-app-id",
  "request_id": "unique-request-id"
}

You will need the Request ID for your next call, along with the Informed application ID, of course.

If something goes wrong with the generation of the report, you will receive an asynchronous webhook callback (POST) that looks like this:

{
  "event_type": "PDFProcessError",
  "application_id": "informed-app-id",
  "application_reference_id": "your-unique-app-id",
  "error_message": "Interval Server Error",
  "request_id": "unique-request-id"
}

Retrieve the summary

The asynchronous callback indicates that the report is ready to retrieve, and since you now have all the information needed, you can make a GET call to the appropriate URL below with the variables filled in with the unique Informed application ID and the Request ID.

Environment	URL
Staging	https://pdf.staging.informediq-infra.com/v1/applications/<informed-app-id>/requests/<request-id>
Production	https://pdf.prod.informediq.com/v1/applications/<informed-app-id>/requests/<request-id>

You will want to save the PDF that is returned by the GET call somewhere in your system where the loan officers and funders can see it quickly and conveniently.

Click here to view a sample Verification Summary PDF.

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