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
account
objectAttribute | Type | Description |
---|---|---|
id | string uuid | Unique ID of the payroll account. |
user | string uuid | ID of the user associated with the payroll account. |
employers | array of strings | A 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_item | string | ID 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 | string | Deprecated in favor of link_item . |
item | string | Sequential ID of the Link item, in the format item_123456789 . |
source | string | Denotes 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_at | string timestamp | Time at which the account was connected. Timestamps follow the ISO 8601 standard. |
updated_at | string timestamp | Time at which the account was updated. Timestamps follow the ISO 8601 standard. |
was_connected | boolean | Indicates 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. |
connection | object See underlying attributes | Contains information about connection status and possible connection errors for a given account. |
status *deprecated | string | Deprecated in favor of connection.status . |
error_code *deprecated | string | Deprecated in favor of connection.error_code . |
pay_distribution | object See underlying attributes | Contains information about the direct deposit update process and possible direct deposit switching errors for a given account. |
availability | object 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
connection
Attribute | Type | Description |
---|---|---|
status | string | Represents 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_code | string | Provides information on why the connection failed when connection.status is error .Each error_code has a corresponding error_message . |
error_message | string | Provides 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_at | string timestamp | Timestamp denoting the last time connection status was updated. Timestamps follow the ISO 8601 standard. |
To check an account’s current
status
, you can callGET /accounts/:id
and check all relevant details within theaccounts.connection
object in the response.
Attributes of pay_distribution
pay_distribution
Attribute | Type | Description |
---|---|---|
status | string | Denotes 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_code | string | Provides information on why the direct deposit update was unsuccessful when pay_distribution.status is error .Each error_code has a corresponding error_message . |
error_message | string | Provides 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_at | string timestamp | Timestamp denoting the last time the direct deposit was updated. Timestamps follow the ISO 8601 standard. |
Attributes of availability
availability
Attribute | Type | Description |
---|---|---|
status | string | Denotes 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_at | string timestamp | Timestamp of the last data scan. Timestamps follow the ISO 8601 standard. |
available_count | string | The 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_to | string timestamp | Denotes 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_from | string timestamp | Denotes 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",
"item": "item_000019016",
"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
}
}
}