# Step 1: request presigned upload URLs
curl --request POST \
  --url https://api.sandbox.goteal.co/entries/payslips/presign \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "files": [
      {"file_name": "payslip1.pdf", "external_id": "ext-jan-2024"},
      {"file_name": "payslip2.pdf"}
    ]
  }'

# Step 2: upload PDFs with the provided presigned URLs
curl --request PUT \
  --url "<presigned_url_from_step_1>" \
  --header 'Content-Type: application/octet-stream' \
  --data-binary '@./fixtures/payslip1.pdf'

# Step 3: submit uploaded payslips for processing
curl --request POST \
  --url https://api.sandbox.goteal.co/entries/payslips \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "files": [
      {"path": "client/acct123/users/user456/payslip1.pdf", "external_document_id": "ext-jan-2024"},
      {"path": "client/acct123/users/user456/payslip2.pdf"}
    ]
  }'

{
  "account_id": "95a0e70b-fe02-4f47-aef9-2efff279df71",
  "entry_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "payroll_submissions": [
    {
      "id": "95a0e70b-fe02-4f47-aef9-2efff279df71",
      "account_id": "674744df-9626-47ef-ae2b-4a491be136b5",
      "entry_id": "be770ba4-1362-46cd-8c1c-2330ce3a8b69",
      "created_at": "2019-05-17T00:00:00.000Z",
      "document_external_id": "payslip123456",
      "document_filename": "file1-payslip.pdf",
      "identity_information": {
        "name": "John Smith",
        "date_of_birth": "2019-05-17T00:00:00.000Z",
        "address": {
          "street": "123 Main Street",
          "county": "Greater London",
          "city": "London",
          "post_code": "SW1A 1AA",
          "country": "United Kingdom"
        },
        "email": "[email protected]",
        "phone": 447123456789,
        "NI_number": "AB123456C"
      },
      "employment_information": {
        "employer_name": "Acme Ltd",
        "role": "Software Engineer",
        "type": "Full-time",
        "status": "Active",
        "start_date": "2019-05-17T00:00:00.000Z",
        "leave_date": "2019-05-17T00:00:00.000Z"
      },
      "income_information": {
        "pay_date": "2023-05-27T00:00:00.000Z",
        "pay_interval_start": "2023-05-01T00:00:00.000Z",
        "pay_interval_end": "2023-05-31T00:00:00.000Z",
        "pay_frequency": "Monthly",
        "earnings": {
          "gross_pay": 3500,
          "net_pay": 2500,
          "base_salary": 3000,
          "bonus": 500
        },
        "deductions": {
          "income_tax": 500,
          "employee_ni": 200,
          "employee_pension": 300,
          "total_deductions": 1000
        }
      }
    },
    "fraud_risk": "Low"
    ],
  "payslip_errors" : [{
    "error" : "File is not a payslip",
    "file_name" : "Payslip3.pdf"
  }]
}

Entries

Payslips upload

Uploading payslips is a three-step flow:

Request upload slots with POST /entries/payslips/presign, providing each PDF file name (and optional external identifier). The response includes presigned_url and path values for every requested file.
Upload the PDF content to every presigned_url using an HTTP PUT request with Content-Type: application/octet-stream. Each file must be a searchable, machine-readable PDF (scanned images are not supported).
Call this endpoint with the JSON payload returned in step one, echoing the path (and optional external_document_id) for every uploaded file so Teal can process the documents. The path values you submit must match the ones returned by the presign step. Any files that failed validation or upload are reported in the payslip_errors array.

POST

entries

payslips

# Step 1: request presigned upload URLs
curl --request POST \
  --url https://api.sandbox.goteal.co/entries/payslips/presign \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "files": [
      {"file_name": "payslip1.pdf", "external_id": "ext-jan-2024"},
      {"file_name": "payslip2.pdf"}
    ]
  }'

# Step 2: upload PDFs with the provided presigned URLs
curl --request PUT \
  --url "<presigned_url_from_step_1>" \
  --header 'Content-Type: application/octet-stream' \
  --data-binary '@./fixtures/payslip1.pdf'

# Step 3: submit uploaded payslips for processing
curl --request POST \
  --url https://api.sandbox.goteal.co/entries/payslips \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "files": [
      {"path": "client/acct123/users/user456/payslip1.pdf", "external_document_id": "ext-jan-2024"},
      {"path": "client/acct123/users/user456/payslip2.pdf"}
    ]
  }'

{
  "account_id": "95a0e70b-fe02-4f47-aef9-2efff279df71",
  "entry_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "payroll_submissions": [
    {
      "id": "95a0e70b-fe02-4f47-aef9-2efff279df71",
      "account_id": "674744df-9626-47ef-ae2b-4a491be136b5",
      "entry_id": "be770ba4-1362-46cd-8c1c-2330ce3a8b69",
      "created_at": "2019-05-17T00:00:00.000Z",
      "document_external_id": "payslip123456",
      "document_filename": "file1-payslip.pdf",
      "identity_information": {
        "name": "John Smith",
        "date_of_birth": "2019-05-17T00:00:00.000Z",
        "address": {
          "street": "123 Main Street",
          "county": "Greater London",
          "city": "London",
          "post_code": "SW1A 1AA",
          "country": "United Kingdom"
        },
        "email": "[email protected]",
        "phone": 447123456789,
        "NI_number": "AB123456C"
      },
      "employment_information": {
        "employer_name": "Acme Ltd",
        "role": "Software Engineer",
        "type": "Full-time",
        "status": "Active",
        "start_date": "2019-05-17T00:00:00.000Z",
        "leave_date": "2019-05-17T00:00:00.000Z"
      },
      "income_information": {
        "pay_date": "2023-05-27T00:00:00.000Z",
        "pay_interval_start": "2023-05-01T00:00:00.000Z",
        "pay_interval_end": "2023-05-31T00:00:00.000Z",
        "pay_frequency": "Monthly",
        "earnings": {
          "gross_pay": 3500,
          "net_pay": 2500,
          "base_salary": 3000,
          "bonus": 500
        },
        "deductions": {
          "income_tax": 500,
          "employee_ni": 200,
          "employee_pension": 300,
          "total_deductions": 1000
        }
      }
    },
    "fraud_risk": "Low"
    ],
  "payslip_errors" : [{
    "error" : "File is not a payslip",
    "file_name" : "Payslip3.pdf"
  }]
}

End-to-end upload flow

Follow these steps to upload payslips programmatically:

Request upload slots – call POST /entries/payslips/presign with the list of filenames (and optional external identifiers) you intend to upload. The response returns presigned_url and path fields for each file.
Upload PDFs – for every returned presigned_url, perform an HTTP PUT with Content-Type: application/octet-stream, streaming the PDF bytes. Files must be searchable, machine-readable PDFs (scanned images are not supported).
Submit metadata – call POST /entries/payslips (this endpoint) with a JSON payload that includes the path for each uploaded file and an optional external_document_id. Teal uses this metadata to process the uploaded documents. Any files that fail validation are listed in payslip_errors in the response.

# Step 1: request presigned upload URLs
curl --request POST \
  --url https://api.sandbox.goteal.co/entries/payslips/presign \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "files": [
      {"file_name": "payslip1.pdf", "external_id": "ext-jan-2024"},
      {"file_name": "payslip2.pdf"}
    ]
  }'

# Step 2: upload PDFs with the provided presigned URLs
curl --request PUT \
  --url "<presigned_url_from_step_1>" \
  --header 'Content-Type: application/octet-stream' \
  --data-binary '@./fixtures/payslip1.pdf'

# Step 3: submit uploaded payslips for processing
curl --request POST \
  --url https://api.sandbox.goteal.co/entries/payslips \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "files": [
      {"path": "client/acct123/users/user456/payslip1.pdf", "external_document_id": "ext-jan-2024"},
      {"path": "client/acct123/users/user456/payslip2.pdf"}
    ]
  }'

{
  "account_id": "95a0e70b-fe02-4f47-aef9-2efff279df71",
  "entry_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "payroll_submissions": [
    {
      "id": "95a0e70b-fe02-4f47-aef9-2efff279df71",
      "account_id": "674744df-9626-47ef-ae2b-4a491be136b5",
      "entry_id": "be770ba4-1362-46cd-8c1c-2330ce3a8b69",
      "created_at": "2019-05-17T00:00:00.000Z",
      "document_external_id": "payslip123456",
      "document_filename": "file1-payslip.pdf",
      "identity_information": {
        "name": "John Smith",
        "date_of_birth": "2019-05-17T00:00:00.000Z",
        "address": {
          "street": "123 Main Street",
          "county": "Greater London",
          "city": "London",
          "post_code": "SW1A 1AA",
          "country": "United Kingdom"
        },
        "email": "[email protected]",
        "phone": 447123456789,
        "NI_number": "AB123456C"
      },
      "employment_information": {
        "employer_name": "Acme Ltd",
        "role": "Software Engineer",
        "type": "Full-time",
        "status": "Active",
        "start_date": "2019-05-17T00:00:00.000Z",
        "leave_date": "2019-05-17T00:00:00.000Z"
      },
      "income_information": {
        "pay_date": "2023-05-27T00:00:00.000Z",
        "pay_interval_start": "2023-05-01T00:00:00.000Z",
        "pay_interval_end": "2023-05-31T00:00:00.000Z",
        "pay_frequency": "Monthly",
        "earnings": {
          "gross_pay": 3500,
          "net_pay": 2500,
          "base_salary": 3000,
          "bonus": 500
        },
        "deductions": {
          "income_tax": 500,
          "employee_ni": 200,
          "employee_pension": 300,
          "total_deductions": 1000
        }
      }
    },
    "fraud_risk": "Low"
    ],
  "payslip_errors" : [{
    "error" : "File is not a payslip",
    "file_name" : "Payslip3.pdf"
  }]
}

Authorizations

Authorization

string

header

required

Bearer token for authentication. The token should be the one returned by the /user-tokens endpoint.

Body

application/json

files

object[]

required

Minimum array length: 1

Show child attributes

files.path

string

required

Storage path returned by the presign endpoint.

Example:

"client/acct123/users/user456/payslip1.pdf"

files.external_document_id

string

Optional identifier shown in payroll submissions when present.

Example:

"ext-payslip-2024-05"

Response

Created

account_id

string<uuid>

required

The id of the account

Example:

"95a0e70b-fe02-4f47-aef9-2efff279df71"

entry_id

string<uuid>

required

The id of the entry

payroll_submissions

object[]

required

Show child attributes

payroll_submissions.id

string<uuid>

required

Example:

"95a0e70b-fe02-4f47-aef9-2efff279df71"

payroll_submissions.account_id

string<uuid>

required

The id of the account

Example:

"674744df-9626-47ef-ae2b-4a491be136b5"

payroll_submissions.entry_id

string<uuid>

required

The id of the entry

Example:

"be770ba4-1362-46cd-8c1c-2330ce3a8b69"

payroll_submissions.created_at

string<date-time>

required

The date the payroll was submitted

Example:

"2019-05-17T00:00:00.000Z"

payroll_submissions.identity_information

object

required

Show child attributes

payroll_submissions.identity_information.name

string

The full name of the user

Example:

"John Smith"

payroll_submissions.identity_information.date_of_birth

string<date-time>

Example:

"2019-05-17T00:00:00.000Z"

payroll_submissions.identity_information.address

object

Show child attributes

payroll_submissions.identity_information.address.street

string

The street of the address

Example:

"123 Main Street"

payroll_submissions.identity_information.address.county

string

The county of the address

Example:

"Greater London"

payroll_submissions.identity_information.address.city

string

The city of the address

Example:

"London"

payroll_submissions.identity_information.address.post_code

string

The post code of the address

Example:

"SW1A 1AA"

payroll_submissions.identity_information.address.country

string

The country of the address

Example:

"United Kingdom"

payroll_submissions.identity_information.email

string<email>

The email of the user

Example:

"[email protected]"

payroll_submissions.identity_information.phone

string

The phone number of the user

Example:

447123456789

payroll_submissions.identity_information.NI_number

string

The national insurance number of the user

Example:

"AB123456C"

payroll_submissions.employment_information

object

required

Show child attributes

payroll_submissions.employment_information.employer_name

string

The name of the employer

Example:

"Acme Ltd"

payroll_submissions.employment_information.role

string

The role of the user

Example:

"Software Engineer"

payroll_submissions.employment_information.type

string

The type of employment

Example:

"Full-time"

payroll_submissions.employment_information.status

enum<string>

The status of the employment. Status active will be used when the user is employed in the company, alternatively inactive will be used when the user is not employed in the company anymore.

Available options:

active,

inactive

Example:

"active"

payroll_submissions.employment_information.start_date

string<date-time>

Example:

"2019-05-17T00:00:00.000Z"

payroll_submissions.employment_information.leave_date

string<date-time> | null

Example:

"2019-05-17T00:00:00.000Z"

payroll_submissions.income_information

object

required

Show child attributes

payroll_submissions.income_information.pay_date

string<date-time>

The date the payroll was submitted

Example:

"2023-05-27T00:00:00.000Z"

payroll_submissions.income_information.pay_interval_start

string<date-time>

The start date of the pay interval

Example:

"2023-05-01T00:00:00.000Z"

payroll_submissions.income_information.pay_interval_end

string<date-time>

The end date of the pay interval

Example:

"2023-05-31T00:00:00.000Z"

payroll_submissions.income_information.pay_frequency

string

The frequency of the pay

Example:

"Monthly"

payroll_submissions.income_information.earnings

object

Show child attributes

payroll_submissions.income_information.earnings.gross_pay

number

The gross pay

Example:

3500

payroll_submissions.income_information.earnings.net_pay

number

The net pay

Example:

2500

payroll_submissions.income_information.earnings.base_salary

number

The base salary

Example:

3000

payroll_submissions.income_information.earnings.bonus

number

The bonus

Example:

500

payroll_submissions.income_information.deductions

object

Show child attributes

payroll_submissions.income_information.deductions.income_tax

number

The income tax

Example:

500

payroll_submissions.income_information.deductions.employee_ni

number

The employee national insurance

Example:

200

payroll_submissions.income_information.deductions.employee_pension

number

The employee pension

Example:

300

payroll_submissions.income_information.deductions.total_deductions

number

The total deductions

Example:

1000

payroll_submissions.document_id

string<uuid> | null

The id of the document

Example:

"95a0e70b-fe02-4f47-aef9-2efff279df71"

payroll_submissions.document_external_id

string | null

A string coming from the parameters of the uploaded payslip1.pdf either the form field name or external_document_id header for the file part. It might not be unique and depends on what's passed when uploading. If the payroll submission doesn't originate from a payslip this will be null.

Example:

"payslip123456"

payroll_submissions.document_filename

string | null

If the payroll submission originates from a payslip this will be the file name of the uploaded payslip. It will be duplicate if same file names are uploaded If the payroll submission doesn't originate from a payslip this will be null.

Example:

"file1-payslip.pdf"

payroll_submissions.fraud_risk

enum<string> | null

The fraud risk level assessment. Fraud risk will be present if the payroll data is coming from a payslip source

Available options:

Low,

Medium,

High

Example:

"Low"

payslip_errors

object[]

List of errors for payslips that passed validation but failed to upload

Show child attributes

payslip_errors.error

string

payslip_errors.file_name

string

Generate presigned payslip URLs List all entries

⌘I

API Documentation

Users

User Token

API Keys

Accounts

Entries

Payroll

Documents

Configuration

Webhooks

Members

Payslips upload

End-to-end upload flow

Authorizations

Body

Response

API Documentation

Users

User Token

API Keys

Accounts

Entries

Payroll

Documents

Configuration

Webhooks

Members

​End-to-end upload flow

Authorizations

Body

Response

End-to-end upload flow