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:
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.
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.
You may call
GET /v1/accounts/<account-id> and extract
pay_distribution.error from the payload.
The status will progress as follows:
scanning -> updating -> success.
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.
400 Bad Request can be returned with one of the following error messages:
Standard HTTP errors, such as
404 Not Found, are also possible
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
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.
accounts.pay_distribution_updated will fire. On failure,
accounts.pay_distribution_failed will fire.
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.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
AccX in our records. 15 minutes ago the user added
AccB that we do not have in our records yet:
pay_allocations.added fires to announce that we have scanned
pay_allocations.removed fires to announce that we have removed
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:
remainder(also known as "primary"), one other allocation may take its place as the
PERCENTvalues may adjust to reach the sum of