Sandbox - Starter Kit

Introduction

The sandbox environment functions as a simulated version of the actual system, designed for testing and development purposes without interacting with real data.

This environment employs mock payroll providers and payslip readers in order to allow developers to evaluate the API interface without compromising real data privacy.

Setting Up for Testing

Before you begin testing, ensure you have the following:

An API key for authentication: please ask your Teal connection to supply you with an API key
A callback URL for receiving webhook notifications: generate your URL in webhook.site

1. Webhooks Setup `/webhooks`

Configure webhooks to receive notifications for events such as new payroll submissions.

curl --request POST \
  --url https://api.sandbox.goteal.co/webhooks \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '{
  "events": [
    "user-payroll-submitted",
    "user-payroll-created"
  ],
  "name": "user-payroll-submitted",
  "secret": "very-secret",
  "url": "https://webhooks.company.com"
}'

Response Example:

{
  "webhook_id": "95a0e70b-fe02-4f47-aef9-2efff279df71",
  "events": [
    "user-payroll-submitted",
    "user-payroll-created"
  ],
  "name": "user-payroll-submitted",
  "url": "https://webhooks.company.com",
  "created_at": "2019-05-17T00:00:00.000Z"
}

2. Create a user `/users`

Now you need to create a user selecting a user ID from the following users:

curl --request POST \
  --url https://api.sandbox.goteal.co/users \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '{
  "name": "John Smith",
  "email": "john.smith@company.com"
}'

The field email does not have to be a real email address. It can be the user’s identifier in your system.

Response Example:

{
  "user_id": "95a0e70b-fe02-4f47-aef9-2efff279df71",
  "name": "John Smith",
  "email": "john.smith@company.com",
  "created_at": "2019-05-17T00:00:00.000Z"
}

3. Generating a user token `/user-tokens`

After creating a webhook, generate a token to authenticate subsequent actions for that user. The token ensures that actions such as account connection and payslip uploads are securely attributed to the correct user.

curl --request POST \
  --url https://api.sandbox.goteal.co/user-tokens \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '{
  "user_id": "95a0e70b-fe02-4f47-aef9-2efff279df71"
}'

Response Example:

{
  "created_at": "2019-05-17T00:00:00.000Z",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoiOTVhMGU3MGItZmUwMi00ZjQ3LWFlZjktMmVmZmYyNzlkZjcxIiwiaWF0IjoxNTE2MjM5MDIyfQ.4S5J"
}

4. Connecting a Payroll Account `/accounts`

This simulates the user connecting their payroll account for automatic data retrieval.

curl --request POST \
  --url https://api.sandbox.goteal.co/accounts \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '{
  "user_id": "95a0e70b-fe02-4f47-aef9-2efff279df71",
  "password": "very-secret-password",
  "payroll_provider": "quickbooks",
  "user_name": "john.smith@company.com"
}'

Response Example:

{
  "account_id": "95a0e70b-fe02-4f47-aef9-2efff279df71",
  "created_at": "2019-05-17T00:00:00.000Z",
  "payroll_provider": "quickbooks",
  "user_name": "john.smith@company.com"
}

5. Retrieve submitted Payroll information `/entries/connections`

Retrieve payroll for a connected account.

curl --location --request POST 'https://api.sandbox.goteal.co/entries/connections' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjbGllbnRfbmFtZSI6InN5c19jbGllbnQxIiwidXNlcl9pZCI6IjU3YWRiMzg0LWE2ZGEtNGE1Ny05NThhLTU1ZDk5MzdjZWE0MyIsImlzcyI6ImFwcC5zYW5kYm94LmdvdGVhbC5jbyIsImV4cCI6MTcxNTM0NTI5MH0.IxgmSN4XAn7j2jbQu0npwLXQjEQVqcbjmIBO2T-NCAc' \
--header 'Content-Type: application/json' \
--data-raw '{
    "account_id" : 552300dd-1e91-48d4-958b-41736c2c0167
}'

Response Example:

{
    "account_id": "552300dd-1e91-48d4-958b-41736c2c0167",
    "entry_id": "bdc420fe-5e48-4802-a753-659979a2a346",
    "payroll_submissions": [
        {
            "id": "0187c66e-e7e5-811c-b006-2232f00f426a",
            "account_id": "552300dd-1e91-48d4-958b-41736c2c0167",
            "entry_id": "bdc420fe-5e48-4802-a753-659979a2a346",
            "created_at": "2024-05-03T14:00:13.804Z",
            "identity_information": {
                "name": "Jane Doe",
                "date_of_birth": "1990-04-01",
                "address": {
                    "street": "123 Main St",
                    "county": "Anyshire",
                    "city": "Anycity",
                    "post_code": "AB12 3CD",
                    "country": "Countryland"
                },
                "email": "jane.doe@example.com",
                "phone": "+1234567890",
                "NI_number": "AB123456C"
            },
            "employment_information": {
                "employer_name": "Acme Corp",
                "role": "Software Developer",
                "type": "Full-Time",
                "status": "Active",
                "start_date": "2018-06-01",
                "leave_date": null
            },
            "income_information": {
                "pay_date": "2024-02-15",
                "pay_interval_start": "2024-02-01",
                "pay_interval_end": "2024-02-15",
                "pay_frequency": "weekly",
                "earnings": {
                    "gross_pay": 2000,
                    "net_pay": 1500,
                    "base_salary": 1900,
                    "bonus": 100
                },
                "deductions": {
                    "income_tax": 300,
                    "employee_ni": 150,
                    "employee_pension": 50,
                    "total_deductions": 500
                }
            }
        },
        {
            "id": "0187c66e-e7e5-811c-b006-2232f00f426a",
            "account_id": "552300dd-1e91-48d4-958b-41736c2c0167",
            "entry_id": "bdc420fe-5e48-4802-a753-659979a2a346",
            "created_at": "2024-05-03T14:00:13.804Z",
            "identity_information": {
                "name": "Jane Doe",
                "date_of_birth": "1990-04-01",
                "address": {
                    "street": "123 Main St",
                    "county": "Anyshire",
                    "city": "Anycity",
                    "post_code": "AB12 3CD",
                    "country": "Countryland"
                },
                "email": "jane.doe@example.com",
                "phone": "+1234567890",
                "NI_number": "AB123456C"
            },
            "employment_information": {
                "employer_name": "Acme Corp",
                "role": "Software Developer",
                "type": "Full-Time",
                "status": "Active",
                "start_date": "2018-06-01",
                "leave_date": null
            },
            "income_information": {
                "pay_date": "2024-02-15",
                "pay_interval_start": "2024-02-01",
                "pay_interval_end": "2024-02-15",
                "pay_frequency": "weekly",
                "earnings": {
                    "gross_pay": 2000,
                    "net_pay": 1500,
                    "base_salary": 1900,
                    "bonus": 100
                },
                "deductions": {
                    "income_tax": 300,
                    "employee_ni": 150,
                    "employee_pension": 50,
                    "total_deductions": 500
                }
            }
        },
        {
            "id": "0187c66e-e7e5-811c-b006-2232f00f426a",
            "account_id": "552300dd-1e91-48d4-958b-41736c2c0167",
            "entry_id": "bdc420fe-5e48-4802-a753-659979a2a346",
            "created_at": "2024-05-03T14:00:13.804Z",
            "identity_information": {
                "name": "Jane Doe",
                "date_of_birth": "1990-04-01",
                "address": {
                    "street": "123 Main St",
                    "county": "Anyshire",
                    "city": "Anycity",
                    "post_code": "AB12 3CD",
                    "country": "Countryland"
                },
                "email": "jane.doe@example.com",
                "phone": "+1234567890",
                "NI_number": "AB123456C"
            },
            "employment_information": {
                "employer_name": "Acme Corp",
                "role": "Software Developer",
                "type": "Full-Time",
                "status": "Active",
                "start_date": "2018-06-01",
                "leave_date": null
            },
            "income_information": {
                "pay_date": "2024-02-15",
                "pay_interval_start": "2024-02-01",
                "pay_interval_end": "2024-02-15",
                "pay_frequency": "weekly",
                "earnings": {
                    "gross_pay": 2000,
                    "net_pay": 1500,
                    "base_salary": 1900,
                    "bonus": 100
                },
                "deductions": {
                    "income_tax": 300,
                    "employee_ni": 150,
                    "employee_pension": 50,
                    "total_deductions": 500
                }
            }
        }
    ]
}

6. Extract Payroll information from a payslip `/entries/payslips`

This request simulates the user uploading a payslip to extract payroll information. Extracting payslip information can be done using the endpoint below but will usually be done by the user through the WebApp as per section 8

curl --location --request POST 'https://api.sandbox.goteal.co/entries/payslips' \
--header 'Authorization: Bearer <bearer-token>' \
--form 'file=@"<path-to-file>"'

Response Example:

{
    "account_id": "95a0e70b-fe02-4f47-aef9-2efff279df71",
    "entry_id": "f5e0a310-d4d0-4db0-b5c3-895a81e26e03",
    "payroll_submissions": [
        {
            "id": "0187c66e-e7e5-811c-b006-2232f00f426a",
            "account_id": null,
            "entry_id": "f5e0a310-d4d0-4db0-b5c3-895a81e26e03",
            "created_at": "2024-05-03T12:48:54.886Z",
            "identity_information": {
                "name": "Jane Doe",
                "date_of_birth": "1990-04-01",
                "address": {
                    "street": "123 Main St",
                    "county": "Anyshire",
                    "city": "Anycity",
                    "post_code": "AB12 3CD",
                    "country": "Countryland"
                },
                "email": "jane.doe@example.com",
                "phone": "+1234567890",
                "NI_number": "AB123456C",
                "employment_information": {
                    "employer_name": "Acme Corp",
                    "role": "Software Developer",
                    "type": "Full-Time",
                    "status": "Active",
                    "start_date": "2018-06-01",
                    "leave_date": null
                },
                "income_information": {
                    "pay_date": "2024-02-15",
                    "pay_interval_start": "2024-02-01",
                    "pay_interval_end": "2024-02-15",
                    "pay_frequency": "weekly",
                    "earnings": {
                        "gross_pay": 2000,
                        "net_pay": 1500,
                        "base_salary": 1900,
                        "bonus": 100
                    },
                    "deductions": {
                        "income_tax": 300,
                        "employee_ni": 150,
                        "employee_pension": 50,
                        "total_deductions": 500
                    }
                }
            }
        }
    ]
}

7. Retrieving Payroll Data `/payroll`

Retrieve the payroll data submitted through the connected account or document upload.

curl --request GET \
  --url https://api.sandbox.goteal.co/payroll/{user_id} \
  --header 'X-API-KEY: <api-key>'

Response Example:

{
  "pagination": {
    "count": 14,
    "limit": 25,
    "offset": 75,
    "total_count": 89
  },
  "payroll_submissions": [
    {
      "id": "95a0e70b-fe02-4f47-aef9-2efff279df71",
      "account_id": "0988b4bd-42dd-4556-95ae-27a906c066ec",
      "entry_id": "0d2bcb9b-a7ec-463f-bd7e-aacaa1a190a4",
      "created_at": "2019-05-17T00:00:00.000Z",
      "document_external_id": null,
      "document_filename": null,
      "employment_information": {
        "employer_name": "Acme Ltd",
        "leave_date": "2019-05-17T00:00:00.000Z",
        "role": "Software Engineer",
        "start_date": "2019-05-17T00:00:00.000Z",
        "status": "Active",
        "type": "Full-time"
      },
      "identity_information": {
        "NI_number": "AB123456C",
        "address": {
          "city": "London",
          "country": "United Kingdom",
          "county": "Greater London",
          "post_code": "SW1A 1AA",
          "street": "123 Main Street"
        },
        "date_of_birth": "2019-05-17T00:00:00.000Z",
        "email": "john.smith@company.com",
        "name": "John Smith",
        "phone": 447123456789
      },
      "income_information": {
        "deductions": {
          "employee_ni": 200,
          "employee_pension": 300,
          "income_tax": 500,
          "total_deductions": 1000
        },
        "earnings": {
          "base_salary": 3000,
          "bonus": 500,
          "gross_pay": 3500,
          "net_pay": 2500
        },
        "pay_date": "2019-05-17T00:00:00.000Z",
        "pay_frequency": "Monthly",
        "pay_interval_end": "2019-05-17T00:00:00.000Z",
        "pay_interval_start": "2019-05-17T00:00:00.000Z"
      }
    }
  ]
}

8. WebApp usage

Teal’s webapp can be tested by accessing https://app.sandbox.goteal.co/ in the browser. Use the generated bearer token in order to identify the user https://app.sandbox.goteal.co/?jwt=<bearer-token>. The webapp uses the same API mechanism as the mentioned above, therefore the data will be retrieved in the same way.

Connect a Payroll:

Submit a Payroll:

9. Cleanup: Deleting a User `/users`

After testing, clean up by deleting the test user and their associated data.

curl --request DELETE \
  --url https://api.sandbox.goteal.co/users/{user_id} \
  --header 'X-API-KEY: <api-key>'

Response Example:

{
  "message": "User deleted successfully."
}

Get Started

​Introduction

​Setting Up for Testing

​1. Webhooks Setup /webhooks

​2. Create a user /users

​3. Generating a user token /user-tokens

​4. Connecting a Payroll Account /accounts

​5. Retrieve submitted Payroll information /entries/connections

​6. Extract Payroll information from a payslip /entries/payslips

​7. Retrieving Payroll Data /payroll

​8. WebApp usage

​9. Cleanup: Deleting a User /users

Introduction

Setting Up for Testing

1. Webhooks Setup `/webhooks`

2. Create a user `/users`

3. Generating a user token `/user-tokens`

4. Connecting a Payroll Account `/accounts`

5. Retrieve submitted Payroll information `/entries/connections`

6. Extract Payroll information from a payslip `/entries/payslips`

7. Retrieving Payroll Data `/payroll`

8. WebApp usage

9. Cleanup: Deleting a User `/users`