Data

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.

​

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

curl --request GET \
  --url https://api.sandbox.goteal.co/users/{user_id} \
  --header 'X-API-KEY: <api-key>'

A user is made up of their identity information only.

​

Accounts /accounts

Account are the payroll and HR platform accesses that users link to Teal, providing a stream of income and employment data

Example: Link a payroll account

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"
}'

A user can have multiple accounts to the same provider depending on the type of connection. The 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.

​

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

curl --request POST \
  --url https://api.sandbox.goteal.co/entries/connections \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "account_id": "95a0e70b-fe02-4f47-aef9-2efff279df71"
  }'

For an account, a call to the /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.

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 retireved 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

curl --request GET \
  --url https://api.sandbox.goteal.co/payroll/{user_id} \
  --header 'X-API-KEY: <api-key>''

The structure of the returned data will contain fields on employment, identity and income.

​

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

curl --request GET \
  --url https://api.sandbox.goteal.co/documents/{document_id} \
  --header 'X-API-KEY: <api-key>'

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.

​

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 data

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"
}'

​

3. 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 deletion

curl --request DELETE \
  --url https://api.sandbox.goteal.co/users/{user_id} \
  --header 'X-API-KEY: <api-key>'

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.

​

Security and Compliance

Our infrastructure employs advanced security measures, including data encryption, regular security audits, and compliance with global data protection standards (e.g., GDPR, CCPA), to safeguard user data against unauthorized access or breaches.

This enhanced documentation provides a clearer, more detailed view of how our API manages, delivers, and secures financial data, emphasizing our commitment to data integrity, security, and user control.