Skip to main content

Register application

Process Flow​

The Informed income calculation service provides a streamlined approach to calculating income from consumer-permissioned documents. Please reference the sequence diagram for the full process flow.

Base URL​

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

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

Example Request​

The first step in calculating income is to register the application and associated applicant with Informed. The below code block shows an example request payload for the initial call to register an application. The following sections provide details on the key nodes of the request payload.

{
  "application_reference_id": "your_unique_application_id",
  "application_date": "2021-05-09T09:11:38",
  "applicants": {
    "applicant1": {} // including applicant info is optional
  },
  "services": [
    "extract", // optional
    "income-calc"
  ],
  "webhook": "https://your.callback.com/here"
}

Request Components​

Endpoint​

You will append the following endpoint to the base URL to register the initial application:

/v1/income/applications

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

https://api.staging.informediq-infra.com/v1/income/applications

Application Level Info​

This is the application level information included in the payload, where your unique Application Reference ID is defined along with the application date.

Application Level Info
{
  "application_reference_id": "your_unique_application_id",
  "application_date": "2021-05-09T09:11:38"
  ...
}
ElementValueDescription
application_reference_idstringRequired
Your unique identifier for the loan application
application_datestringRequired
The date when the application was decisioned.

Use either YYYY-MM-DDThh:mm:ss or YYYY-MM-DD format.
Examples: 1981-12-30T12:25:00 or 1981-12-30

Applicant Personal Info​

This section of the JSON payload is where all of the applicant's personal information is defined.

At the current time, the number of applicant blocks that can be provided under the applicants section is limited to just applicant1.

caution

For the income calculation service, the applicant's personal information is optional, but even if you don't have any of the personal information, you must at least include the empty placeholder for applicant1.

{
  ...
  "applicants": {
    "applicant1": {}
  }
  ...
}
Applicant Personal Info
{
  ...
  "applicants":
  {
    "applicant1":
      {
        "first_name": "Jo",
        "middle_name": null,
        "last_name": "Boren",
        "suffix": null,
        "email": "jo.boren@gmail.com",
        "phone": "9196201234",
        "ssn": "681129638",
        "date_of_birth": "1965-12-10",
        "address_info": [
          {...}
        ]
      }
  }
  ...
}
ElementValueDescription
first_namestringOptional
Example: John
middle_namestringOptional
Middle name or middle initial
Example: Edgar or E
last_namestringOptional
Example: Doe
suffixstringOptional
Valid values are: I, II, III, IV, JR, SR
emailstringOptional
Should be a valid email address.  Example: john.doe@gmail.com
phonestringOptional
Only US phone numbers will be supported.
Example: 6508675329 or 650-867-5329
ssnstringOptional
Example: 666111234. Could also be an ITIN.
Can also be last 4 digits of the SSN.
Example: 1234
date_of_birthstringOptional
Date of birth value should be in YYYY-MM-DD format.
Example: 1981-12-30

Applicant Address Info​

This section of the JSON payload is where the applicant's address information is specified. For the income calculation service, the applicant's address information is optional.

Applicant Address Info
{
  ...
  "applicants":
  {
    "applicant1":
      {
        ...
        "address_info": [
          {
            "address":
              {
                "street_address": "8717 S 4th Ave",
                "street_2": "Apt 120C",
                "city": "Inglewood",
                "state": "CA",
                "zip": "90305"
              },
              "is_current": true,
              "start_date": "2020-10-01",
              "end_date": null,
              "residence_type": "Rent",
              "monthly_housing_cost": 1000
          }
        ]
      }
  }
  ...
}
ElementValueDescription
street_addressstringOptional
Example: 1 Example St
street_2stringOptional
Example: Apt 120C
citystringOptional
Example: San Francisco
statestringOptional
Standard two-letter abbreviation. Example: CA
zipstringOptional
Zip codes are formatted as strings due to the fact that some zip codes start with a zero. Example: 94105
is_currentstringOptional
If set to true this designates that the address is the current residence for the applicant. If the address is a previous residence, the value should be set to false. One of the associated address objects must have is_current set to true.
start_datestringOptional
Date when the applicant began living at the specified address. Use YYYY-MM-DD format: 2020-10-01
end_datestringOptional
If not the current residence, this is date when the applicant stopped living at that address. Use YYYY-MM-DD format: 2022-10-01
residence_typestringOptional
Valid values are: Rent, Own, Family, Mortgage
monthly_housing_costnumericOptional
Example: 1000.01 (in USD)

Services​

This portion of the documentation is specific to the income calculation service, thus the only applicable services to include in your request are the extract and income-calc services. Note that the extract service is purely optional.

{
  ...
  "services": [
    "extract",  // optional
    "income-calc"
  ],
  ...
}

Callback Url​

A webhook must be provided to receive asynchronous responses containing classified documents with extracted data and analysis. Authentication details will need to be shared with Informed to ensure secure transmission at time of setup. To further safeguard data, Informed will only POST back to your webhook using the HTTPS protocol to ensure encryption in transit. More technical details about your callback endpoint can be found at the link in this paragraph above.

caution

Please note that you are not forced to provide a webhook URL. If you send an empty string for the value of the webhook property, you will not receive any asynchronous, programmatic callbacks with data.

{
  ...
  "webhook": "https://your.callback.com/here"
}

Synchronous Response​

A successful API request resulting in an application registration will return the following synchronous response to indicate that the application was submitted to Informed. Make sure that you record the application_id value, as you will need that in subsequent steps, such as associating documents with the application or updating the applicant info.


  {
    "application_id": "unique-Informed-app-id",
    "status": "Ready"
  }

Updating Application Info​

The update payload will look the same as the initial application registration request payload, but with the modified values/additions. And, you will need to send this as a PUT call to a slightly different endpoint because the application already exists.

caution

Note that this is a PUT and not a PATCH call, which means that you must resend the entire original payload but with any applicable modifications.

The one thing you cannot update with this PUT call for an existing application is the application_reference_id (reference). That value must stay the same for the life of the application.

You will append the following endpoint to the base URL to update the application:

/v1/income/applications/<unique-Informed-app-id>

So to put it all together, you will make a PUT call to the following URL with your request payload:

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

tip

The synchronous response will contain the same unique-Informed-app-id that you received in the synchronous response to the original application registration.


  {
    "application_id": "unique-Informed-app-id",
    "status": "Ready"
  }