Get Started
Data
Manage your data easily and securely
This documentation is designed to provide developers with detailed insights into our API’s structure, focusing on the management, delivery, and security of financial data.
Users
Represents the borrowers and end-users that give consented access and upload their payslips to our API.
Example: Retrieve a new user
A user is made up of their identity information only.
Accounts
Accounts represent user-linked connections to payroll and HR platforms, which provide Teal with a stream of income and employment data.
Example: Link a payroll account
A user can have multiple accounts to the same provider depending on the type of connection. The Entries
Entries log each data submission, tracking the origin (account connection or manual upload) and content type of the data.
Example: Query and persist data for a valid account connection
For an account, a call to the Payroll
Aggregates detailed payroll information obtained through account synchronization or document analysis, including comprehensive earnings and deductions data.
Example: Access payroll data
The structure of the returned data will contain fields on employment, identity and income.
Documents
Original documents (e.g., payslips) uploaded by users are stored securely, serving as the basis for data extraction and verification.
Example: Retrieve a raw payslip
The response data of the above document request will be JSON containing the Base-64 encoded file contents. This can be decoded and transformed back into PDF format.
A deletion of a user deletes all sub-resources that the user is linked to. This includes accounts, payroll and uploaded documents. Once deleted no data can be retreived for that user, nor can any new data be attributed. On an account level, any connection can be revoked by the user at any time.
A deletion of an account removes all entries and payroll associated with it. After deletion, this account can not be retireved nor any data queried from it.
1. Endpoints
Our API organizes financial data into several key entities, each tailored for specific aspects of data handling and retrieval.Users /users
Represents the borrowers and end-users that give consented access and upload their payslips to our API.
Example: Retrieve a new user
Accounts /accounts
Accounts represent user-linked connections to payroll and HR platforms, which provide Teal with a stream of income and employment data.
Example: Link a payroll account
POST /accounts endpoint is a way to initialize a connection to a provider for a given user; Teal offers a separate provider flow for users via the WebUI as documented in Introduction.
The status of a account determines if it is able to recieve data, needs authorisation or if it is invalid or expired. An account connected via OAuth will not require credentials to be passed into the account creation request. Any credentials that are passed to Teal are encrypted securely. An account creation
will do an initial payroll retrieval using the optional dates supplied; if none are sent with the request we then check for the client specific duration for which to lookback - if this is not configured, we take a default of 36 months.
Entries /entries
Entries log each data submission, tracking the origin (account connection or manual upload) and content type of the data.
Example: Query and persist data for a valid account connection
/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 /entries/connections is persisted on Teal’s storage and can be retrieved using the /payroll/{user_id} endpoint.
When querying a connection, new payroll will be fetched based on the initial period used in account creation; Teal uses the most recent pay_date of an account to update the connection with the latest payroll seen after this date.
A manual upload of payslip data using is not linked to an account, but the JSON response of /entries/payslips will be in the same format and the payroll data
can be retrieved in the exact same way. The files for upload must be in PDF format.
Payroll /payroll
Aggregates detailed payroll information obtained through account synchronization or document analysis, including comprehensive earnings and deductions data.
Example: Access payroll data
Documents /documents
Original documents (e.g., payslips) uploaded by users are stored securely, serving as the basis for data extraction and verification.
Example: Retrieve a raw payslip
2. Data Delivery
Data delivery mechanisms are designed to ensure timely, secure, and efficient access to financial data, facilitating seamless integration and real-time processing.Timing
Data processing is immediate for connected accounts, with payroll information updated in real-time as new data becomes available. Manual uploads are processed within seconds of submission, ensuring prompt data availability.Availability
Our API provides round-the-clock access to processed data, supporting queries for real-time and historical financial information. Data is accessible through dedicated endpoints, with responses designed for easy integration into client applications.Webhooks
Webhooks offer a proactive approach to data delivery, notifying client applications of specific events, such as new data submissions or updates to existing entries, facilitating immediate action or processing. Example: Configure a webhook for new payroll data3. Data Security
Adhering to strict security protocols, our API ensures the integrity and confidentiality of sensitive financial data throughout its lifecycle.Data Sharing
Access to data through our API is regulated by user permissions alongside OAuth 2.0 protocols, allowing us to securely access user-authorized data. Upon obtaining this data, we then facilitate its secure transfer to the third party requesting this information. This process ensures that data sharing is both compliant with user consent and adheres to stringent privacy standards, safeguarding data integrity during transmission.Data Deletion Requests
In compliance with privacy laws, our API supports explicit requests for data deletion, allowing our clients to manage the data footprint of their customers if needed be. Example: Request data deletionDate handling
All dates in our API are formatted according to ISO 8601. Response dates are always returned in UTC, representing the equivalent moment in time regardless of the original time zone offset. For example, 2PM in Berlin:2024-02-17T14:00:00+02:00 is returned as 2024-02-17T12:00:00Z
When submitting dates to the API, you can include offsets, and these will be respected in all date calculations.
When integrating with payroll providers that supply dates without time components (e.g., 2024-02-17), we standardize these to noon UTC (2024-02-17T12:00:00Z) to avoid any ambiguity with date boundaries across time zones.
This should be taken into consideration when submitting your own dates for filtering payroll (such as in POST /accounts).
Client callback
You can configure a client callback that will be redirected to after the end user has completed their journey. This allows the user to finish their flow on your chosen domain. For successful account connections we will redirect with theaccount_id, user_id and provider in the query parameters. For payslip uploads we will redirect with the user_id and a message parameter. On failure we’ll attach an error parameter alongside the user_id.