# 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. |
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.numaly.com/retrieving-reports-1/retrieving-reports.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.