Setting Up for Testing

Before you begin testing, ensure you have the following:

  • An API key for authentication: please ask your Teal connection to suppy 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"
}

This will create also a test user data automatically.

2. Create a user /users

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

  • User 1 |John Smith| - 95a0e70b-fe02-4f47-aef9-2efff279df71
  • User 2 |Jane Brown| - 4dfd21fa-2a2c-42af-aa52-278b4ffc9e40
  • User 3 |Robert Clarke| - 30074ec7-0cbc-4a80-a332-23fbf9342adf
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"
}'

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. 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": [
    {
      "account_id": "95a0e70b-fe02-4f47-aef9-2efff279df71S",
      "created_at": "2019-05-17T00:00:00.000Z",
      "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"
      },
      "entry_id": "95a0e70b-fe02-4f47-aef9-2efff279df71S1",
      "id": "95a0e70b-fe02-4f47-aef9-2efff279df71",
      "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"
      }
    }
  ]
}

6. 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."
}