# Step 1: request presigned upload URLs
curl --request POST \
  --url https://api.sandbox.goteal.co/payroll/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/payroll/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",
      "source": "Payslip (via Doc Scan)",
      "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": "john.smith@company.com",
        "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
        }
      }
    },
    "trust_score": "High"
    ],
  "payslip_errors" : [{
    "error" : "File is not a payslip",
    "file_name" : "Payslip3.pdf"
  }]
}

Payroll

Payslips upload

Uploading payslips is a three-step flow:

Request upload slots with POST /payroll/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

payroll

entries

payslips

# Step 1: request presigned upload URLs
curl --request POST \
  --url https://api.sandbox.goteal.co/payroll/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/payroll/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",
      "source": "Payslip (via Doc Scan)",
      "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": "john.smith@company.com",
        "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
        }
      }
    },
    "trust_score": "High"
    ],
  "payslip_errors" : [{
    "error" : "File is not a payslip",
    "file_name" : "Payslip3.pdf"
  }]
}

This endpoint requires a valid authorisation for the user. If no active authorisation exists, the request will be rejected. You can optionally pass the x-teal-authorisation-id header to specify which authorisation to use; otherwise the system will resolve a valid authorisation automatically. See Authorisations for more details.

End-to-end upload flow

Follow these steps to upload payslips programmatically:

Request upload slots – call POST /payroll/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 /payroll/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/payroll/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/payroll/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",
      "source": "Payslip (via Doc Scan)",
      "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": "john.smith@company.com",
        "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
        }
      }
    },
    "trust_score": "High"
    ],
  "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.

Headers

x-teal-authorisation-id

string<uuid>

Optional authorisation ID to associate with this request. If not provided, the system will attempt to resolve a valid authorisation for the user automatically.

Example:

"7f3b8c2a-1d4e-5f6g-7h8i-9j0k1l2m3n4o"

Body

application/json

files

object[]

required

Minimum array length: 1

Show child attributes

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

authorisation_id

string<uuid> | null

The id of the authorisation that authorized this data retrieval

Example:

"7f3b8c2a-1d4e-5f6g-7h8i-9j0k1l2m3n4o"

payslip_errors

object[]

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

Show child attributes

Generate presigned payslip URLs Get Payroll

​End-to-end upload flow

Authorizations

Headers

Body

Response

End-to-end upload flow