Retrieve Report

Retrieves the income report data and a url to the report pdf of a completed request.

Retrieve Report

GET https://api.numaly.com/v1/requests/{id}

Note: An incomplete report will return empty report fields. Make sure to check for an awaiting screening status before parsing the data.

Path Parameters

Name	Type	Required	Description
id	string	true	Either a verification request id or your request_id

201 Verification request successfully sent.

      {
         "id": "1c3f343d-3f21-4c1d-bf53-5939cf42e611",
         "send_to_applicant" true,
         "report_url": "https://www.numaly.com/report?id=1c3f343d-3f21-4c1d-bf53-5939cf42e611&token=eyJhbGciOiJIUzUxMiIsImlhdCI6MTYxMzMwMjEzMSwiZXhwIjoxNjEzMzA1NzMxfQ.eyJ1c2VyX2lkIjo0fQ.lLnNNTBKTWyMA0K5D8BZFSA7YNYDVu2fvB8Wrntach6QwJK29CmCRhP4ogdfsJy6rJ2vzjQc9Pgf1pgT_-bS-Q",
         "identity_report_url: "https://www.numaly.com/report?id=1c3f343d-3f21-4c1d-bf53-5939cf42e611&token=eyJhbGciOiJIUzUxMiIsImlhdCI6MTYxMzMwMjEzMSwiZXhwIjoxNjEzMzA1NzMxfQ.eyJ1c2VyX2lkIjo0fQ.lLnNNTBKTWyMA0K5D8BZFSA7YNYDVu2fvB8Wrntach6QwJK29CmCRhP4ogdfsJy6rJ2vzjQc9Pgf1pgT_-bS-Q"
         "paystub_url": null,
         "request_id": null,
         "request_date": "2021-02-02",
         "completed_date": "2021-02-06",
         "from_date": "2020-02-06",
         "to_date": "2021-02-05",
         "days_retrieved": 365,
         "months_retrieved": 12,
         "requester_name": null,
         "first_name": "Sarah",
         "last_name": "Samples",
         "currency": "USD",
         "status": "awaiting screening",
         "reference": "12 Sample Rd",
         "property_rent": "$700.00",
         "email": "[email protected]",
         "phone_number": null,
         "identity_accept_tos_status": true
         "identity_verify_sms_status": true
         "identity_kyc_check_status": true
         "identity_document_verification_status": true
         "identity_selfie_check_status": true
         "identity_watchlist_screening_status": true
         "identity_risk_status": true
         "permitted_verification_method": ['all']
         "allow_paystub_upload": true
         "verify_identity": true
         "employer": "Abc Hospital",
         "total_income": "$218,454.00",
         "income_projection_12_months": "NA",
         "average_monthly_income": "$18,204.50",
         "average_monthly_income_last_3_months": "$19,204.5",
         "total_recurring_income": "$19,727.00",
         "average_monthly_income_recurring": "$1,643.90",
         "total_non_recurring_income": "$198,727.00",
         "average_monthly_income_non_recurring": "$16,560.58",
         "total_deposits": 62,
         "total_recurring_deposits": 4,
         "total_non_recurring_deposits": 58,
         "income_rent_multiple": "14.10",
         "expense_income_ratio": null,
         "average_monthly_expenses": "$1,211.52",
         "average_days_between_rent_payments": "NA",
         "applicant_note": null,
         "account_names": null,
         "sources":[
            {
               "name": "ABC Hospital",
               "amount": "$198,727.00",
               "recurring": "$0.00",
               "non_recurring": "$198,727.00",
               "last_10_deposits":[
                  {
                     "date": "2021-02-03",
                     "source": "Not available",
                     "amount": "$882.79"
                  },
                  ....
               ]
            },
            {
               "name": "Vanguard Dividends",
               "amount": "$19,727.00",
               "recurring": "$19,727.00",
               "non_recurring": "0.00",
               "last_10_deposits":[
                  {
                     "date": "2020-02-20",
                     "source": "Vanguard 1770",
                     "amount": "$2,576.53"
                  },
                  ....
               ]
            },
            {
               "name": "Others"
               "amount": "$3,654.64",
               "recurring": "$2,978.22",
               "non_recurring": "$676.42",
               "last_10_deposits":[
                  {
                     "date": "2021-01-10",
                     "source": "Amazon",
                     "amount": "$515.22"
                  },
                  ....
               ]
            }
         ],
         "accounts":[
            {
               "account_type": "SAVINGS",
               "available_balance": "$83,644.74",
               "current_balance": "$83,644.74",
               "bank": "Dag Site",
               "account_name": "Joint Savings - 7159",
               "average_balance": "$80,268.66"
            },
            ....
         ],
         "rent_payments":[
            {
                "amount": $800.00, 
                "date": "2020-02-14" 
            },
            ....
         ],
         "meta_data": {},
      }

404 Request not found

Response Schema

All fields are calculated using data retrieved between the period from_date and to_date. All empty field values will return null

Field	Type	Response
id	string	id of the verification request
request_id	string	id of the verification request set by you
from_date	string	How far back the data the income report is generated is generated from.
to_date	string	Date of the most recent transaction the income report is generated from.
days_retrieved	number	Total days of transactions the income report is generated from. It is the delta days of from_date and to_date.
months_retrieved	number	Total months of transactions the income report is generated from. It is the delta months of from_date and to_date.
requester_name	string	Name displayed to applicants when completing an income verification. Set by you.
first_name	string	First name of the applicant.
last_name	string	Last name of the applicant.
currency	string	Currency the income report is denoted in.
status	string	Status of the verification request. Either 'awaiting response', 'awaiting screening', 'accepted', 'rejected'.
opened	boolean	Was a sent verification request click on by the applicant. Note: this defaults to false for all verifications started from your link.
reference	string	Reference of the verification request. Set by you.
property_rent	number	Rent for the applied property.
email	string	Applicants email.
phone_number	number	Applicant mobile number.
employer	string	Applicants employment (supplied by them).
total_income	number	Applicants total income in the period between from_date and to_date.
income_projection_12_months	number	A 12 month income projection if the total income report has less than 12 months of data. (12 ÷months_retrieved) x total_income
average_monthly_income	number	Average monthly income between the period from_date and to_date.
average_monthly_income_3_months	number	Average monthly income in the last 3 months.
total_recurring_income	number	Total recurring income between the period from_date and to_date
average_monthly_income_recurring	number	Average monthly income in the past
total_non_recurring_income	number	Total non-recurring Income between the period from_date and to_date.
average_monthly_income_non_recurring	number	Average monthly non-recurring income between from_date and to_date.
total_deposits	number	Total number of deposits into applicants accounts between from_date and to_date.
total_recurring_deposits	number	Total number of deposits for recurring income between from_date and to_date.
total_non_recurring_deposits	number	Total number of deposits for non-recurring income between from_date and to_date.
income_rent_multiple	number	average_monthly_income ÷ property_rent.
expense_income_ratio	number	average_monthly_expenses ÷ average_monthly_income
average_monthly_expenses	number	Average total expenses per month between the period from_date and to_date.
average_days_between_rent_payments	number	The average number of days the between each of the applicants rent payments.
applicant_note	string	A comment left by the applicant on the report.
account_names	string	The names on the applicants bank accounts.
sources	array	An array objects containing information on each of the applicants income sources.
accounts	array	An array objects containing information on each of the applicants accounts with their banks (e.g Checking, Savings ..)
rent_payment_history	array	An array of objects containing each of the applicants rent payments between the period from_date and to_date.
meta_data	object	The data you supplied when creating your verification link (see start verification tab)
request_date	string	Date verification request was sent to applicant (YYYY-MM-DD).
completed_date	string	Date verification request was completed by applicant (YYYY-MM-DD).
report_url	string	Url to of the income report pdf if it was completed otherwise null.
paystub_url	string	Url of the users paystub if they used to fallback option otherwise null

Sources Schema

Field	Type	Description
name	String	Name of the income source.
amount	number	Total income from source.
recurring	number	Total recurring income from source
non-recurring	number	Total non-recurring income from source

Accounts Schema

Field	Type	Description
account_id	string	Id for the account.
account_type	string	Type of account eg. Checking, Savings..
available_balance	number	Balance available for use.
current_balance	number	Balance unavailable for use.
bank	string	Name of financial institution the account is with.
account_name	string	Name of the account (e.g Freedom Saver etc)
average_balance	number	Average balance of the account between the period from_date and to_date.

Rent Payment History Schema

Field	Type	Description
amount	number	Rent amount paid by applicant.
date	string	Date of rent payment.