> ## Documentation Index
> Fetch the complete documentation index at: https://docs.goteal.co/llms.txt
> Use this file to discover all available pages before exploring further.
# Create a connection
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](/authorisations) for more details.
## OpenAPI
````yaml POST /payroll/entries/connections
openapi: 3.0.1
info:
title: Payroll API
description: A full flagged payroll api provided by Teal
version: 1.0.0
servers:
- url: https://api.sandbox.goteal.co
description: Sandbox server for experiments
- url: https://api.goteal.co
description: Production server
security:
- ApiKeyAuth: []
- MemberBearerAuth: []
paths:
/payroll/entries/connections:
description: >-
For an account, a call to the `/payroll/entries/connections` endpoint will
query the connection for data. This endpoint is for adhoc data retrieval
for an account; Teal will also collect the payroll data for users via the
WebUI as soon as a valid connection is established. This endpoint can be
applied to any account, it does not matter if it was established via your
own call to `POST /accounts` or via the Teal WebUI. Note that any new data
retrieved via `/payroll/entries/connections` is persisted on Teal's
storage and can be retrieved using the `/payroll/{user_id}` endpoint.
post:
summary: Connects a user account to a payroll provider
parameters:
- $ref: '#/components/parameters/XAuthorisationId'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- account_id
properties:
account_id:
type: string
format: uuid
description: The account id to use to connect to the payroll provider
example: 95a0e70b-fe02-4f47-aef9-2efff279df71
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/PayrollData'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/UnauthorizedBearer'
security:
- BearerAuth: []
components:
parameters:
XAuthorisationId:
name: x-teal-authorisation-id
in: header
required: false
description: >-
Optional authorisation ID to associate with this request. If not
provided, the system will attempt to resolve a valid authorisation for
the user automatically.
schema:
type: string
format: uuid
example: 7f3b8c2a-1d4e-5f6g-7h8i-9j0k1l2m3n4o
schemas:
PayrollData:
type: object
required:
- account_id
- entry_id
- pagination
- payroll_submissions
properties:
account_id:
type: string
format: uuid
description: The id of the account
example: 95a0e70b-fe02-4f47-aef9-2efff279df71
entry_id:
type: string
format: uuid
description: The id of the entry
authorisation_id:
type: string
format: uuid
nullable: true
description: The id of the authorisation that authorized this data retrieval
example: 7f3b8c2a-1d4e-5f6g-7h8i-9j0k1l2m3n4o
payroll_submissions:
type: array
items:
$ref: '#/components/schemas/PayrollSubmission'
PayrollSubmission:
type: object
required:
- id
- account_id
- entry_id
- created_at
- identity_information
- employment_information
- income_information
properties:
id:
type: string
format: uuid
example: 95a0e70b-fe02-4f47-aef9-2efff279df71
account_id:
type: string
format: uuid
description: The id of the account
example: 674744df-9626-47ef-ae2b-4a491be136b5
entry_id:
type: string
format: uuid
description: The id of the entry
example: be770ba4-1362-46cd-8c1c-2330ce3a8b69
created_at:
$ref: '#/components/schemas/Date'
description: The date the payroll was submitted
example: '2019-05-17T00:00:00.000Z'
document_id:
type: string
nullable: true
format: uuid
description: The id of the document
example: 95a0e70b-fe02-4f47-aef9-2efff279df71
document_external_id:
type: string
nullable: true
description: >-
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
document_filename:
type: string
nullable: true
description: >-
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
identity_information:
$ref: '#/components/schemas/IdentityInformation'
employment_information:
$ref: '#/components/schemas/EmploymentInformation'
income_information:
$ref: '#/components/schemas/IncomeInformation'
trust_score:
$ref: '#/components/schemas/TrustScore'
nullable: true
source:
type: string
description: The source of the payroll data
example: Payroll (via Direct Connection)
enum:
- Payroll (via Direct Connection)
- Payroll (via User Connection)
- Payslip (via Doc Scan)
Error:
required:
- errors
type: object
properties:
errors:
type: array
items:
type: string
description: An array of messages describing the errors
example:
- The request is missing the required field `name`
UnauthorizedBarer:
type: object
properties:
errors:
type: array
items:
type: string
description: An array of messages describing the errors
example:
- 'Not Authorization: Bearer provided or wrong value'
Date:
type: string
format: date-time
example: '2019-05-17T00:00:00.000Z'
IdentityInformation:
type: object
properties:
name:
type: string
description: The full name of the user
example: John Smith
date_of_birth:
$ref: '#/components/schemas/Date'
address:
$ref: '#/components/schemas/Address'
email:
type: string
description: The email of the user
format: email
example: john.smith@company.com
phone:
type: string
description: The phone number of the user
example: 447123456789
NI_number:
type: string
description: The national insurance number of the user
example: AB123456C
EmploymentInformation:
type: object
properties:
employer_name:
type: string
description: The name of the employer
example: Acme Ltd
role:
type: string
description: The role of the user
example: Software Engineer
type:
type: string
description: The type of employment
example: Full-time
status:
type: string
description: >
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.
enum:
- active
- inactive
example: active
start_date:
$ref: '#/components/schemas/Date'
leave_date:
$ref: '#/components/schemas/Date'
nullable: true
IncomeInformation:
type: object
properties:
pay_date:
$ref: '#/components/schemas/Date'
type: string
description: The date the payroll was submitted
example: '2023-05-27T00:00:00.000Z'
pay_interval_start:
$ref: '#/components/schemas/Date'
type: string
description: The start date of the pay interval
example: '2023-05-01T00:00:00.000Z'
pay_interval_end:
$ref: '#/components/schemas/Date'
type: string
description: The end date of the pay interval
example: '2023-05-31T00:00:00.000Z'
pay_frequency:
type: string
description: The frequency of the pay
example: Monthly
earnings:
$ref: '#/components/schemas/Earnings'
deductions:
$ref: '#/components/schemas/Deductions'
TrustScore:
type: string
description: >-
The document trust score assessment. Trust score will be present if the
payroll data is coming from a payslip source
enum:
- Low
- Medium
- High
example: High
Address:
type: object
properties:
street:
type: string
description: The street of the address
example: 123 Main Street
county:
type: string
description: The county of the address
example: Greater London
city:
type: string
description: The city of the address
example: London
post_code:
type: string
description: The post code of the address
example: SW1A 1AA
country:
type: string
description: The country of the address
example: United Kingdom
Earnings:
type: object
properties:
gross_pay:
type: number
description: The gross pay
example: 3500
net_pay:
type: number
description: The net pay
example: 2500
base_salary:
type: number
description: The base salary
example: 3000
bonus:
type: number
description: The bonus
example: 500
Deductions:
type: object
properties:
income_tax:
type: number
description: The income tax
example: 500
employee_ni:
type: number
description: The employee national insurance
example: 200
employee_pension:
type: number
description: The employee pension
example: 300
total_deductions:
type: number
description: The total deductions
example: 1000
responses:
BadRequest:
description: Bad request if one of the required parameters is missing
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
UnauthorizedBearer:
description: Unauthorized if the X-API-KEY is not provided or is wrong
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedBarer'
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-KEY
MemberBearerAuth:
type: http
scheme: bearer
description: >-
Bearer token for authentication. The token should be the one returned by
the "/members/signin"
BearerAuth:
type: http
scheme: bearer
description: >-
Bearer token for authentication. The token should be the one returned by
the /user-tokens endpoint.
````