​
Introduction

To keep your users’ payroll up to date without having to manually query each connection, Recurring Payroll can be enabled for your users. This allows you to specify a time frequency for automated payroll fetches. The valid frequencies are:
  • WEEKLY - once a week on Monday 12AM UTC
  • MONTHLY - once a month on the first day of the month 12AM UTC

​
Execution

When a recurring check is executed, all of your eligible users will have their accounts updated with their latest payroll. The payroll is queried from the payroll provider by using the most recent pay_date of the account, retrieving the new data that falls after this. Recurring checks can be enabled for all users or for individual users. This also applies to the recurring check configuration where the frequency and end date of the recurring check can be applied on the user level or to the client level. If a user has a configuration for a given field, it will always take precedence over the client level configuration. If the user has a partial configuration, then the fields that are not configured will be taken from the client configuration if present.

​
Eligibility

A users account is eligible for a recurring payroll check if the following are all true:
  • The account has Authorised status
  • Multi-factor authentication is disabled for the account
  • The account is active
To see which users are eligible for recurring checks you can call the GET /users/recurring endpoint. For a user to be eligible for the recurring check they need to have at least one account that matches the above criteria. An account is considered active if the payroll provider has not marked it as inactive and the latest pay_date for the account is not older than 40 days. A duplicate account is defined as multiple accounts with the same username and payroll provider combination for a given user. If there are duplicate accounts then Teal will take the one with the most recent activity (time of last fetch of payroll), or the by the creation time (most recently created). A user can have multiple active accounts with different providers and all of these accounts will be part of the recurring update. To see which accounts would be part of the recurring schedule for a given user you can call the GET /accounts/recurring endpoint.

​
Failures

If a fetch fails for an account during the recurring payroll check, then it will be placed on a daily retry schedule until it is successful. The daily retry runs at 3AM UTC. When the failure is due to invalid credentials, expired refresh token or a detection of Multi-Factor authentication, these accounts are excluded from future checks.

​
Sandbox

In the sandbox environment, recurring checks can be enabled but all the data that is returned for the accounts is mocked up. For testing purposes, the frequency of the recurring payroll can be set to HOURLY in this environment if you choose.

​
Activation

To activate recurring payroll checks please contact Teal with the following information:
  • Your chosen frequency
  • An optional end date for when you want recurring checks to end. If omitted, the checks will run indefinitely.