Teal is the unified data layer for income and employment verification. Our API allows lenders, proptechs, and background screening platforms to instantly verify an applicant’s financial identity and affordability. Whether the data is retrieved automatically via Direct Connections, through a User Connection (payroll login), or extracted from an uploaded payslip via Doc Scan, Teal normalises the output into a single, standardised JSON schema. Write your underwriting logic once, and let Teal handle the data ingestion.

The Teal Ecosystem

Integrating with Teal typically involves a hybrid approach, leveraging our backend endpoints alongside our drop-in frontend and management tools.

1. Core API

The backbone of your integration. You will use our REST API from your secure backend to create user sessions, trigger frictionless Direct Connections, and retrieve the final, normalised JSON payloads. Note: For teams that want absolute control, you can bypass our UI entirely and build a custom native frontend that passes credentials directly to these endpoints. Explore the API Reference ->

2. Hosted webapp

The fastest path to live for interactive flows. Instead of building your own UI for payroll logins and document uploads, embed our conversion-tested modal into your frontend. The Webapp securely handles the employer search directory, consent screens, User Connections, and Doc Scan routing, seamlessly syncing the results back to your API.

3. The Teal Console

Your team’s command center. While your code talks to our API, your Risk, Operations, and Developer teams can log into the Teal Console. Use it to visually track applicant timelines, inspect raw parsed data, manage API keys, and configure your webhook endpoints without writing database queries.

How Teal Works

By default, Teal uses an intelligent waterfall approach to guarantee the highest possible conversion rate for your applicants. However, this routing is entirely configurable. You have the flexibility to enable or disable specific paths—such as turning off document uploads or restricting flows to Direct Connections only—to perfectly match your compliance and user experience requirements.

1. Direct Connections

The lowest-friction path. Where available, Teal interacts directly with payroll and HRIS systems via server-to-server APIs to instantly pull verified employment and income data without requiring the user to log in.

2. User Connections

If a direct API connection isn’t available, Teal prompts the user to securely authenticate with their employer or payroll provider. The user searches for their provider, enters their credentials, and Teal securely retrieves their verified history.

3. Doc Scan

If digital connections fail or the user cannot remember their credentials, Teal seamlessly falls back to document upload. Unlike generic OCR, Teal’s purpose-built extraction models interrogate the uploaded payslip’s metadata, validate the mathematics (Gross vs. Net), and check for pixel anomalies for a better assessment.

Real-Time Updates via Webhooks

To keep your application in sync without continuous polling, Teal provides secure Webhooks. As soon as an applicant’s data is processed—whether from an API connection or a parsed document—we instantly fire a user-payroll-submitted event to your backend. Our webhooks support HMAC-SHA512 signature verification and AES/GCM payload encryption, ensuring that sensitive financial data is transmitted with enterprise-grade security. Learn more about Webhooks ->

Standardized Output

Regardless of which path the user takes in the waterfall, the data always arrives in your system normalized into the exact same schema. Here is an example of what you will receive:

{
  "payroll_submissions": [
    {
      "id": "8f3b2a1c-9d4e-48b2-b1c3-7f6e5d4c3b2a",
      "account_id": "c9a8b7c6-d5e4-4f3a-9b2c-1d0e9f8a7b6c",
      "entry_id": "e5d4c3b2-a1b2-4c3d-8e7f-6a5b4c3d2e1f",
      "created_at": "2023-11-28T08:15:32.000Z",
      "identity_information": {
        "name": "David Sterling",
        "date_of_birth": "1988-08-22T00:00:00.000Z",
        "address": {
          "street": "42 Highfield Road",
          "county": "Greater Manchester",
          "city": "Manchester",
          "post_code": "M19 3LW",
          "country": "United Kingdom"
        },
        "email": "david.sterling@techflow.co.uk",
        "phone": 447700900451,
        "NI_number": "JL654321D"
      },
      "employment_information": {
        "employer_name": "TechFlow Solutions Ltd",
        "role": "Senior Product Manager",
        "type": "Full_Time",
        "status": "Active",
        "start_date": "2020-03-15T00:00:00.000Z",
        "leave_date": null,
        "employer_tax_reference": "321/TF987",
        "is_director": false
      },
      "income_information": {
        "pay_date": "2023-11-28T00:00:00.000Z",
        "pay_interval_start": "2023-11-01T00:00:00.000Z",
        "pay_interval_end": "2023-11-30T00:00:00.000Z",
        "pay_frequency": "Monthly",
        "earnings": {
          "gross_pay": "5500.00",
          "net_pay": "3850.00",
          "base_salary": "5000.00",
          "bonus": "500.00",
          "fixed_pay_total": "5000.00",
          "variable_pay_total": "500.00",
          "earning_elements": [
            {
              "type": "Bonus",
              "amount": "500.00",
              "is_fixed": false,
              "is_after_tax": false,
              "is_after_ni": false,
              "is_bik": false
            }
          ],
          "year_to_date": {
            "gross_pay": "44000.00",
            "net_pay": "30800.00",
            "total_tax_paid": "7600.00",
            "total_ni_paid": "2800.00",
            "total_taxable_earnings": "44000.00",
            "tax_year": 2023
          },
          "rolling_12m_income": {
            "gross_pay": "66000.00",
            "net_pay": "46200.00"
          }
        },
        "deductions": {
          "income_tax": "950.00",
          "employee_ni": "350.00",
          "employee_pension": "350.00",
          "total_deductions": "1650.00",
          "loan_deductions": "0.00",
          "deductions_elements": [
            {
              "type": "Pension",
              "amount": "350.00"
            }
          ]
        },
        "tax_code": "1257L"
      }
    }
  ]
}

Next Steps

Ready to start building? Here is how to get your first test data flowing.

Get your API Keys: Contact our team at hello@goteal.co to schedule a quick intro call, and we will provision your Sandbox keys.
Explore the Sandbox: Learn how to use our test credentials to simulate successful User Connections, direct connections, and document uploads.

Get Started

Introduction

The Teal Ecosystem

1. Core API

2. Hosted webapp

3. The Teal Console

How Teal Works

1. Direct Connections

2. User Connections

3. Doc Scan

Real-Time Updates via Webhooks

Standardized Output

Next Steps

​The Teal Ecosystem

​1. Core API

​2. Hosted webapp

​3. The Teal Console

​How Teal Works

​1. Direct Connections

​2. User Connections

​3. Doc Scan

​Real-Time Updates via Webhooks

​Standardized Output

​Next Steps

The Teal Ecosystem

1. Core API

2. Hosted webapp

3. The Teal Console

How Teal Works

1. Direct Connections

2. User Connections

3. Doc Scan

Real-Time Updates via Webhooks

Standardized Output

Next Steps