Collect documents and data

Process Flow

If you do not have the necessary supporting documents from the applicant, Informed gives you the option to collect those documents directly from the applicant via a secure, white-labeled web application known as CollectIQ.

Informed sends an SMS text message to the applicant(s) asking them to upload the requested supporting documents. The SMS text message contains a personalized link to the web application hosted by Informed on your behalf where applicants can securely upload the requested supporting documents.

Please reference the full sequence diagram.

Registering an application

The collect documents functionality only works in the context of an existing application-- i.e., an application that has been registered via the process described here.

Compliance

While it is ultimately your responsibility to obtain the consent of the applicant to receive SMS communications regarding their application, Informed will honor the applicant's desire to "opt-out" of the communications and report that information back to you.

Base URL

The table below shows the Base URL to be used with the endpoints mentioned in this guide.

Environment	Base URL
Staging:	https://api.staging.informediq-infra.com
Production:	https://api.informediq.com

Request Components

Endpoint

You will append the following endpoint to the base URL to generate a request to collect documents from the applicant:

/v1/consumer/applications/<unique-Informed-app-id>/documents/collect

tip

The <unique-Informed-app-id> needs to be the application_id described in the synchronous response section of the app registration guide.

So to put it all together, you will make a POST call to the following URL with a request payload similar to the example shown below:

https://api.staging.informediq-infra.com/v1/consumer/applications/<unique-Informed-app-id>/documents/collect

If you later require additional documents from the applicant for a particular application, you can repeat the process described in this guide to request those documents from the applicant.

Example payload

Below is an example payload for requesting various documents from applicants. Note that this payload must dynamically change depending on the needs of each specific situation. The payload components are explained in greater detail below.

{
  "send_sms": true,  // optional
  "applicant1": {
    "categories": {
      "identity": {
        "combinatorial_logic": "any",
        "documents": {
          "driver_license_front": {},
          "state_id": {},
          "passport": {}
        }
      },
      "income": {
        "combinatorial_logic": "one_or_more",
        "documents": {
          "paystub": {"num_required": 1},
          "bank_statement": {"num_required": 3},
          "ssi_award_letter": {"num_required": 1},
          "form_1040": {"num_required": 2},
          "military_les": {"num_required": 1}
        }
      },
      "residence": {
        "combinatorial_logic": "any",
        "documents": {
          "utility_bill": {},
          "bank_statement": {"num_required": 1}
        }
      },
      "misc": {
        "combinatorial_logic": "all",
        "documents": {
          "marriage certificate": {}
        }
      }
    }
  },
  "applicant2": {
    "categories": {
      "ssn": {
        "combinatorial_logic": "any",
        "documents": {
          "social_security_card": {}
        }
      },
      "references": {
        "combinatorial_logic": "all",
        "documents": {
          "references": {
            "num_required": 2
          }
        }
      }
    }
  }
}

Request-level Properties

caution

Note that these request-level (root-level) properties apply to any and all applicants that are included in the request.

Determining whether or not to send the SMS text message

There may be situations where you would prefer not to have Informed send the text message directly to the applicant, but instead include the short link (found in the synchnronous response) in an email or other communication medium of your own with the applicant.

This decision can be accomplished through the use of the send_sms property at the root level of the request.

Below is the matrix of possible scenarios:

Scenario	Value	Outcome
send_sms present	true	Informed will send a text message to the specified applicants requesting the designated document types.
send_sms present	false	Informed will NOT send a text message to any of the specified applicants, but you will still be able to use the short links provided in the synchnronous response to provide to the appropriate applicant.
send_sms not present	true	When this optional property is not provided, the default behavior is to treat it as a true value and Informed will send the text messages to the specified applicants.

Applicants

At the root level of the request payload are the applicants from which you wish to request documents.

Acceptable values: applicant1, applicant2

tip

Only include applicant sections for applicants from which you need documents. In other words, if you do not need to collect documents from applicant2, then you should not include that applicant in the payload.

{
  "applicant1": {
    ...
  },
  "applicant2": {
    ...
  }
}

Categories

For each applicant from whom you are requesting supporting documents, you will need to list the high level categories under which to group the combination logic and acceptable document types. The acceptable category keys are shown below:

• identity
• income
• residence
• insurance
• ssn
• references (see references below)
• misc

More information about the misc category is given below under document types.

{
  "applicant1": {
    "categories": {
      "identity": {
        ...
      },
      "income": {
        ...
      },
      "residence": {
        ...
      },
      "references": {
        ...
      },
      "misc": {
        ...
      }
    }
  },
  "applicant2": {
    "categories": {
      "ssn": {
        ...
      }
    }
  }
}

Combination logic

Within a given category, there can be different expectations associated with the combination of documents needed from the applicant. The expected combination logic can be specified with the combinatorial_logic property within the category. The explanation of each of the acceptable logic types is found in the table below.

Logic	Explanation
any	Use this combination logic when there are multiple document types that the applicant can use to satisfy the category and the applicant only needs to upload one of the document types to satisfy the category. A good example would be for the residence category where the applicant can upload a paystub or a driver's license or a utility bill. But the applicant only needs to upload one of those in order to prove residence.
one_or_more	Use this combination logic when there are multiple document types that the applicant can use to satisfy the category and there is potential benefit or desire for the applicant to be able to upload more than one of the document types listed. The most common category which would use this combination logic would be income, where you would want the applicant to upload their paystub, but also be able to upload documents to support additional sources of income, such as bank statements or SSI award letters, etc.
all	Use this combination logic when you require the applicant to upload ALL the document types listed for the category. Normally, this combination logic would be used for the misc and references categories.

{
  "applicant1": {
    "categories": {
      "income": {
        "combinatorial_logic": "one_or_more",
        "documents": {...}
      },
      "misc": {
        "combinatorial_logic": "all",
        "documents": {...}
      }
    }
  },
  "applicant2": {
    "categories": {
      "identity": {
        "combinatorial_logic": "any",
        "documents": {...}
      }
    }
  }
}

Document types

The document type id's that you should use with each of the categories align with the document types on the document components page.

Category	Allowed Requested Document Types
income	paystub w2 bank_statement form_1040 ssi_award_letter military_les payroll_connect (please see info box below the table)
residence	paystub bank_statement utility_bill phone_bill driver_license_front state_id ssi_award_letter
identity	driver_license_front state_id passport mexican_matriculas green_card
insurance	insurance_id_card verification_of_coverage
ssn	social_security_card
references	references (see references below)
misc	There are no explicit document types associated with the misc category. This is the one category that can accept "free-form" document types. Each of the document types that you list here should be a unique, short but descriptive string that contains no special characters. For a list of document types which Informed can classify, see the document components page. Bear in mind that you can still request document types using the misc category even if Informed does not classify them.

info

Please note that the payroll_connect document type is a special use document type for collecting consumer-permissioned data sources through third party services such as Truework. You must have contracted with Informed and/or the third party for the use of their service and the Informed team must explicitly configure your account in order to be able to use this document type. More information can be found in the third party sources section below.

{
  "applicant1": {
    "categories": {
      "identity": {
        ...
        "documents": {
          "driver_license_front": {},
          ...
        }
      },
      "income": {
        ...
        "documents": {
          "paystub": {"num_required": 1},
          "bank_statement": {"num_required": 3},
          ...
        }
      },
      "misc": {
        ...
        "documents": {
          "marriage certificate": {},
          ...
        }
      }
    }
  }
}

Desired quantity

For many document types, you will logically only need to request one of them (e.g., a driver's license), but for other types, you need more than one (e.g., last 3 months of bank statements or 3 references). The payload schema allows for specifying a desired quantity for each requested document type.

If you want to request more than one of a certain document type, just add the "num_required": X key/value pair to the document type object as shown below. The X will be an integer representing the desired quantity.

tip

If you do not assign a num_required property, the assumed desired quantity is 1.

{
  "applicant1": {
    "categories": {
      "identity": {
        ...
        "documents": {
          "driver_license_front": {},
          "state_id": {},
          "passport": {}
        }
      },
      "income": {
        ...
        "documents": {
          "paystub": {"num_required": 1},
          "bank_statement": {"num_required": 3},
          "ssi_award_letter": {"num_required": 1},
          ...
        }
      },
      "misc": {
        ...
        "documents": {
          "marriage certificate": {}
        }
      }
    }
  }
}

References

Informed has added a new category of data that can be collected via the CollectIQ web browser user interface.

{
  "applicant1": {
    "categories": {
      ...
      "references": {
        "combinatorial_logic": "all",
        "documents": {
          "references": {
            "num_required": 3
          },
          ...
        }
      },
      ...
    }
  }
}

References allows you to have the applicant electronically fill in the information on one or more references via the CollectIQ user interface.

Notes:

• The combinatorial_logic for the references category should always be all.
• The applicant will be asked to provide the following information about each reference:
  • first and last name
  • relationship
  • phone number
  • city and state

The form looks like this:

The digital data of the supplied references will be included in an extractions response. See the example below for the format of the extracted data when three references are requested and supplied.

Example References Extraction Response

{
  "event_type": "extractions",
  "application_id": "767f3242-fd38-4ef4-8f88-a8598383a6ff",
  "application_reference_id": "test-app-001",
  "documents": {
    "references_electronic": [
      {
        "data_action": "create",
        "document_id": "de6d7c25-be59-4c61-bb42-69193f0847bd",
        "document_label": "Electronic References",
        "file_ids": null,
        "file_reference_ids": null,
        "url": null,
        "extracted_data": {
          "references_electronic": [
            {
              "first_name": "Donald",
              "last_name": "Durban",
              "relationship": "family",
              "phone_number": "5551234567",
              "city": "Albuquerque",
              "state": "NM"
            },
            {
              "first_name": "Mickey",
              "last_name": "Martin",
              "relationship": "acquaintance",
              "phone_number": "5552352356",
              "city": "New York",
              "state": "NY"
            },
            {
              "first_name": "Roland",
              "last_name": "Smith",
              "relationship": "friend",
              "phone_number": "5558982345",
              "city": "Tampa",
              "state": "FL"
            }
          ]
        },
        "updated_at": "2024-02-14T05:59:11Z"
      }
    ]
  }
}

Synchronous Response

This is the synchronous response that can be expected from sending a collect documents request.

2xx response

{
  "status_code": 200,
  "message": {
    "request_id": "Informed Request Id",
    "upload_urls": {
      "applicant1": "https://short.link.com/here"
    }
  }
}

Non-2xx responses

If you forget any of the necessary properties of the collect documents POST call, such as the applicant section, combination logic or correct categories/document types, you will receive an error message similar to the one shown below, detailing the issues with your request.

{
  "status_code": 400,
  "message": "RequiredFieldMissing",
  "errors": [
    {
      "reason": "RequiredFieldMissing",
      "location": "applicant1 -> categories -> income -> combinatorial_logic",
      "values": [
        null
      ]
    }
  ]
}

If you were to make a collect documents POST call to an application that already has had a collect documents POST call, you would receive the synchronous error response shown below. It reminds you to use a PATCH call for subsequent collect documents calls.

{
  "status_code": 400,
  "message": "POST request already exists for this application id: <Informed app id>. Please use a PATCH request to update your collect documents request",
  "errors": "DuplicatePOSTRequest"
}

Asynchronous Responses

A collect documents request can result in a number of asynchronous responses depending on the actions of the applicant once they receive the SMS text message. All of these asynchronous responses are posted to the callback webhook registered with the application.

Tracking SMS messages sent to applicants

Regardless of whether or not the applicant ever uploads any of the requested documents, Informed will always POST an sms-sent event to your registered callback webhook notifying you that the SMS text message has been sent as requested.

{
  "event_type": "sms-sent",
  "application_id": "unique-Informed-app-id",
  "application_reference_id": "partner application id",
  "reference_id": "caller-provided reference id",
  "applicant_phone": "1234567890",
  "belongs_to": "applicant1",
  "message_body": "Hi Jo, please upload your required documents using this link https://infrmd.com/xyz123",
  "login_link":  "https://short.link.com/here",
  "sms_sent_at": "date/time stamp"
}

Tracking opt-outs

In the event that the applicant decides they no longer want to receive text messages relating to their loan application with you, they may reply with any of the recognized key words for opting out: STOP, STOPALL, END, CANCEL, UNSUBSCRIBE, QUIT.

If this occurs, Informed will POST an sms-opt-out event to your registered callback webhook notifying you that the applicant wishes to opt out of future communications via text message.

{
  "event_type": "sms-opt-out",
  "application_id": "unique-Informed-app-id",
  "application_reference_id": "partner application id",
  "applicant_phone": "1234567890",
  "belongs_to": "applicant1",
  "sms_opt_out_at": "date/time stamp"
}

Extractions

For each requested file that the applicant uploads successfully, Informed will POST an asynchronous extractions response to the callback webhook registered for the application. This extractions response will contain the extracted data from the document types found in the uploaded image file.

Extractions responses resulting from CollectIQ uploads will contain a metadata block with a collectiq property that contains the following elements:

• document_upload_label provides a relevant document label. If the uploaded document type is one which Informed classifies, then this label will not provide much additional insight. However, where it becomes extremely helpful is when you are requesting a document under the misc category (the "Other" section in the RequestIQ UI modal). Then this label will be what you entered as the freeform type.
• document_uploaded_by indicates which applicant uploaded the image. If you only have one applicant on an application, then this would not be as helpful, but it becomes very helpful when you have two applicants and are receiving multiple file uploads via CollectIQ.

Example extractions payload for a document uploaded via CollectIQ:

{
  "event_type": "extractions",
  "application_id": "d33aba0e-159c-43a7-b7a6-154c214229e1",
  "application_reference_id": "collectiq-metadata-test",
  "documents": {
    "unknown": [
      {
        "data_action": "create",
        "document_id": "1e5d8cb7-c22b-444e-9de8-8b542aacfc30",
        "document_label": "Unknown",
        "file_ids": [
          "9a57b719-15aa-44c6-9cd7-7ad64df6922a"
        ],
        "file_reference_ids": [
          "5234f415-35d4-4869-9e72-c9d3a03581e2"
        ],
        "metadata": {
          "collectiq": {
            "document_upload_label": "Court Summary",
            "document_uploaded_by": "applicant1"
          }
        },
        "url": "https://informed-techno-core-<env>-downloads.s3.amazonaws.com/123...",
        "extracted_data": {},
        "updated_at": "2024-05-14T20:33:59Z"
      }
    ]
  }
}

Verifications

Once the uploaded files have finished processing, Informed will POST an asynchronous verifications response to the callback webhook registered for the application. This verifications response will contain the analysis of the specified verifications based on the extracted data from the document types found in the aggregate of the uploaded image files along with any other supplied images.

Asynchronous error messages

If for some reason an SMS text message is not able to be successfully sent to the specified applicant, Informed will POST an sms-send-error event to your registered callback webhook notifying you of the error.

{
  "event_type": "sms-send-error",
  "application_id": "unique-Informed-app-id",
  "application_reference_id": "partner application id",
  "reference_id": "transaction reference id",
  "applicant_phone": "1234567890",
  "error_message": "INVALID_BUT_POSSIBLE"
}

Requesting additional documents

Sometimes, the first round of collecting documents will not fully satisfy your needs and you may want to reach out to the applicant again. But you don't want to have to repeat all the documents you asked for initially-- just the ones you need now.

tip

Unlike the original POST API call to collect documents, you will need to make a PATCH call with a request payload similar to the example shown below for the follow on requests.

Example URL: (same format as before but as a PATCH call)

https://api.staging.informediq-infra.com/v1/consumer/applications/<unique-Informed-app-id>/documents/collect

Example payload

Subsequent request payloads will likely be much more targeted depending on the situation -- maybe you decided that you need a different document based on what was initially provided.

caution

Please note that the one thing that will not/cannot be changed across subsequent requests is the combination logic. Whatever logic you started with will remain the logic for that category regardless if you add new document types or not.

{
  "applicant1": {
    "categories": {
      "income": {
        "combinatorial_logic": "one_or_more",
        "documents": {
          "paystub": {},
          "ssi_award_letter": {}
        }
      }
    }
  }
}

Third party sources

caution

Please note that the payroll connect features described here are only available if you are properly configured to use the third-party provider in Informed and have an account with the third-party provider either directly or through Informed.

Overview

Payroll connect allows for the use of third-party consumer-permissioned data platforms directly within the CollectIQ workflow such that applicants are able to provide digital data from payroll providers or HR platforms directly to you.

Informed currently supports the following third-party providers to collect consumer-permissioned data:

• Truework

If you are interested in the offerings of the payroll connect features or would like to see a demo, please contact your Account Manager.

Truework

Informed leverages the Truework Credentials product within the CollectIQ workflow to allow applicants to log into their payroll provider in order to provide supporting income data.

The income data provided by the applicant's payroll provider is passed back via the normal asynchronous extractions webhook callbacks along with an Employment Income Verification Report.

Employment Income Verification Report

Truework provides an employment income verification report that summarizes the digital data from the payroll platform into a document. Informed will pass this document back along with the digital data elements that are provided by Truework in an abbreviated format similar to that of paystubs (see example responses below). The document is classified as an Employment Income Verification Report.

Example extractions response

{
  "event_type": "extractions",
  "application_id": "unique-Informed-app-id",
  "application_reference_id": "partner application id",
  "documents": {
    "employment_income_verification_report": [
      {
        "data_action": "create",
        "document_id": "457580d0-a20e-4b25-8deb-5f9746175527",
        "file_ids": null,
        "file_reference_ids": null,
        "updated_at": "2023-09-18T14:04:39Z",
        "url": "https://informed-techno-core-...",
        "extracted_data": {
          "bonus_pay": {
            "current": 0,
            "ytd": 0
          },
          "commission_pay": {
            "current": 0,
            "ytd": 0
          },
          "current_as_of": "2023-12-31",
          "employee_status": "active",
          "employer_address": {
            "address": "",
            "city": "",
            "state": "",
            "zip": ""
          },
          "employer_name": "Fake Company",
          "first_name": "Jo",
          "gross_pay": {
            "current": 0,
            "ytd": 100000
          },
          "hire_date": "2020-01-01",
          "last_name": "Boren",
          "other_pay": {
            "current": 0,
            "ytd": 0
          },
          "overtime_pay": {
            "current": 0,
            "ytd": 0
          },
          "pay_year": "2023",
          "paystubs": [
            {
              "base": 100000,
              "bonus": 0,
              "commission": 0,
              "gross": 0,
              "net": 0,
              "other": 0,
              "overtime": 0,
              "pay_date": "2023-12-31",
              "pay_period_end_date": null,
              "pay_period_hours": 0,
              "pay_period_start_date": null
            }
          ],
          "regular_pay": {
            "current": 0,
            "ytd": 100000
          },
          "salary": {
            "frequency": "biweekly",
            "hours_per_week": null,
            "pay_rate": {
              "amount": 150000,
              "unit": "annually"
            },
            "reduced_covid": "unknown"
          },
          "ssn": "***-**-0000",
          "termination_date": null
        }
      }
    ]
  }
}