Accounts & connections

Account objects represent data partner accounts that your users connect to 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.

Attributes

id string uuid

Unique ID of the account.

user string uuid

ID of the user associated with the account.

employers array of strings

A list of names of all employers associated with this account. In most cases, this returns a single employer. However, sometimes the same payroll platform account (for example, MyADP) is associated with more than one employer.

link_item string

ID of the Link item (in other words, company or platform), 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.

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 platform:

link_item="gnomedepot"

source="workbay"

📘
In the sandbox environment, source always returns argyle_sandbox, regardless of the link_item.

created_at string

Time at which the account was connected. Timestamps follow the ISO 8601 standard.

updated_at string

Time at which the account was updated. Timestamps follow the ISO 8601 standard.

was_connected boolean

Indicates whether the account has been successfully connected at some point in the past. Once an account has been successfully connected, was_connected returns true and stays true indefinitely, even if that account becomes disconnected later on.

When a user submits a form, a special account linked to a form Link item is created. This type of account will always return was_connected as false, as it is only used for form creation and does not connect any employment data.

connection.status boolean

Represents the status of the link between Argyle and the work platform. 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.

📘
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.

connection.error_code string

Provides information on why the connection failed when connection.status is error.

Each error_code has a corresponding error_message.

connection.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 the Account connection errors page.

connection.updated_at string

Timestamp denoting the last time connection status was updated. Timestamps follow the ISO 8601 standard.

pay_distribution.status string

Denotes the point in the process of the pay distribution update process. Possible values:

idle - Pay distribution update process has not been initiated.
awaiting_confirmation - Waiting for the user to confirm updated pay distribution.
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 pay distribution.
success - Pay distribution update successful.
error – Pay distribution update unsuccessful. See pay_distribution.error_code for details.

pay_distribution.error_code string

Provides information on why the pay distribution update was unsuccessful when pay_distribution.status is error.

Each error_code has a corresponding error_message.

pay_distribution.error_message string

Provides additional information on why the pay distribution 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 the Pay distribution errors page.

pay_distribution.updated_at string

Timestamp denoting the last time pay distribution was updated. Timestamps follow the ISO 8601 standard.

availability object

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 will only be present if your Argyle account has pay distribution updating enabled. Additionally, if pay distribution updating is enabled, but the pay allocation resource is not available within the Link item platform, then pay_allocations will be null.

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

availability.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.

availability.updated_at string

Timestamp of the last data scan. Timestamps follow the ISO 8601 standard.

availability.available_count string

The number of available events—for example, activities, payouts.

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

availability.available_to string

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.

availability.available_from string

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.

Deprecated

status string

status is deprecated in favor of connection.status.

error_code string

error_code is deprecated in favor of connection.error_code.

data_partner string

data_partner is deprecated in favor of link_item.

Endpoints

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",
   "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"
      },
      "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
      }
   }
}