Removing pay allocations

Learn how to remove pay allocations via the API.

Overview

The process outlined in this guide allows you to remove pay allocations on behalf of your users without initializing Argyle Link.

Removing a pay allocation via the API changes the remaining allocations on the payroll platform. We cannot guarantee that the original pay distribution settings will be observed and therefore you have to:

  1. Retrieve the current pay allocations and determine if they are distributed correctly. You might need to check with the user to confirm this.
  2. If the pay distribution is incorrect, you have to ask the user to go into their payroll platform and adjust the pay distribution settings themselves.

How to remove a pay allocation?

Make a POST request (with no payload) to the /v1/pay-allocations/<id>/remove endpoint, where <id> is the ID of the allocation you want to be removed.

How long will it take?

Typically between 15-90 seconds, depending on the Link item. Removal is faster than the regular pay distribution update flow, because there is no waiting for the user to confirm.

How to check the progress?

You may call GET /v1/accounts/<account-id> and extract pay_distribution.status and pay_distribution.error from the payload.

The status will progress as follows: scanning -> updating -> success.

accounts.pay_distribution_updated or accounts.pay_distribution_failed webhooks will fire once when the removal succeeds or fails, respectively.

If successful, the pay_allocations.removed webhook will fire for the allocation that was removed.

Troubleshooting

When initiating the removal

400 Bad Request can be returned with one of the following error messages:

  • This user's connection has expired and requires re-authentication.
  • A PD update for this account is currently in progress. Please try again in a few minutes.
  • Argyle encountered a problem when updating pay distribution information. Our team has been notified and is investigating.
  • This user's employment account does not support updating pay distribution information.

Standard HTTP errors, such as 401 Unauthorizedand 404 Not Found, are also possible

After the removal was initiated

If the pay allocation cannot be removed due to platform constraints (for example, it is the only allocation and having zero allocations is not permitted), pay_distribution.error will be set to incompatible_config.

If the platform asks Argyle to reauthenticate and it is impossible without the user's input, removal will not be executed. In some cases, the platform may ping the user to submit an MFA token.

Reading webhooks

On success, accounts.pay_distribution_updated will fire. On failure, accounts.pay_distribution_failed will fire.

The pay_allocations.removed webhook will fire if the allocation was removed. It will not fire if the allocation was not removed for any reason.

When removal is initiated, the account is first scanned. Any previously unknown changes will cause pay_allocations.added, pay_allocations.updated and/or pay_allocations.removed to fire. Then, we perform the removal and fire the webhook(s) for any effects caused by the removal.

For example, you want to remove AccX and we have AccA and AccX in our records. 15 minutes ago the user added AccB that we do not have in our records yet:

First, pay_allocations.added fires to announce that we have scanned AccB. Later, pay_allocations.removed fires to announce that we have removed AccX.

Side effects

Removing a user's pay allocations via API may cause changes to the other user's allocations. See below two example scenarios where these side effects would occur:

  • If the removed allocation was the remainder (also known as "primary"), one other allocation may take its place as the remainder:
  • PERCENT values may adjust to reach the sum of 100: