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-2s, 1099s 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-2s, 1099s, 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-2s and 1099s 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

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-2s and 1099s 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.

{
  "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:

{
  "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.