> ## Documentation Index
> Fetch the complete documentation index at: https://docs.argyle.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Reports Upgrade Guide
> Upgrading to new reports.
See what's changed and learn how to upgrade to our new reports.
## Context
On June 2, 2025 Argyle's reports were upgraded to improve usability and clarity:
* **Updated report designs** — a cleaner, consistent format across all report types with employment details easier to access.
* **API updates** — a new process to generate reports and restructured report details centered around **employments** rather than accounts.
## Generating reports
On **October 6, 2025** the legacy endpoint — where `{type}` is not required as a path parameter — will stop receiving updates. After **January 5, 2026**, this legacy endpoint will be retired; all report generation must use the updated endpoint after this date.
### Key changes
1. Report `type` will now be required as a **path parameter** when [generating reports](/api-reference/reports#generate).
2. In the updated endpoint, `file_url` has been changed to a direct download link of the report PDF.
[Argyle authentication headers](/api-guide/overview#authentication) are now required to retrieve report PDFs via `file_url`
— Signed Google Cloud Storage links are no longer returned.
— The URL can no longer be accessed directly in a browser or automation script without the appropriate headers.
3. We have added a new `json_url` field to the response payloads. This link should be used to [retrieve reports in JSON](/reports-upgrade-guide#retrieving-reports-in-json).
[Argyle authentication headers](/api-guide/overview#authentication) are now required to retrieve report JSONs via `json_url`
### Legacy Endpoint
**Request example:**
* **POST** `https:api.argyle.com/v2/reports`
**Request body:**
* `user` (required) — ID of the user.
* `type` (required) — Type of report.
**Response payload:**
```json theme={}
{
"id": "43a2c6c3-1e63-91e5-88e3-f9ab2dcc489b",
"user": "018051aa-f7a9-a0db-2f38-6cfa325e9d69",
"reference_id": "43a2c6c3-1e63-91e5-88e3-f9ab2dcc489b",
...
"file_url": "www.argyle.com/storagename/file",
"json_url": "www.argyle.com/storagename.json",
...
}
```
### Updated Endpoint
**Request example:**
* **POST** `https:api.argyle.com/v2/reports/{type}`
**Request body:**
* `user` (required) — ID of the user
**Response payload:**
```json theme={}
{
"id": "43a2c6c3-1e63-91e5-88e3-f9ab2dcc489b",
"user": "018051aa-f7a9-a0db-2f38-6cfa325e9d69",
"reference_id": "43a2c6c3-1e63-91e5-88e3-f9ab2dcc489b",
...
"file_url": "www.argyle.com/storagename/pdf",
"json_url": "www.argyle.com/storagename/json",
...
}
```
## Retrieving reports in JSON
Only applicable if retrieving reports in JSON format.
* Report JSON's should now be retrieved using the value of `json_url` returned in the response payload after generating a report.
### Legacy Workflow
* Generate a report using **POST** `/v2/reports`
* Call **GET** `/v2/reports/{report_id}.json` to retrieve report JSON
### Updated Workflow
* Generate a report using **POST** `/v2/reports`
* Access the Report JSON using the value of `json_url` returned in the response payload
* Call **GET** `{json_url value}`
Argyle does not recommend but will also support calling **GET** `/v2/reports/{report_id}/json`
### Updated JSON Schema
Report JSON's have been re-oriented around employments rather than accounts:
```json theme={}
{
"type": "voe",
"report_id": "6c3fa756-2e76-43e1-55f6-e29fc6ae535d",
"user_id": "018051aa-f7a9-a0db-2f38-6cfa325e9d69",
"external_id": "March Connection",
"generated_at": "2023-03-26T09:19:08.916Z",
"last_synced_at": "2023-03-24T12:41:21.576Z",
"metadata": {},
"accounts": [
{
"account": "018728a3-afee-5288-8e8a-c68ceb591359",
"source": "Worknight",
"first_name": "Bob",
"last_name": "Jones",
"full_name": "Bob Jones",
"employer": "Whole Goods",
"employer_address": {
"city": "New York",
"country": "US",
"state": "NY",
"postal_code": "10014",
"line1": "852 North W St",
"line2": null
},
"status": "active",
"employment_type": "full-time",
"job_title": "Store Manager",
"original_hire_date": "2020-08-28",
"start_date": "2020-08-28",
"end_date": null,
"last_pay_period_end_date": "2023-03-22",
"last_paystub_date": "2023-03-24",
"ssn": "522-09-1191"
},
{
"account": "018728a2-2fe0-cdb4-9486-70b2fe9834f9",
"source": "Bullseye",
"first_name": "Bob",
"last_name": "Jones",
"full_name": "Bob Jones",
"employer": "Bullseye",
"employer_address": {
"city": "New York",
"country": "US",
"state": "NY",
"postal_code": "10014",
"line1": "119 Green Ridge",
"line2": null
},
"status": "active",
"employment_type": "part-time",
"job_title": "Clerk",
"original_hire_date": "2020-06-29",
"start_date": "2020-06-29",
"end_date": null,
"last_pay_period_end_date": "2023-02-23",
"last_paystub_date": "2023-02-24",
"ssn": "522-09-1191"
}
]
}
```
```json theme={}
{
"report_id": "6c3fa756-2e76-43e1-55f6-e29fc6ae535d",
"type": "voe",
"user_id": "018051aa-f7a9-a0db-2f38-6cfa325e9d69",
"external_id": "March Connection",
"created_at": "2023-03-26T09:19:08.916Z",
"last_synced_at": "2023-03-24T12:41:21.576Z",
"metadata": {},
"employments": [
{
"employment": "0186a27d-e5c6-735a-a359-6315b34d544c",
"account": "0187c66e-e7e5-811c-b006-2232f00f426a",
"last_synced_at": "2023-03-09T14:08:25.069Z",
"source": "Worknight",
"first_name": "Bob",
"last_name": "Jones",
"full_name": "Bob Jones",
"ssn": "522-09-1191",
"employer": "Whole Goods",
"employer_address": {
"line1": "852 North W St",
"line2": null,
"city": "New York",
"state": "NY",
"postal_code": "10014",
"country": "US"
},
"status": "active",
"employment_type": "full-time",
"job_title": "Store Manager",
"start_date": "2020-08-28",
"original_hire_date": "2020-08-28",
"end_date": null,
"length_of_work": {
"years": "2",
"months": "6"
},
"last_pay_period_end_date": "2023-03-22",
"last_paystub_date": "2023-03-24"
},
{
"employment": "0185a31d-e2c8-991c-a251-5977e36a418c",
"account": "018728a2-2fe0-cdb4-9486-70b2fe9834f9",
"last_synced_at": "2023-03-01T05:10:59.558Z",
"source": "Bullseye",
"first_name": "Bob",
"last_name": "Jones",
"full_name": "Bob Jones",
"ssn": "522-09-1191",
"employer": "Bullseye",
"employer_address": {
"line1": "119 Green Ridge",
"line2": null,
"city": "New York",
"state": "NY",
"postal_code": "10014",
"country": "US"
},
"status": "active",
"employment_type": "part-time",
"job_title": "Clerk",
"start_date": "2020-06-29",
"original_hire_date": "2020-06-29",
"end_date": null,
"length_of_work": {
"years": "2",
"months": "9"
},
"last_pay_period_end_date": "2023-02-23",
"last_paystub_date": "2023-02-24"
}
]
}
```
```json theme={}
{
"type": "voie",
"report_id": "6da4c9a3-2e63-95e5-8be3-f9a52ddc489a",
"user_id": "018051aa-f7a9-a0db-2f38-6cfa325e9d69",
"external_id": "March Connection",
"generated_at": "2023-03-26T09:20:06.081Z",
"last_synced_at": "2023-03-24T12:41:25.069Z",
"metadata": {},
"accounts": [
{
"account": "018728a3-afee-5288-8e8a-c68ceb591359",
"source": "Worknight",
"first_name": "Bob",
"last_name": "Jones",
"full_name": "Bob Jones",
"birth_date": "1980-10-10",
"phone_number": "+18009000010",
"email": "bob@email.com",
"employer": "Whole Goods",
"employee_address": {
"city": "New York",
"country": "US",
"state": "NY",
"postal_code": "10014",
"line1": "342 Fence Rd",
"line2": null
},
"employer_address": {
"city": "New York",
"country": "US",
"state": "NY",
"postal_code": "10014",
"line1": "852 North W St",
"line2": null
},
"status": "active",
"employment_type": "full-time",
"job_title": "Store Manager",
"original_hire_date": "2020-08-28",
"start_date": "2020-08-28",
"end_date": null,
"last_pay_period_end_date": "2023-03-22",
"last_paystub_date": "2023-03-24",
"base_pay": {
"amount": "75372.62",
"currency": "USD",
"period": "annual"
},
"pay_cycle": "monthly",
"income": [
{
"gross_pay": {
"total": 25124.2,
"base": 25124.2,
"overtime": 0,
"commission": 0,
"bonus": 0,
"other": 0
},
"employer": "Whole Goods",
"period": "2023",
"currency": "USD",
"reimbursements": 8.13,
"deductions": 816.53,
"taxes": 5715.75,
"fees": 0,
"net_pay": 18600.05
},
{
"gross_pay": {
"total": 82866.32,
"base": 81653.65,
"overtime": 0,
"commission": 881.09,
"bonus": 331.58,
"other": 0
},
"employer": "Whole Goods",
"period": "2022",
"currency": "USD",
"reimbursements": 4.35,
"deductions": 3266.12,
"taxes": 14948.85,
"fees": 0,
"net_pay": 64655.7
},
{
"gross_pay": {
"total": 87854.76,
"base": 81653.65,
"overtime": 5774.51,
"commission": 426.6,
"bonus": 0,
"other": 0
},
"employer": "Whole Goods",
"period": "2021",
"currency": "USD",
"reimbursements": 26.6,
"deductions": 3328.93,
"taxes": 16833.19,
"fees": 0,
"net_pay": 67719.24
}
],
"ssn": "522-09-1191"
},
{
"account": "018728a2-2fe0-cdb4-9486-70b2fe9834f9",
"source": "Bullseye",
"first_name": "Bob",
"last_name": "Jones",
"full_name": "Bob Jones",
"birth_date": "1980-10-10",
"phone_number": "+18009000010",
"email": "bob@email.com",
"employer": "Bullseye",
"employee_address": {
"city": "New York",
"country": "US",
"state": "NY",
"postal_code": "10014",
"line1": "342 Fence Rd",
"line2": null
},
"employer_address": {
"city": "New York",
"country": "US",
"state": "NY",
"postal_code": "10014",
"line1": "119 Green Ridge",
"line2": null
},
"status": "active",
"employment_type": "part-time",
"job_title": "Clerk",
"original_hire_date": "2020-06-29",
"start_date": "2020-06-29",
"end_date": null,
"last_pay_period_end_date": "2023-02-23",
"last_paystub_date": "2023-02-24",
"base_pay": {
"amount": "61030.57",
"currency": "USD",
"period": "annual"
},
"pay_cycle": "monthly",
"income": [
{
"gross_pay": {
"total": 20848.92,
"base": 20343.52,
"overtime": 0,
"commission": 0,
"bonus": 505.4,
"other": 0
},
"employer": "Bullseye",
"period": "2023",
"currency": "USD",
"reimbursements": 0,
"deductions": 915.48,
"taxes": 4475.58,
"fees": 0,
"net_pay": 15457.86
},
{
"gross_pay": {
"total": 68070.08,
"base": 66116.44,
"overtime": 0,
"commission": 777.54,
"bonus": 1176.1,
"other": 0
},
"employer": "Bullseye",
"period": "2022",
"currency": "USD",
"reimbursements": 18.4,
"deductions": 2034.4,
"taxes": 13274.18,
"fees": 0,
"net_pay": 52779.9
},
{
"gross_pay": {
"total": 68378.52,
"base": 66116.44,
"overtime": 0,
"commission": 641.94,
"bonus": 1620.14,
"other": 0
},
"employer": "Bullseye",
"period": "2021",
"currency": "USD",
"reimbursements": 20.27,
"deductions": 1881.82,
"taxes": 13731.92,
"fees": 0,
"net_pay": 52785.05
}
],
"ssn": "522-09-1191"
}
],
"income_totals": [
{
"period": "2023",
"period_total": {
"gross_pay": {
"total": 45973.12,
"base": 45467.72,
"overtime": 0,
"commission": 0,
"bonus": 505.4,
"other": 0
},
"currency": "USD",
"reimbursements": 8.13,
"deductions": 1732.01,
"taxes": 10191.33,
"fees": 0,
"net_pay": 34057.91
}
},
{
"period": "2022",
"period_total": {
"gross_pay": {
"total": 150936.4,
"base": 147770.09,
"overtime": 0,
"commission": 1658.63,
"bonus": 1507.68,
"other": 0
},
"currency": "USD",
"reimbursements": 22.75,
"deductions": 5300.52,
"taxes": 28223.03,
"fees": 0,
"net_pay": 117435.6
}
},
{
"period": "2021",
"period_total": {
"gross_pay": {
"total": 156233.28,
"base": 147770.09,
"overtime": 5774.51,
"commission": 1068.54,
"bonus": 1620.14,
"other": 0
},
"currency": "USD",
"reimbursements": 46.87,
"deductions": 5210.75,
"taxes": 30565.11,
"fees": 0,
"net_pay": 120504.29
}
}
]
}
```
```json theme={}
{
"report_id": "6da4c9a3-2e63-95e5-8be3-f9a52ddc489a",
"type": "voie",
"user_id": "018051aa-f7a9-a0db-2f38-6cfa325e9d69",
"external_id": "March Connection",
"created_at": "2023-03-26T09:20:06.081Z",
"last_synced_at": "2023-03-24T12:41:25.069Z",
"metadata": {},
"employments": [
{
"employment": "0186a27d-e5c6-735a-a359-6315b34d544c",
"account": "018728a3-afee-5288-8e8a-c68ceb591359",
"last_synced_at": "2023-03-09T14:08:25.069Z",
"source": "Worknight",
"first_name": "Bob",
"last_name": "Jones",
"full_name": "Bob Jones",
"birth_date": "1980-10-10",
"ssn": "522-09-1191",
"phone_number": "+18009000010",
"email": "bob@email.com",
"employee_address": {
"line1": "342 Fence Rd",
"line2": null,
"city": "New York",
"state": "NY",
"postal_code": "10014",
"country": "US"
},
"employer": "Whole Goods",
"employer_address": {
"line1": "852 North W St",
"line2": null,
"city": "New York",
"state": "NY",
"postal_code": "10014",
"country": "US"
},
"status": "active",
"employment_type": "full-time",
"job_title": "Store Manager",
"base_pay": {
"amount": "75372.62",
"currency": "USD",
"period": "annual"
},
"pay_cycle": "monthly",
"start_date": "2020-08-28",
"original_hire_date": "2020-08-28",
"end_date": null,
"length_of_work": {
"years": "2",
"months": "6"
},
"last_pay_period_end_date": "2023-03-22",
"last_paystub_date": "2023-03-24",
"income": [
{
"period": "2023",
"currency": "USD",
"gross_pay": {
"total": "25124.20",
"base": "25124.20",
"overtime": "0.00",
"commission": "0.00",
"bonus": "0.00",
"other": "0.00"
},
"reimbursements": "8.13",
"deductions": "816.53",
"taxes": "5715.75",
"fees": "0.00",
"net_pay": "18600.05"
},
{
"period": "2022",
"currency": "USD",
"gross_pay": {
"total": "82866.32",
"base": "81653.65",
"overtime": "0.00",
"commission": "881.09",
"bonus": "331.58",
"other": "0.00"
},
"reimbursements": "4.35",
"deductions": "3266.12",
"taxes": "14948.85",
"fees": "0.00",
"net_pay": "64655.70"
}
],
"monthly_income": {
"argyle": {
"total": "7102.33",
"base": "6902.55",
"overtime": "165.94",
"bonus": "5.22",
"commission": "28.62",
"other": "0.00"
}
},
"callouts": []
},
{
"employment": "0185a31d-e2c8-991c-a251-5977e36a418c",
"account": "018728a2-2fe0-cdb4-9486-70b2fe9834f9",
"last_synced_at": "2023-03-01T05:10:59.558Z",
"source": "Bullseye",
"first_name": "Bob",
"last_name": "Jones",
"full_name": "Bob Jones",
"birth_date": "1980-10-10",
"ssn": "522-09-1191",
"phone_number": "+18009000010",
"email": "bob@email.com",
"employee_address": {
"line1": "342 Fence Rd",
"line2": null,
"city": "New York",
"state": "NY",
"postal_code": "10014",
"country": "US"
},
"employer": "Bullseye",
"employer_address": {
"line1": "119 Green Ridge",
"line2": null,
"city": "New York",
"state": "NY",
"postal_code": "10014",
"country": "US"
},
"status": "active",
"employment_type": "part-time",
"job_title": "Clerk",
"base_pay": {
"amount": "61030.57",
"currency": "USD",
"period": "annual"
},
"pay_cycle": "monthly",
"start_date": "2020-06-29",
"original_hire_date": "2020-06-29",
"end_date": null,
"length_of_work": {
"years": "2",
"months": "9"
},
"last_pay_period_end_date": "2023-02-23",
"last_paystub_date": "2023-02-24",
"income": [
{
"period": "2023",
"currency": "USD",
"gross_pay": {
"total": "20848.92",
"base": "20343.52",
"overtime": "0.00",
"commission": "0.00",
"bonus": "505.40",
"other": "0.00"
},
"reimbursements": "0.00",
"deductions": "915.48",
"taxes": "4475.58",
"fees": "0.00",
"net_pay": "15457.86"
},
{
"period": "2022",
"currency": "USD",
"gross_pay": {
"total": "68070.08",
"base": "66116.44",
"overtime": "0.00",
"commission": "777.54",
"bonus": "1176.10",
"other": "0.00"
},
"reimbursements": "18.40",
"deductions": "2034.40",
"taxes": "13274.18",
"fees": "0.00",
"net_pay": "52779.90"
}
],
"monthly_income": {
"argyle": {
"total": "5683.51",
"base": "5512.92",
"overtime": "0.00",
"bonus": "119.51",
"commission": "51.08",
"other": "0.00"
}
},
"callouts": []
}
],
"income_totals": [
{
"period": "2023",
"currency": "USD",
"gross_pay": {
"total": "45973.12",
"base": "45467.72",
"overtime": "0.00",
"commission": "0.00",
"bonus": "505.40",
"other": "0.00"
},
"reimbursements": "8.13",
"deductions": "1732.01",
"taxes": "10191.33",
"fees": "0.00",
"net_pay": "34057.91"
},
{
"period": "2022",
"currency": "USD",
"gross_pay": {
"total": "150936.4",
"base": "147770.09",
"overtime": "0.00",
"commission": "1658.63",
"bonus": "1507.68",
"other": "0.00"
},
"reimbursements": "22.75",
"deductions": "5300.52",
"taxes": "28223.03",
"fees": "0.00",
"net_pay": "117435.60"
}
]
}
```
```json theme={}
{
"type": "voe-mortgage",
"report_id": "6c3fa756-2e76-43e1-55f6-e29fc6ae535d",
"user_id": "018051aa-f7a9-a0db-2f38-6cfa325e9d69",
"external_id": "March Connection",
"generated_at": "2023-03-26T09:19:08.916Z",
"last_synced_at": "2023-03-24T12:41:21.576Z",
"d1c_id": "6c3fa756-2e76-43e1-55f6-e29fc6ae535d",
"metadata": {
"d1c_report": {
"id": "6c3fa756-2e76-43e1-55f6-e29fc6ae535d",
"ssn": "522-09-1191",
"accounts": [
"018728a3-afee-5288-8e8a-c68ceb591359",
"018728a2-2fe0-cdb4-9486-70b2fe9834f9"
]
},
"aim_report": {
"id": "6c3fa756-2e76-43e1-55f6-e29fc6ae535d",
"ssn": "522-09-1191",
"accounts": [
"018728a3-afee-5288-8e8a-c68ceb591359",
"018728a2-2fe0-cdb4-9486-70b2fe9834f9"
]
}
},
"accounts": [
{
"account": "018728a3-afee-5288-8e8a-c68ceb591359",
"source": "Worknight",
"first_name": "Bob",
"last_name": "Jones",
"full_name": "Bob Jones",
"employer": "Whole Goods",
"employer_address": {
"city": "New York",
"country": "US",
"state": "NY",
"postal_code": "10014",
"line1": "852 North W St",
"line2": null
},
"status": "active",
"employment_type": "full-time",
"job_title": "Store Manager",
"original_hire_date": "2020-08-28",
"start_date": "2020-08-28",
"end_date": null,
"last_pay_period_end_date": "2023-03-22",
"last_paystub_date": "2023-03-24",
"ssn": "522-09-1191"
},
{
"account": "018728a2-2fe0-cdb4-9486-70b2fe9834f9",
"source": "Bullseye",
"first_name": "Bob",
"last_name": "Jones",
"full_name": "Bob Jones",
"employer": "Bullseye",
"employer_address": {
"city": "New York",
"country": "US",
"state": "NY",
"postal_code": "10014",
"line1": "119 Green Ridge",
"line2": null
},
"status": "active",
"employment_type": "part-time",
"job_title": "Clerk",
"original_hire_date": "2020-06-29",
"start_date": "2020-06-29",
"end_date": null,
"last_pay_period_end_date": "2023-02-23",
"last_paystub_date": "2023-02-24",
"ssn": "522-09-1191"
}
]
}
```
```json theme={}
{
"report_id": "6c3fa756-2e76-43e1-55f6-e29fc6ae535d",
"type": "voe-mortgage",
"user_id": "018051aa-f7a9-a0db-2f38-6cfa325e9d69",
"external_id": "March Connection",
"created_at": "2023-03-26T09:19:08.916Z",
"last_synced_at": "2023-03-24T12:41:21.576Z",
"metadata": {
"aim_report": {
"status": "available",
"accounts": [
"0187c66e-e7e5-811c-b006-2232f00f426a",
"018728a2-2fe0-cdb4-9486-70b2fe9834f9"
],
"employments": [
"0186a27d-e5c6-735a-a359-6315b34d544c",
"0185a31d-e2c8-991c-a251-5977e36a418c"
]
},
"d1c_report": {
"status": "available",
"accounts": [
"0187c66e-e7e5-811c-b006-2232f00f426a",
"018728a2-2fe0-cdb4-9486-70b2fe9834f9"
],
"employments": [
"0186a27d-e5c6-735a-a359-6315b34d544c",
"0185a31d-e2c8-991c-a251-5977e36a418c"
]
}
},
"employments": [
{
"employment": "0186a27d-e5c6-735a-a359-6315b34d544c",
"account": "0187c66e-e7e5-811c-b006-2232f00f426a",
"last_synced_at": "2023-03-09T14:08:25.069Z",
"source": "Worknight",
"first_name": "Bob",
"last_name": "Jones",
"full_name": "Bob Jones",
"ssn": "522-09-1191",
"employer": "Whole Goods",
"employer_address": {
"line1": "852 North W St",
"line2": null,
"city": "New York",
"state": "NY",
"postal_code": "10014",
"country": "US"
},
"status": "active",
"employment_type": "full-time",
"job_title": "Store Manager",
"start_date": "2020-08-28",
"original_hire_date": "2020-08-28",
"end_date": null,
"length_of_work": {
"years": "2",
"months": "6"
},
"last_pay_period_end_date": "2023-03-22",
"last_paystub_date": "2023-03-24"
},
{
"employment": "0185a31d-e2c8-991c-a251-5977e36a418c",
"account": "018728a2-2fe0-cdb4-9486-70b2fe9834f9",
"last_synced_at": "2023-03-01T05:10:59.558Z",
"source": "Bullseye",
"first_name": "Bob",
"last_name": "Jones",
"full_name": "Bob Jones",
"ssn": "522-09-1191",
"employer": "Bullseye",
"employer_address": {
"line1": "119 Green Ridge",
"line2": null,
"city": "New York",
"state": "NY",
"postal_code": "10014",
"country": "US"
},
"status": "active",
"employment_type": "part-time",
"job_title": "Clerk",
"start_date": "2020-06-29",
"original_hire_date": "2020-06-29",
"end_date": null,
"length_of_work": {
"years": "2",
"months": "9"
},
"last_pay_period_end_date": "2023-02-23",
"last_paystub_date": "2023-02-24"
}
]
}
```
```json theme={}
{
"type": "voie-mortgage",
"report_id": "6da4c9a3-2e63-95e5-8be3-f9a52ddc489a",
"user_id": "018051aa-f7a9-a0db-2f38-6cfa325e9d69",
"external_id": "March Connection",
"generated_at": "2023-03-26T09:20:06.081Z",
"last_synced_at": "2023-03-24T12:41:25.069Z",
"d1c_id": "6c3fa756-2e76-43e1-55f6-e29fc6ae535d",
"metadata": {
"d1c_report": {
"id": "6da4c9a3-2e63-95e5-8be3-f9a52ddc489a",
"ssn": "522-09-1191",
"accounts": [
"018728a3-afee-5288-8e8a-c68ceb591359",
"018728a2-2fe0-cdb4-9486-70b2fe9834f9"
]
},
"aim_report": {
"id": "6da4c9a3-2e63-95e5-8be3-f9a52ddc489a",
"ssn": "522-09-1191",
"accounts": [
"018728a3-afee-5288-8e8a-c68ceb591359",
"018728a2-2fe0-cdb4-9486-70b2fe9834f9"
]
}
},
"accounts": [
{
"account": "018728a3-afee-5288-8e8a-c68ceb591359",
"source": "Worknight",
"first_name": "Bob",
"last_name": "Jones",
"full_name": "Bob Jones",
"birth_date": "1980-10-10",
"phone_number": "+18009000010",
"email": "bob@email.com",
"employer": "Whole Goods",
"employee_address": {
"city": "New York",
"country": "US",
"state": "NY",
"postal_code": "10014",
"line1": "342 Fence Rd",
"line2": null
},
"employer_address": {
"city": "New York",
"country": "US",
"state": "NY",
"postal_code": "10014",
"line1": "852 North W St",
"line2": null
},
"status": "active",
"employment_type": "full-time",
"job_title": "Store Manager",
"original_hire_date": "2020-08-28",
"start_date": "2020-08-28",
"end_date": null,
"last_pay_period_end_date": "2023-03-22",
"last_paystub_date": "2023-03-24",
"base_pay": {
"amount": "75372.62",
"currency": "USD",
"period": "annual"
},
"pay_cycle": "monthly",
"income": [
{
"employer": "Whole Goods",
"gross_pay": {
"total": 25124.2,
"base": 25124.2,
"overtime": 0,
"commission": 0,
"bonus": 0,
"other": 0
},
"period": "2023",
"currency": "USD"
},
{
"employer": "Whole Goods",
"gross_pay": {
"total": 82866.32,
"base": 81653.65,
"overtime": 0,
"commission": 881.09,
"bonus": 331.58,
"other": 0
},
"period": "2022",
"currency": "USD"
},
{
"employer": "Whole Goods",
"gross_pay": {
"total": 87854.76,
"base": 81653.65,
"overtime": 5774.51,
"commission": 426.6,
"bonus": 0,
"other": 0
},
"period": "2021",
"currency": "USD"
}
],
"ssn": "522-09-1191"
},
{
"account": "018728a2-2fe0-cdb4-9486-70b2fe9834f9",
"source": "Bullseye",
"first_name": "Bob",
"last_name": "Jones",
"full_name": "Bob Jones",
"birth_date": "1980-10-10",
"phone_number": "+18009000010",
"email": "bob@email.com",
"employer": "Bullseye",
"employee_address": {
"city": "New York",
"country": "US",
"state": "NY",
"postal_code": "10014",
"line1": "342 Fence Rd",
"line2": null
},
"employer_address": {
"city": "New York",
"country": "US",
"state": "NY",
"postal_code": "10014",
"line1": "119 Green Ridge",
"line2": null
},
"status": "active",
"employment_type": "part-time",
"job_title": "Clerk",
"original_hire_date": "2020-06-29",
"start_date": "2020-06-29",
"end_date": null,
"last_pay_period_end_date": "2023-02-23",
"last_paystub_date": "2023-02-24",
"base_pay": {
"amount": "61030.57",
"currency": "USD",
"period": "annual"
},
"pay_cycle": "monthly",
"income": [
{
"employer": "Bullseye",
"gross_pay": {
"total": 20848.92,
"base": 20343.52,
"overtime": 0,
"commission": 0,
"bonus": 505.4,
"other": 0
},
"period": "2023",
"currency": "USD"
},
{
"employer": "Bullseye",
"gross_pay": {
"total": 68070.08,
"base": 66116.44,
"overtime": 0,
"commission": 777.54,
"bonus": 1176.1,
"other": 0
},
"period": "2022",
"currency": "USD"
},
{
"employer": "Bullseye",
"gross_pay": {
"total": 68378.52,
"base": 66116.44,
"overtime": 0,
"commission": 641.94,
"bonus": 1620.14,
"other": 0
},
"period": "2021",
"currency": "USD"
}
],
"ssn": "522-09-1191"
}
],
"income_totals": [
{
"period": "2023",
"period_total": {
"gross_pay": {
"total": 45973.12,
"base": 45467.72,
"overtime": 0,
"commission": 0,
"bonus": 505.4,
"other": 0
},
"currency": "USD"
}
},
{
"period": "2022",
"period_total": {
"gross_pay": {
"total": 150936.4,
"base": 147770.09,
"overtime": 0,
"commission": 1658.63,
"bonus": 1507.68,
"other": 0
},
"currency": "USD"
}
},
{
"period": "2021",
"period_total": {
"gross_pay": {
"total": 156233.28,
"base": 147770.09,
"overtime": 5774.51,
"commission": 1068.54,
"bonus": 1620.14,
"other": 0
},
"currency": "USD"
}
}
]
}
```
```json theme={}
{
"report_id": "6da4c9a3-2e63-95e5-8be3-f9a52ddc489a",
"type": "voie-mortgage",
"user_id": "018051aa-f7a9-a0db-2f38-6cfa325e9d69",
"external_id": "March Connection",
"created_at": "2023-03-26T09:20:06.081Z",
"last_synced_at": "2023-03-24T12:41:25.069Z",
"metadata": {
"aim_report": {
"status": "available",
"accounts": [
"018728a3-afee-5288-8e8a-c68ceb591359",
"018728a2-2fe0-cdb4-9486-70b2fe9834f9"
],
"employments": [
"0186a27d-e5c6-735a-a359-6315b34d544c",
"0185a31d-e2c8-991c-a251-5977e36a418c"
]
},
"d1c_report": {
"status": "available",
"accounts": [
"018728a3-afee-5288-8e8a-c68ceb591359",
"018728a2-2fe0-cdb4-9486-70b2fe9834f9"
],
"employments": [
"0186a27d-e5c6-735a-a359-6315b34d544c",
"0185a31d-e2c8-991c-a251-5977e36a418c"
]
}
},
"employments": [
{
"employment": "0186a27d-e5c6-735a-a359-6315b34d544c",
"account": "018728a3-afee-5288-8e8a-c68ceb591359",
"last_synced_at": "2023-03-09T14:08:25.069Z",
"source": "Worknight",
"first_name": "Bob",
"last_name": "Jones",
"full_name": "Bob Jones",
"birth_date": "1980-10-10",
"ssn": "522-09-1191",
"phone_number": "+18009000010",
"email": "bob@email.com",
"employee_address": {
"line1": "342 Fence Rd",
"line2": null,
"city": "New York",
"state": "NY",
"postal_code": "10014",
"country": "US"
},
"employer": "Whole Goods",
"employer_address": {
"line1": "852 North W St",
"line2": null,
"city": "New York",
"state": "NY",
"postal_code": "10014",
"country": "US"
},
"status": "active",
"employment_type": "full-time",
"job_title": "Store Manager",
"base_pay": {
"amount": "75372.62",
"currency": "USD",
"period": "annual"
},
"pay_cycle": "monthly",
"start_date": "2020-08-28",
"original_hire_date": "2020-08-28",
"end_date": null,
"length_of_work": {
"years": "2",
"months": "6"
},
"last_pay_period_end_date": "2023-03-22",
"last_paystub_date": "2023-03-24",
"income": [
{
"period": "2023",
"currency": "USD",
"gross_pay": {
"total": "25124.20",
"base": "25124.20",
"overtime": "0.00",
"commission": "0.00",
"bonus": "0.00",
"other": "0.00"
}
},
{
"period": "2022",
"currency": "USD",
"gross_pay": {
"total": "82866.32",
"base": "81653.65",
"overtime": "0.00",
"commission": "881.09",
"bonus": "331.58",
"other": "0.00"
}
},
{
"period": "2021",
"currency": "USD",
"gross_pay": {
"total": "87854.76",
"base": "81653.65",
"overtime": "5774.51",
"commission": "426.60",
"bonus": "0.00",
"other": "0.00"
}
}
],
"monthly_income": {
"argyle": {
"total": "7102.33",
"base": "6902.55",
"overtime": "165.94",
"bonus": "5.22",
"commission": "28.62",
"other": "0.00"
}
},
"callouts": []
},
{
"employment": "0185a31d-e2c8-991c-a251-5977e36a418c",
"account": "018728a2-2fe0-cdb4-9486-70b2fe9834f9",
"last_synced_at": "2023-03-01T05:10:59.558Z",
"source": "Bullseye",
"first_name": "Bob",
"last_name": "Jones",
"full_name": "Bob Jones",
"birth_date": "1980-10-10",
"ssn": "522-09-1191",
"phone_number": "+18009000010",
"email": "bob@email.com",
"employee_address": {
"line1": "342 Fence Rd",
"line2": null,
"city": "New York",
"state": "NY",
"postal_code": "10014",
"country": "US"
},
"employer": "Bullseye",
"employer_address": {
"line1": "119 Green Ridge",
"line2": null,
"city": "New York",
"state": "NY",
"postal_code": "10014",
"country": "US"
},
"status": "active",
"employment_type": "part-time",
"job_title": "Clerk",
"base_pay": {
"amount": "61030.57",
"currency": "USD",
"period": "annual"
},
"pay_cycle": "monthly",
"start_date": "2020-06-29",
"original_hire_date": "2020-06-29",
"end_date": null,
"length_of_work": {
"years": "2",
"months": "9"
},
"last_pay_period_end_date": "2023-02-23",
"last_paystub_date": "2023-02-24",
"income": [
{
"period": "2023",
"currency": "USD",
"gross_pay": {
"total": "20848.92",
"base": "20343.52",
"overtime": "0.00",
"commission": "0.00",
"bonus": "505.40",
"other": "0.00"
}
},
{
"period": "2022",
"currency": "USD",
"gross_pay": {
"total": "68070.08",
"base": "66116.44",
"overtime": "0.00",
"commission": "777.54",
"bonus": "1176.10",
"other": "0.00"
}
},
{
"period": "2021",
"currency": "USD",
"gross_pay": {
"total": "68378.52",
"base": "66116.44",
"overtime": "0.00",
"commission": "641.94",
"bonus": "1620.14",
"other": "0.00"
}
}
],
"monthly_income": {
"argyle": {
"total": "5683.51",
"base": "5512.92",
"overtime": "0.00",
"bonus": "119.51",
"commission": "51.08",
"other": "0.00"
}
},
"callouts": []
}
]
}
```
All changes:
1. The `accounts` array has been restructured as an `employments` array.
2. A new `created_at` field has been added.
3. The following fields have been added to the `employments` object:
* `employment` — unique employment ID
* `last_synced_at` — timestamp of when the employment was most recently scanned for new data prior to report generation
* `length_of_work` — object representing the number of `years` and `months` the user has been employed at this employment
* `monthly_income` — object containing Argyle's monthly income calculation for this employment (not available on report PDF)
4. The following adjustments have been made:
* The income period has been reduced from YTD + prior 2 years (e.g. 2025YTD, 2024, and 2023) to YTD + prior year (e.g. 2025YTD and 2024)
* Values within the `income` and `income_totals` objects have been changed from numbers to strings.
* When all nested values within an object are `null`, the object itself will return `null`. This impacts:
* Existing objects: `employee_address`, `employer_address`, and `base_pay`
* New objects: `length_of_work` and `monthly_income`
5. The following fields have been removed:
* `generated_at`
* `accounts.income.employer`
* `income_totals.period_total_gross_pay.{...}`
1. The `accounts` array has been restructured as an `employments` array.
2. A new `created_at` field has been added.
3. The following fields have been added to the `employments` object:
* `employment` — unique employment ID
* `last_synced_at` — timestamp of when the employment was most recently scanned for new data prior to report generation
* `length_of_work` — object representing the number of `years` and `months` the user has been employed at this employment
* `monthly_income` — object containing Argyle's monthly income calculation for this employment (not available on report PDF)
4. The following adjustments have been made:
* `metadata` has been updated to provide a consistent structure, regardless of GSE eligibility:
* `metadata.d1c_report.status` and `metadata.aim_report.status` represent the status of their respective GSE reports. Possible values:
* `available` — The report is eligible for GSE submission.
* `not eligible` — The report is not eligible for GSE submission.
* `metadata.d1c_report.accounts` and `metadata.aim_report.accounts` represent the account IDs contained in the GSE submission.
* `metadata.d1c_report.employments` and `metadata.aim_report.employments` represent the employment IDs contained in the GSE submission.
* Values within the `income` and `income_totals` objects have been changed from numbers to strings.
* When all nested values within an object are `null`, the object itself will return `null`. This impacts:
* Existing objects: `employee_address`, `employer_address`, and `base_pay`
* New objects: `length_of_work` and `monthly_income`
5. The following fields have been removed:
* `generated_at`
* `d1c_id`
* `metadata.d1c_report.id`
* `metadata.aim_report.id`
* `metadata.d1c_report.ssn`
* `metadata.aim_report.ssn`
* `accounts.income.employer`
* `income_totals`
## Unmapped payroll documents
Only applicable if retrieving documents using the `/v2/paystubs` or `/v2/payroll-documents` endpoints.
To ensure the highest data quality, Argyle's new reports only include data linked to **complete employment records** where information on identity, employment, and income is available.
* In rare cases (less than 5%), documents from multiple employments may be retrieved from a single connection if those employments share the same payroll system.
* If those documents are not mapped to a complete employment record, they are excluded from the new reports.
* These unmapped documents (e.g. paystubs, W-2s) can be identified if `paystubs.employment` or `payroll-documents.employment` are `null`, and can be filtered out when retrieving documents via either method below:
**Method 1: Pull documents by employment ID**
1. [List employments](/api-reference/employments#list) by user ID to retrieve a list of employment IDs
2. [List paystubs](/api-reference/paystubs#list) or [list payroll documents](/api-reference/payroll-documents#list) by these employment IDs
**Method 2: Filter out documents with `employment` = `null`**
1. [List paystubs](/api-reference/paystubs#list) or [list payroll documents](/api-reference/payroll-documents#list)
2. Ignore documents with `employment` = `null`