Accounts

Learn about the /accounts endpoint.

Account objects represent payroll accounts that your users connect via Argyle Link.

You can query accounts by account ID or user ID that you might have obtained through one of the Argyle Link callbacks.

🚧

Accounts that have never successfully connected are removed after 30 days.

The account object

AttributeTypeDescription
idstring uuidUnique ID of the payroll account.
userstring uuidID of the user associated with the payroll account.
employersarray of stringsA list of names of all employers associated with this payroll account. In most cases, this returns a single employer. However, sometimes the same payroll provider (for example, MyADP) is associated with more than one employer.
link_itemstringID of the Link item (employer or payroll provider), that the user selected when connecting their account via Argyle Link. This value is usually human-readable.

link_item supersedes the now deprecated data_partner field.
data_partner
*deprecated
stringDeprecated in favor of link_item.
sourcestringDenotes the source of the account's employment records provided in the Argyle API. The source value is the same as the link_item when a company has an in-house solution for managing employment data:

link_item="udre"
source="udre"

Or it can be different when a company is utilizing a third-party payroll provider:

link_item="gnomedepot"
source="workbay"

In the sandbox environment, source always returns argyle_sandbox, regardless of the link_item.
created_atstring timestampTime at which the account was connected. Timestamps follow the ISO 8601 standard.
updated_atstring timestampTime at which the account was updated. Timestamps follow the ISO 8601 standard.
was_connectedbooleanIndicates whether a payroll account has been successfully connected at some point in the past. Once a payroll account has been successfully connected, was_connected returns true and stays true indefinitely, even if that payroll account becomes disconnected later on.

When a user submits a form, a special account linked to a form Link item is created. In this case, was_connected will always return false, as this account was only used for form creation and did not connect any payroll accounts.
connectionobject

See underlying attributes
Contains information about connection status and possible connection errors for a given account.
status
*deprecated
stringDeprecated in favor of connection.status.
error_code
*deprecated
stringDeprecated in favor of connection.error_code.
pay_distributionobject

See underlying attributes
Contains information about the direct deposit update process and possible direct deposit switching errors for a given account.
availabilityobject

See underlying attributes
The availability object shows the synchronization status and the updated_at fields for each data resource (for example, documents, vehicles, or payouts) within the account. Event data resources (for example, payouts or activities) have additional information pertaining to event count and availability timeframe.

pay_allocations availability is only present if your Argyle account has direct deposit switching enabled. Additionally, if direct deposit switching is enabled, but the pay allocation resource is not available within the Link item, then pay_allocations returns null.

Note: the finances resource has been *deprecated.

For more information on data synchronization, refer to Gradual Data Delivery.

Attributes of connection

AttributeTypeDescription
statusstringRepresents the status of the link between Argyle and the payroll provider. Possible values:

connecting – a connection to the Link item is being established. This status only occurs when a user submits their credentials through Argyle Link for a new account or for an existing account.

connected – account is linked with the Link item. Note that this does not mean the data retrieval has finished. Use the availability field to check if data has been synced.

error – the connection to the Link item is not currently live. Argyle is not able to retrieve data for the account. See connection.error_code below for details.
error_codestringProvides information on why the connection failed when connection.status is error.

Each error_code has a corresponding error_message.
error_messagestringProvides additional information on why the connection error occurred.

Each error_message corresponds to a particular error_code.

For more information on possible values, common causes, and troubleshooting suggestions for these errors, see Account connection errors.
updated_atstring timestampTimestamp denoting the last time connection status was updated. Timestamps follow the ISO 8601 standard.

📘

To check an account’s current status, you can call GET /accounts/:id and check all relevant details within the accounts.connection object in the response.

Attributes of pay_distribution

AttributeTypeDescription
statusstringDenotes the point in the process of the direct deposit update process. Possible values:

- idle - Direct deposit update process has not been initiated.
- awaiting_confirmation - Waiting for the user to confirm their updated direct deposit.
- awaiting_connection - Waiting to establish connection to the user's employment account.
- scanning - Scanning existing pay allocations prior to update process.
- updating - Updating the user's direct deposit.
- success - Direct deposit update successful.
- error – Direct deposit update unsuccessful. See pay_distribution.error_code for details.
error_codestringProvides information on why the direct deposit update was unsuccessful when pay_distribution.status is error.

Each error_code has a corresponding error_message.
error_messagestringProvides additional information on why the direct deposit update error occurred.

Each error_message corresponds to a particular error_code.

For more information on possible values, common causes, and troubleshooting suggestions for these errors, see our direct deposit switching errors guide.
updated_atstring timestampTimestamp denoting the last time the direct deposit was updated. Timestamps follow the ISO 8601 standard.

Attributes of availability

AttributeTypeDescription
statusstringDenotes the status of the data scan. Possible values:

in_progress - Initial data retrieval is in progress.

synced - Data is synced as of the time indicated in the updated_at field.

sync_failed - Data retrieval failed. Please refer to connection.error_code to troubleshoot potential problems.
updated_atstring timestampTimestamp of the last data scan. Timestamps follow the ISO 8601 standard.
available_countstringThe number of available events—for example, activities, payouts.

During the first scan of an account, the value of this field changes with each scanning iteration until the availability.status becomes synced.
available_tostring timestampDenotes the end point of the time interval, for which the events (for example, activities or payouts) are available. Timestamps follow the ISO 8601 standard.

During the first scan of an account, the value of this field will change with each scanning iteration until the availability.status becomes synced.
available_fromstring timestampDenotes the start point of the time interval, for which the events (for example, activities or payouts) are available. Timestamps follow the ISO 8601 standard.

During the first scan of an account, the value of this field will change with each scanning iteration until the availability.status becomes synced.

Endpoints

These are the endpoints available for accounts.

Endpoints
Retrieve an account - GET /accounts/:id
List accounts - GET /accounts
Delete an account - DELETE /accounts/:id

Example objects

{
    "id": "ac81e2bc-2157-4535-8ca4-fb1f068df1fc",
    "user": "53fe928d-9c6a-460b-b5ac-19d67304d106",
    "employers": [
        "homedepot"
    ],
    "link_item": "homedepot",
    "data_partner": "homedepot",
    "source": "workday",
    "created_at": "2019-11-27T15:55:56.771322Z",
    "updated_at": "2019-11-29T08:37:42.164522Z",
    "was_connected": true,
    "connection": {
        "status": "connected",
        "error_code": null,
        "error_message": null,
        "updated_at": "2019-11-29T08:37:42.112859"
    },
    "pay_distribution": {
        "status": "success",
        "error": null,
        "error_message": null,
        "updated_at": "2019-11-29T08:37:42.164522Z"
    },
    "availability": {
        "profiles": {
            "status": "synced",
            "updated_at": "2019-11-29T08:37:42.164522Z"
        },
        "employments": {
            "status": "synced",
            "updated_at": "2019-11-29T08:37:42.164522Z"
        },
        "finances": {
            "status": "synced",
            "updated_at": "2019-11-29T08:37:42.164522Z"
        },
        "reputations": {
            "status": "synced",
            "updated_at": "2019-11-29T08:37:42.164522Z"
        },
        "documents": {
            "status": "synced",
            "updated_at": "2019-11-29T08:37:42.164522Z"
        },
        "vehicles": {
            "status": "synced",
            "updated_at": "2019-11-29T08:37:42.164522Z"
        },
        "pay_allocations": {
            "status": "synced",
            "updated_at": "2019-11-29T08:37:42.164522Z"
        },
        "payouts": {
            "status": "synced",
            "updated_at": "2019-11-29T08:37:42.164522Z",
            "available_count": 3,
            "available_from": "2019-10-30T00:00:00Z",
            "available_to": "2018-11-27T00:00:00Z"
        },
        "activities": {
            "status": "synced",
            "updated_at": "2019-11-29T08:37:42.164522Z",
            "available_count": 146,
            "available_to": "2019-11-29T08:37:42.164522Z",
            "available_from": "2018-12-15T20:40:50.399677Z"
        },
        "forms": null
    }
}
{
    "id": "ac81e2bc-2157-4535-8ca4-fb1f068df1fc",
    "user": "53fe928d-9c6a-460b-b5ac-19d67304d106",
    "employers": [
        "homedepot"
    ],
    "link_item": "homedepot",
    "source": "workday",
    "created_at": "2019-11-27T15:55:56.771322Z",
    "updated_at": "2019-11-29T08:37:42.164522Z",
    "was_connected": true,
    "connection": {
        "status": "error",
        "error_code": "invalid_credentials",
        "error_message": null,
        "updated_at": "2019-11-29T08:37:42.112859"
    },
    "pay_distribution": {
        "status": "idle",
        "error": null,
        "error_message": null,
        "updated_at": "2019-11-29T08:37:42.164522Z"
    },
    "availability": {
        "activities": null,
        "payouts": null,
        "documents": null,
        "profiles": null,
        "employments": null,
        "reputations": null,
        "vehicles": null,
        "pay_allocations": null,
        "forms": {
            "status": "synced",
            "updated_at": "2021-11-23T14:19:43.569653Z",
            "available_count": 1,
            "files_count": 1,
            "in_progress_count": 0
        }
    }
}
{
    "id": "ac81e2bc-2157-4535-8ca4-fb1f068df1fc",
    "user": "53fe928d-9c6a-460b-b5ac-19d67304d106",
    "employers": [],
    "link_item": "form_link_item",
    "source": "sandbox",
    "created_at": "2019-11-27T15:55:56.771322Z",
    "updated_at": "2019-11-29T08:37:42.164522Z",
    "was_connected": true,
    "connection": {
        "status": "connecting",
        "error_code": null,
        "error_message": null,
        "updated_at": "2019-11-29T08:37:42.112859"
    },
    "pay_distribution": {
        "status": "idle",
        "error": null,
        "error_message": null,
        "updated_at": "2019-11-29T08:37:42.164522Z"
    },
    "availability": {
        "activities": null,
        "payouts": null,
        "documents": null,
        "profiles": null,
        "employments": null,
        "reputations": null,
        "vehicles": null,
        "pay_allocations": null,
        "forms": {
            "status": "synced",
            "updated_at": "2021-11-23T14:22:12.334817Z",
            "available_count": 1,
            "files_count": 1,
            "in_progress_count": 0
        }
    }
}