Skip to main content

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.

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.
  2. In the updated endpoint, file_url has been changed to a direct download link of the report PDF.
Argyle authentication headers 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.
  1. We have added a new json_url field to the response payloads. This link should be used to retrieve reports in JSON.
Argyle authentication headers are now required to retrieve report JSONs via json_url

​
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.

​
Updated JSON Schema

Report JSON’s have been re-oriented around employments rather than accounts: 
{
    "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"
        }
    ]
}

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

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

{
    "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"
            }
        }
    ]
}
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)
  1. 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
  1. 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)
  1. 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
  1. 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 by user ID to retrieve a list of employment IDs
  2. List paystubs or list payroll documents by these employment IDs
Method 2: Filter out documents with employment = null
  1. List paystubs or list payroll documents
  2. Ignore documents with employment = null