Reports Upgrade Guide

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#

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.

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

1{
2  "id": "43a2c6c3-1e63-91e5-88e3-f9ab2dcc489b",
3  "user": "018051aa-f7a9-a0db-2f38-6cfa325e9d69",
4  "reference_id": "43a2c6c3-1e63-91e5-88e3-f9ab2dcc489b",
5  ...
6  "file_url": "www.argyle.com/storagename/file",
7  "json_url": "www.argyle.com/storagename.json",
8  ...
9}

1{
2  "id": "43a2c6c3-1e63-91e5-88e3-f9ab2dcc489b",
3  "user": "018051aa-f7a9-a0db-2f38-6cfa325e9d69",
4  "reference_id": "43a2c6c3-1e63-91e5-88e3-f9ab2dcc489b",
5  ...
6  "file_url": "www.argyle.com/storagename/pdf",
7  "json_url": "www.argyle.com/storagename/json",
8  ...
9}

Retrieving reports in JSON#

• 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:

Unmapped payroll documents#

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