Skip to main content
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:
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