Document processing
Argyle supports an extensive data network, covering employers and payroll platforms across multiple sectors. With this coverage, it’s unlikely that your users won’t be able to connect to their payroll account programmatically through Argyle Link. However, if this does happen, Argyle provides several options to help your users upload documentation to verify their income. With built-in Document upload and two optical character recognition (OCR) alternatives (by Argyle or a third party), your users can upload paystubs, W-2s, and 1099s to verify their income and employment.
Document upload
Document upload lets users verify their income by uploading documents to Argyle Link. You can customize the user flow to best suit your business needs:
- Fallback flow user experience: provide an alternative income verification method when users fail to connect their accounts.
- Direct upload user experience: add an option for your users to upload documents directly.
After enabling document upload, users can upload PDF files such as W-2
s, 1099
s and paystubs
for income verification.
User experience flows
Read this section to learn more about user experience flows and customization for the Document upload feature.
Fallback user experience
If a user cannot find their income source or is unable to log into their payroll account, this experience enables them to upload W-2s, 1099s, and paystubs to verify their income.
This user flow is disabled by default. Use Link Customizer to enable this flow for users that are unable to connect their accounts or cannot find their income source.
If this flow is enabled, Argyle Link guides users to select and upload documents for income verification. This is what the process looks like:
Direct user experience
You can direct your users to the document upload screen with deep linking, giving you more flexibility when using Argyle for your income verification process. This option allows your users to upload their documents without logging in to their employer or payroll provider platform.
You can enable the deep linking user flow via Link Customizer in Console. Once enabled, Argyle Link guides users through the document upload process without asking them to connect their accounts. This is what the process looks like:
The Direct upload UX is supported starting from these Link SDK versions:
Android 4.2
iOS 4.2
React Native 4.2
Customize the user experience
Select the user flow that fits your business needs using the Link Customizer.
Enable document upload without requiring users to log in by selecting Document upload under Deep link experience.
Enable document upload for users who cannot find their income source or payroll provider using the ‘If no results’ experience.
Enable document upload after failed login using the ‘If login failed’ experience.
Use the Document upload settings screen to configure:
- Document upload options after unsuccessful login
- Document upload options without login requirements
- In-app texts for headers, descriptions, and buttons
- Accepted document types
- Requirement options for documents
- Minimum and/or maximum number of documents that users can upload
Implement Document upload
Follow the best practices in this section to help you make the most of your Document upload UX implementation.
Initialize Link with Direct upload UX
If you enable the Direct upload UX, you can direct your users to the document upload screen with deep linking. To initialize Argyle Link with this user flow, include the customizationId
of the Link Customization in your Link initialization.
To make this user flow available for returning users, you must also include a userToken
in your Link initialization.
Consult the Argyle Link Integration guide for more information.
Configure webhooks
Use webhooks to receive notifications when documents are uploaded or deleted by your users. You can subscribe to these webhooks:
forms.submitted
- triggered when the user submits the final page of the document upload form.forms.removed
- triggered when the user clicks the Remove all documents button and all previously uploaded documents are deleted.
Consult the Webhooks reference for more information.
Configure callbacks
Configure the onDocumentsSubmitted
callback to trigger additional actions when a document is uploaded.
Retrieve uploaded documents
Use Console to view the documents uploaded by your users. On the Your users page, select the user whose documents you wish to see and and click the Documents tab.
You can also retrieve uploaded documents via the /forms
endpoint.
Consult the API reference for more information.
Set supported document types
You can customize which type of documents you want your users to upload in the Link Customizer. Argyle supports three document types for upload:
Paystub
: outlines the details of the user's pay for each pay period.W-2
: includes wage and salary information as well as federal, state, and other taxes that were withheld.1099
: is used to declare income other than wages, salaries, and tips.
Users can upload PDF files of their W-2
s, 1099
s, and paystubs
with a maximum size of 16 MB each. To avoid duplicate files, Argyle checks the file name and hash of the file before uploading. If the file is a duplicate, Argyle informs the user that a duplicate file has been selected.
Argyle protects your users’ data with customer-managed encryption keys for files.
Note that all files are checked for viruses. If a virus is found, the Argyle API rejects the affected files.
OCR by Argyle
Optical character recognition (OCR) converts uploaded or scanned W-2
and 1099
documents into machine-readable text, making them easier to review and unlocking auto-fill capabilities. This can accelerate your time to decide by bundling everything you need to move forward with Argyle, vs. needing to work with multiple vendors.
With webhooks, Argyle can notify you instantly whenever your user or their employer uploads a W-2
or 1099
on an ongoing basis, enabling you to make decisions based on the latest information available at all times.
This solution enables you to get data from W-2
and 1099
documents in two different scenarios:
- When they are manually uploaded by your users during document upload.
- When they are initially scanned by Argyle from a newly connected account, or when documents are added or updated through periodic scanning.
Implement OCR by Argyle
Argyle's built-in OCR service for scanned documents is enabled by default.
To enable OCR for uploaded documents, reach out to your respective Customer Success Manager, Account Executive, or [email protected].
View data returned by OCR
To see data retrieved through OCR processing, you can either list documents and list forms through the API, or check the Documents tab for a specific user within Console, where an OCR icon next to the uploaded or scanned documents indicates the completion of the OCR process.
You can also use Console to test Argyle's OCR solution. Enable Document upload using Link customizer and use Link to view OCR results for:
- Argyle's sample PDFs that are provided in the Supported document types reference
- Your own
W-2
s and1099
s in PDF format
Developer Tools
Use these reference pages to learn more about the API endpoints, webhooks, and form types used in the OCR for Documents solution:
- Documents and Forms endpoints
- Documents and Forms webhook references
- OCR Data fields and Supported document types
FAQs
Does this solution cover paystubs?
Paystubs are not currently supported.What file types can documents be uploaded in?
Currently, only PDF files are supported.How accurate is the output of OCR?
OCR for Documents can achieve 97% accuracy.How long does it take for OCR to process documents?
15 to 20 seconds per document.OCR by a third party
Integrating a third party OCR processor can function as:
- A fallback option when a user cannot connect to their payroll account
- A UX upgrade for existing document upload processes
Argyle allows your users to upload their W-2
forms, 1099
forms, and paystubs
through Argyle Link and utilize a third party OCR service to provide digitized data through Argyle’s /forms
endpoint.
Argyle also provides the built-in OCR for Documents solution to convert W-2
s and 1099
s into machine-readable text to improve automation and save your team’s time and energy. Refer to the OCR by Argyle for more information.
Implement OCR by a third party
Read this section to learn how to set up OCR by a third party.
Authentication
Argyle recommends creating a dedicated API key for this integration. Follow your third party provider's guidance to generate a dedicated API key and a secret.
Argyle stores credentials encrypted with Google KMS. Read more about how Argyle handles security and compliance here.
API data schema
The Argyle API passes data retrieved through OCR directly from your third party provider. This is what the process looks like:
You can retrieve data by calling Argyle’s /forms
endpoint. When retrieving forms by account ID, the Argyle API provides the digitized data in the optional ocr_data
object within the metadata
field. Refer to the your third party provider's documentation for detailed descriptions of each field within the ocr_data
object.
This example response demonstrates what the results of a successful OCR flow could look like. Keep in mind that this will vary depending on your third party provider and how they structure data.
Successful scenario when retrieving paystub data
{
"id":"3fa85f64-5717-4562-b3fc-2c963f66afa6",
"status":"SUBMITTED",
"data":{
"employer_name":"Jim's Hardware",
"payroll_platform":"MyADP",
"paystubs":[
{
"file_id":"017c8488-1854-7e7b-30e3-a5dffb532534",
"metadata":{
"ocr_data":{
"book_uuid":"89743732-85a5-4ae5-91e0-a2c451ccda58",
"uploaded_image_bucket_uuid":null,
"doc_uuid":"1ad00e85-06c2-4a71-9365-066b0cb80c45",
"doc_page_numbers":[
1
],
"uuid":"70a706b5-070e-41e5-98bb-323fc3617c06",
"employer":{
"name":"SAMPLE COMPANY NAME",
"address":{
"line1":null,
"line2":null,
"city":null,
"state_code":null,
"postal_code":null
}
},
"employee":{
"name":"EMPLOYEE NAME",
"address":{
"line1":null,
"line2":null,
"city":null,
"state_code":null,
"postal_code":null
},
"marital_status":"NOT LISTED",
"taxpayer_id":{
"id_type":"SSN",
"last_4_digits":"1234"
}
},
"employment_details":{
"hire_date":null,
"annual_salary":{
"amount":null,
"currency":null
},
"pay_basis":null,
"hourly_rate":{
"amount":null,
"currency":null
}
},
"paystub_details":{
"pay_period_start_date":"2018-02-07",
"pay_period_end_date":"2018-02-13",
"pay_date":"2018-02-14",
"paystub_provider":null,
"pay_frequency":"WEEKLY",
"pay_frequency_captured":"NOT LISTED"
},
"net_pay":{
"distribution_details":[
],
"totals":{
"description":"NET PAY",
"canonical_description":null,
"current_pay":{
"amount":"590.70",
"currency":"USD"
},
"ytd_pay":{
"amount":"4134.90",
"currency":"USD"
}
}
},
"earnings":{
"subtotals":[
{
"description":"GROSS EARNING",
"canonical_description":null,
"current_pay":{
"amount":"800.00",
"currency":"USD"
},
"ytd_pay":{
"amount":null,
"currency":null
},
"current_hours":"40.00",
"current_rate":"20.00"
}
],
"totals":[
{
"description":"INCOME",
"canonical_description":null,
"current_pay":{
"amount":"800.00",
"currency":"USD"
},
"ytd_pay":{
"amount":"5600.00",
"currency":"USD"
},
"current_hours":null
}
]
},
"deductions":{
"subtotals":[
{
"description":"STATE TAX",
"canonical_description":"STATE TAX",
"current_pay":{
"amount":"40.00",
"currency":"USD"
},
"ytd_pay":{
"amount":"280.00",
"currency":"USD"
}
},
{
"description":"FEDERAL TAX",
"canonical_description":"FEDERAL WITHHOLDINGS",
"current_pay":{
"amount":"108.10",
"currency":"USD"
},
"ytd_pay":{
"amount":"756.70",
"currency":"USD"
}
},
{
"description":"FICA SOCIAL SECURITY",
"canonical_description":"SOCIAL SECURITY EMPLOYEE TAX",
"current_pay":{
"amount":"49.60",
"currency":"USD"
},
"ytd_pay":{
"amount":"347.20",
"currency":"USD"
}
},
{
"description":"FICA-MEDICARE",
"canonical_description":"EMPLOYEE MEDICARE",
"current_pay":{
"amount":"11.60",
"currency":"USD"
},
"ytd_pay":{
"amount":"81.20",
"currency":"USD"
}
}
],
"totals":[
{
"description":"DEDUCTIONS",
"canonical_description":null,
"current_pay":{
"amount":"209.30",
"currency":"USD"
},
"ytd_pay":{
"amount":"1465.10",
"currency":"USD"
}
}
]
},
"status":"COMPLETED",
"rejection_reason":null
}
}
}
]
}
}
View data returned by OCR
To see data retrieved through the OCR process, you can also check the Documents tab for a specific user within Console, where an OCR icon next to the uploaded or scanned documents indicates the completion of the OCR process.
Error handling
Document processing errors
If an error occurs during document processing, the relevant error details are shown in the ocr_data
object under the metadata
field. The error
field indicates different problems.
Refer to Argyle's OCR errors reference for more information.
This example response provides details about a scenario where the user uploaded a document with invalid type:
Error scenario - invalid document type
{
"id":"3fa85f64-5717-4562-b3fc-2c963f66afa6",
"status":"SUBMITTED",
"data":{
"employer_name":"Jim's Hardware",
"payroll_platform":"MyADP",
"paystubs":[
{
"file_id":"017c8488-1854-7e7b-30e3-a5dffb532534",
"metadata":{
"ocr_data":{
"error": "unrecognized_document_type"
}
}
}
]
}
}
Authentication errors
Argyle monitors authentication errors. If your third party account authentication fails (for example, due to an invalid API key) and document processing cannot start, Argyle will notify you. Once the issue is resolved, the pending documents can be reprocessed.
Next steps
For more details, reach out to your respective Customer Success Manager, Account Executive, or the Support team.
Updated 13 days ago