Skip to main content

Register application

Process Flow​

Please reference the full sequence diagram.

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

Full Example Request​

The first step in having stipulations verified is to register the application with Informed. The below code block shows a full example request payload for the initial call to register an application. The following sections provide details on the key nodes of the request payload.

Example Application
{
  "application_reference_id": "your_unique_application_id",
  "application_date": "2021-05-09T09:11:38",
  "contract_date": "2021-05-09T09:11:38",
  "application_type": "Application",
  "application_status": "active",
  "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": [
        {
          "address": {
            "street_address": "8717 S 4th Ave",
            "city": "Inglewood",
            "state": "CA",
            "zip": "90305"
          },
          "is_current": true,
          "start_date": "2020-10-01",
          "end_date": null,
          "residence_type": "Rent",
          "monthly_housing_cost": 1000
        }
      ],
      "employment_info": [
        {
          "employment_type": "Employed",
          "employer_name": "Envoy Air, Inc.",
          "is_current": true,
          "occupation": "Crew Member",
          "income": {
            "period": "Yearly",
            "amount": 74500
          },
          "start_date": "2018-11-01",
          "end_date": null,
          "business_phone": "9196571475"
        }
      ],
      "additional_incomes": [
        {
          "source": "ChildSupport",
          "income": {
            "period": "Yearly",
            "amount": 10000
          }
        }
      ]
    },
    "applicant2": {
      "first_name": "Lucinda",
      "last_name": "Bonadio",
      "email": "lucinda.bonadio@gmail.com",
      "phone": "9196202345",
      "ssn": "681129443",
      "date_of_birth": "1965-12-10",
      "address_info": [
        {
          "address": {
            "street_address": "8717 S 4th Ave",
            "city": "Inglewood",
            "state": "CA",
            "zip": "90305"
          },
          "is_current": true,
          "start_date": "2020-10-01",
          "end_date": null,
          "residence_type": "Rent",
          "monthly_housing_cost": 1000
        }
      ],
      "employment_info": [
        {
          "employment_type": "Employed",
          "employer_name": "Informed Inc.",
          "is_current": true,
          "occupation": "Crew Member",
          "income": {
            "period": "Yearly",
            "amount": 60000
          },
          "start_date": "2018-11-01",
          "end_date": null,
          "business_phone": "9196571425"
        }
      ]
    }
  },
  "verifications": {
    "income": [
      {
        "belongs_to": "applicant1"
      },
      {
        "belongs_to": "applicant2"
      }
    ],
    "residence": [
      {
        "belongs_to": "applicant1"
      }
    ],
    "insurance": [
      {
        "belongs_to": "applicant1"
      }
    ],
    "identity": [
      {
        "belongs_to": "applicant1"
      },
      {
        "belongs_to": "applicant2"
      }
    ]
  },
  "loan_info": {
    "amount_financed": 21345.23,
    "apr": 7.25,
    "dti": 33,
    "ltv": 89,
    "monthly_payment": 513.62,
    "total_down_payment": 2000.00,
    "sales_price": 23345.23,
    "pti": 10,
    "term": 48,
    "credit_score": {
      "applicant1": 695,
      "applicant2": 680
    }
  },
  "lender_info": {
    "lender_name": "Acme Lending LLC",
    "lender_id": "abc123"
  },
  "services": [
    "extract",
    "verify"
  ],
  "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/consumer/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/consumer/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 dates, status, contract type and customer language.

Application Level Info
{
  "application_reference_id": "your_unique_application_id",
  "application_date": "2021-05-09T09:11:38",
  "contract_date": "2021-05-09T09:11:38",
  "application_type": "Application",
  "application_status": "active",
  ...
}
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
contract_datestringOptional
Typically is the same date as the application date, but can be different. If you explicitly know the contract date, it is recommended to provide it, especially if it is different than the application date.

Use either YYYY-MM-DDThh:mm:ss or YYYY-MM-DD format.
Examples: 1981-12-30T12:25:00 or 1981-12-30
application_typestringOptional
Values can either be Lead or Application.

If the element is not present, or empty, it defaults to the value of Application, which is the standard workflow. Lead is for very specific use cases. Please contact your Account Manager if you have questions about the Lead workflow.
application_statusstringRequired
Set value to active

Applicant Personal Info​

This section of the JSON payload is where all of the applicant's personal information is defined. This information will be used for verifications and comparisons against the documents that are provided for a given application.

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

tip

There needs to be an applicant1 in the payload. If you do not have a second applicant for an application, the preferred approach then is to just leave the applicant2 property out of the payload completely. Please do not set applicant2 to null.

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": [
          {...}
        ],
        "employment_info": [
          {...}
        ],
        "additional_incomes": [
          {...}
        ]
      },
      ...
  }
  ...
}
ElementValueDescription
first_namestringRequired
Example: John
middle_namestringOptional
Middle name or middle initial
Example: Edgar or E
last_namestringRequired
Example: Doe
suffixstringOptional
Valid values are: I, II, III, IV, JR, SR
business_namestringConditional
If you are registering a business retail loan, the first applicant will be the business, and it will use the business_name property as opposed to the different name properties.

Example: Best Business Company, Inc.

Note: If you use the business_name property for the business in applicant1, then you will submit a null value for the first_name and last_name properties.
emailstringOptional
Should be a valid email address.  Example: john.doe@gmail.com
phonestringOptional
Only required if part of a CollectIQ request. Only US mobile phone numbers that are textable will be supported.
Example: 6508675329 or 650-867-5329

Note: For partners integrating after January 2024, phone will be a required field. It is also a required field if you are registering a Lead.
ssnstringConditional
Currently, you will not receive a 400 response if you leave this property out of your request, but if you are verifying ssn, then you definitely should be providing the ssn property with a value. If you don't know the applicant's SSN, then you can submit a null value, but please note that this may change in the future to require a non-null value.

Example: 666111234. Could also be an ITIN.
Can also be last 4 digits of the SSN.
Example: 1234

Note: For partners integrating after January 2024, ssn will be a required field.
tax_idstringConditional
If you are registering a business retail loan, the first applicant will be the business, and it will use the tax_id property as opposed to the ssn property.

Example: 666111234

Note: If you use the tax_id property for the business in applicant1, then you will submit a null value for the ssn property.
date_of_birthstringRequired
Currently, it is required to submit the date_of_birth property in every request, but if you do not know the applicant's date of birth, then you can submit a null value (also it would be null if the applicant is a business).

Please note that in the future it may be required to include a non-null value for date_of_birth if you are verifying credit_application, identity, or ssn.

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. It is important that if there are multiple addresses being sent for an applicant, that only the current residence has is_current set to true.

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
          }
        ],
        "employment_info": [
          {...}
        ],
        "additional_incomes": [
          {...}
        ]
      },
      ...
  }
  ...
}
ElementValueDescription
street_addressstringRequired
Example: 1 Example St
street_2stringOptional
Example: Apt 120C
citystringRequired
Example: San Francisco
statestringRequired
Standard two-letter abbreviation. Example: CA
zipstringRequired
Zip codes are formatted as strings due to the fact that some zip codes start with a zero. Example: 94105
is_currentbooleanRequired
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)

Applicant Employment Info​

This section of the JSON payload is where the applicant's employment information is specified. Only one block of employment information with is_current set to true should be added to the employment_info section.

tip

If the applicant has more than one current employer, the additional employment income should be included in the additional_incomes section described below.

If the applicant is a business, then the employment_info key-value pair is not expected.

Applicant Employment Info
{
  ...
  "applicants":
  {
    "applicant1":
      {
        ...
        "address_info": [
          {...}
        ],
        "employment_info": [
          {
            "employment_type": "Employed",
            "employer_name": "Envoy Air, Inc.",
            "is_current": true,
            "occupation": "Crew Member",
            "income":
            {
              "period": "Yearly",
              "amount": 74500
            },
            "start_date": "2018-11-01",
            "end_date": null,
            "business_phone": "9196571475"
          }
        ],
        "additional_incomes": [
          {...}
        ]
      },
      ...
  }
  ...
}
ElementValueDescription
employment_typestringRequired
Valid values: Employed, Unemployed, Retired, SelfEmployed, Other
employer_namestringConditional
Required if employment_type is Employed.

Example: Informed, Inc.

If you do not know the employer name, you can put unknown for the value of this element, but note that the subsequent mismatch of expected employer name to actual employer name found on the supporting documentation will trigger the need for manual intervention.
is_currentbooleanRequired
If true this designates the applicant's current employment. Set to false if providing previous empoloyment information. One of the associated employment objects must have is_current set to true.
occupationstringOptional
But highly recommended to include it if you have it.
Example: "Software engineer"
periodstringRequired
Valid values: Weekly, BiWeekly, Semimonthly, Monthly, Quarterly, Yearly, Annually
amountnumericRequired
Income amount earned in the specified period (in USD).
Example: 3126.00
start_datestringConditional
Required if employment_type is Employed.

Date when the applicant began working at the place of employment. Use YYYY-MM-DD format: 2018-11-01
end_datestringOptional
Date when the applicant stopped working at the place of employment (only applies if this is not their current employment). Use YYYY-MM-DD format: 2020-11-01
business_phonestringOptional
Only US phone numbers will be supported.
Example: 6508675309 or 650-867-5309.

Applicant Additional Income Info​

This section of the JSON payload is where any additional sources of income can be specified for an applicant. This section should only be included if there are additional incomes that need to be accounted for.

Applicant Additional Income Info
{
  ...
  "applicants":
  {
    "applicant1":
      {
        ...
        "address_info": [
          {...}
        ],
        "employment_info": [
          {...}
        ],
        "additional_incomes": [
          {
            "source": "ChildSupport",
            "income":
            {
              "period": "Yearly",
              "amount": 10000
            }
          }
        ]
      },
      ...
  }
  ...
}
ElementsValuesDescription
sourcestringRequired
Valid values are:
Alimony, Annuity, ChildSupport, DisabilityInsurance, PassiveIncome, RideShare, SSI, Trust, Other. Second jobs are typically classified as Other.
periodstringRequired
Valid values: Weekly, BiWeekly, SemiMonthly, Monthly, Quarterly, Yearly, Annually
amountnumericRequired
Income amount earned in the specified period (in USD).
Example: 3126.00

Verifications​

The verifications are the stipulations for which an applicant will be analyzed. Both applicants do not need to have the same stipulations. This is defined by the belongs_to property for either or both applicants or the application on each individual verification.

Verifications 
{
  ...
  "verifications": {
    "income": [
      {
        "belongs_to": "applicant1"
      },
      {
        "belongs_to": "applicant2"
      }
    ],
    "residence": [
      {
        "belongs_to": "applicant1"
      }
    ],
    ...
  }
  ...
}
ElementValueDescription
verificationsstringRequired

Valid values for consumer stipulations belonging to applicants:
identity, income, residence, insurance, ssn
belongs_tostringRequired
Associates the given verification with a particular applicant. Values would be applicant1, applicant2 as appropriate.

Loan Info​

The loan_info section contains relevant information about the loan in question. It is currently an optional section.

Loan Info
{
  ...
  "loan_info": {
    "amount_financed": 21345.23,
    "apr": 7.25,
    "dti": 33,
    "ltv": 89,
    "monthly_payment": 513.62,
    "total_down_payment": 2000.00,
    "sales_price": 23345.23,
    "pti": 10,
    "term": 48,
    "credit_score": {
      "applicant1": 695,
      "applicant2": 680
    }
  },
  ...
}
ElementValueDescription
amount_financednumericOptional
Integer or decimal value representing the dollar amount financed.
Example: 21345.23
aprnumericOptional
Decimal value representing the APR (percentage) of the loan.
Example: 7.25
dtinumericOptional
Integer value representing percentage of debt-to-income ratio.
Example: 33
ltvnumericOptional
Integer value representing percentage of loan-to-value ratio.
Example: 89
monthly_paymentnumericOptional
Integer or decimal value representing dollar amount of monthly payment.
Example: 513.62
total_down_paymentnumericOptional
Integer or decimal value representing dollar amount of total down payment.
Example: 2000.00
sales_pricenumericOptional
Integer or decimal value representing dollar amount of sales price.
Example: 23345.23
ptinumericOptional
Integer value representing percentage of payment-to-income ratio.
Example: 10
termnumericOptional
Integer value representing the number of months of the loan term.
Example: 48
credit_scoreobjectOptional
Object holding the integer value representing each registered applicant's credit score. If there is only one applicant, then you just need to include applicant1.

Example:
"credit_score": {
   "applicant1": 695,
   "applicant2": 680
}

Lender Info​

The lender_info section contains relevant information about the lender. It is currently an optional section.

Lender Info
{
  ...
  "lender_info": {
    "lender_name": "Acme Lending LLC",
    "lender_id": "abc123"
  }
  ...
}
ElementValueDescription
lender_namestringOptional
The name of the lender associated with this application. For most lenders, this will not change, but for some integrations, having the option to specify a lender per application will allow for additional metrics tracking or billing differentiation.

Example: Acme Lending LLC
lender_idstringOptional
A unique identifier for the lender named in lender_name

Example: abc123

Services​

These are the services that the Informed API will be able to perform for the registered application if specified in the request:

  • The extract service will return both the classification of the documents and the relevant data extracted from the documents that were provided.
  • The verify service will perform analysis of all of the requested verifications for a given applicant based on the provided documents.

For most of your calls, you will want to include the extract and verify options, since you will receive the classification results in the extraction response.

{
  ...
  "services": [
    "extract",
    "verify"
  ],
  ...
}

Callback Url​

A webhook must be provided to receive asynchronous responses containing classified documents with extracted data and analysis. Basic auth credentials 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, but 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 application 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. For example, if you start with two applicants and only send one applicant in the update payload, the second applicant will be removed from the application.

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.

Endpoint​

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

/v1/consumer/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/consumer/applications/<unique-Informed-app-id>

Tracking update requests​

Informed now offers the ability to more definitively correlate specific application PUT updates with the resulting verifications response. To accomplish this, you will need to include the new application_update_reference_id property in your application update PUT request as shown below.

{
  "application_reference_id": "your_unique_application_id",
  "application_update_reference_id": "your_unique_update_identifier",
  "application_date": "2021-05-09T09:11:38",
  "application_type": "Application",
  ...
}

The same application_update_reference_id key and value will be returned in the corresponding verifications response, and all subsequent verifications responses until you send a new PUT update to the application registration with a new application_update_reference_id. You should be putting a unique value for the application_update_reference_id in each PUT request if you are using this functionality (e.g., a UUID/GUID or hash).

Responses​

Synchronous response​

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

Asynchronous response​

An application update using the PUT method will always result in an asynchronous verifications response to your callback URL.