> For the complete documentation index, see [llms.txt](https://docs.numaly.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.numaly.com/retrieving-reports-1/retrieving-reports.md).
# Retrieve Report
## 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` |
{% tabs %}
{% tab title="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": "sarahsample@yahoo.com",
"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": {},
}
```
{% endtab %}
{% tab title="404 Request not found" %}
```
No response
```
{% endtab %}
{% endtabs %}
### 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. |