API Reference

Authentication

API authentication

Response

Environments

API environment URLs

Sandbox credentials

Security

Errors

Field validation error response

Null values

Example profile object

limit

The number of objects to be returned. The default value is 10. The maximum value is 200.

results

An array containing the resources requested.

Pagination

List data partners

Rate limiting

Concurrency

is_active


Only active webhooks will receive webhook calls from Argyle.


events

An array of Argyle's webhook event types (e.g., `["activities.added"])`. Refer to the [webhooks reference](/docs/developer-tools/webhooks-reference) for a full list of available event types.


The endpoint that will be invoked when the specified event occurs.


config

Configuration options of the webhook. Refer to the [webhooks reference](/docs/developer-tools/webhooks-reference) to learn more about available configuration parameters.

name


An arbitrary name that will be sent back to your system in the webhook payload.


secret


The key that will be used to generate HMAC-SHA512 hex digest value in the `X-Argyle-Signature` header.


Webhooks

Endpoints

The webhook object

Webhook example


Identifier of the webhook object to be retrieved.


Retrieve a webhook


The number of webhook objects to be returned. The default is 10. Max value is 200.


List webhooks

An array of Argyle webhook [event types](/docs/developer-tools/webhooks-reference).  Specify `['*']` to subscribe to all webhook events.


If provided, `secret` will be used as a key in the `HMAC-SHA512 `algorithm to generate a hex digest, which will then be included in the `X-Argyle-Signature` header in every webhook request to your system.


Create a webhook

Delete a webhook

Companies and Platforms


Unique ID of the Link item. A lot of the time (but not always) Link item IDs will be human-readable. For human-readable values, refer to the `name` attribute.



Name of the Link item (e.g., Walmart, Uber, Gusto).


type


Type of the Link item (e.g., delivery, retail, rideshare, services, technology).


kind


Type of the Link item (e.g. employer, gig, platform).


logo_url


A URL to the Link item logo. Authentication is required to access this field.


is_disabled


Will be `true` if the Link item is disabled. Link items are disabled if there is an issue with the underlying data provider.


has_two_fa


Will be `true` if the underlying data provider requires two-factor authorization to log in.


features.pay_distribution_update

Contains information about pay distribution update capabilities of a given Link item. Please refer to the [Pay Distribution Guide]() for more information.

features.pay_distribution_update.supported


Denotes if the Link item supports pay distribution updates.

If `false`, the features fields will not be shown in the API response.


features.pay_distribution_update.max_allocations


Denotes the maximum amount of allocations an account can have in the given Link item.


features.pay_distribution_update.percent_allocation


Denotes if the Link item allows setting percent allocations (e.g. 60% to one bank account and remained to another).


features.pay_distribution_update.percent_precision


Denotes the level of granularity of the pay distribution percentage. This way you can define the percentage of the pay distribution with up to the 4 decimal places.

Possible values:  `100`, `10`, `1`, `0.1`, `0.01`, `0.001`, `0.0001`.


features.pay_distribution_update.amount_allocation


Denotes if the Link item allows setting amount allocations (e.g. $500 to one bank account and remained to another).


features.pay_distribution_update.amount_precision


Denotes the level of granularity of the pay distribution amount. This way you can define the amount up to the cent level of detail - with 2 decimals.

Possible values:  `100`, `10`, `1`, `0.1`, `0.01`.


features.pay_distribution_update.microdeposit_verification

Denotes if the Link item requests for microdeposit verification.

Link items

The Link item object


The identifier of the Link item to be retrieved.


Retrieve a Link item


Only return Link items with the provided IDs. Multiple IDs should be separated by commas.



Only return Link items with the provided name. Only one name can be provided by using filtering by name. To filter multiple Link items, please use filtering by ID.



The number of Link item objects to be returned. The default is 10. Max value is 200.



If set to `true`, the response will contain only Link items, which support pay distribution updates.



Return Link items with the specified number of maximum allocations allowed.


features.pay_distribution_update.max_allocations.gt


Return Link items where the `max_allocations` field is greater than this value.


features.pay_distribution_update.max_allocations.gte


Return Link items where the `max_allocations` field is greater than or equal to this value.


features.pay_distribution_update.max_allocations.lt


Return Link items where the `max_allocations` field is less than this value.


features.pay_distribution_update.max_allocations.lte


Return Link items where the `max_allocations` field is less than or equal to this value.



If set to `true`, the response will contain only Link items, which support percent allocations.



If set to `true`, the response will contain only Link items, which support amount allocations.


The kind of Link items to be returned. A single value is accepted.

Possible values: `employer`, `gig`, `platform`.

kind.not_in

The kinds of Link items to be omitted. A comma-separated list of kinds is accepted.

Possible values: `employer`, `gig`, `platform`.

List Link items

The name of the Link Item to be searched.


The kind of Link items to be returned. A single value is accepted.

Possible values: `employer`, `gig`, `platform`.



The kinds of Link items to be omitted. A comma-separated list of kinds is accepted.

Possible values: `employer`, `gig`, `platform`.



The number of Link items to be returned. The default is 15. Max value is 200.


Search Link items

User Management

created_at


Time at which the user was created. Timestamps follow the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) standard.


employers_connected


A list of names of employers that the user has connected to via Argyle Link. This list might be different from `data_providers_connected`, which can include payroll platforms (e.g. MyADP). The connections might be active or previously connected employers, which are no longer active (for example, due to a user switching jobs).


data_providers_connected

A list of [Link item](/docs/developer-tools/api-reference#companies-and-platforms-link-items) IDs that the user has connected. The connections might be active or previously connected Link items, which are no longer active (for example, due to a user switching jobs).

external_metadata

You can set external metadata when [creating](/docs/developer-tools/api-reference#users-create-a-user) or [updating](/docs/developer-tools/api-reference#users-update-a-user%E2%80%99s-metadata) a user. This external metadata can be used to map users between Argyle and your own database. External metadata can be any valid JSON — e.g. a string or an object.

Users

The user object

Create a user


External metadata can be any valid JSON — e.g. a string or an object.


Add metadata to a user


ID of the user, whose metadata should be updated.


Update a user’s metadata


The identifier of the user to be retrieved.


Retrieve a user


The number of user objects to be returned. The default is 10. Max value is 200.




List users

Delete a user

User tokens

user


ID of the user to create a new token for.




Create a token


ID of the user associated with the account.


employers


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


link_item

ID of the Link item (i.e. company or platform), that the user selected when connecting their account via [Argyle Link](/docs/products/argyle-link). This value will oftentimes be human-readable.

`link_item` supersedes the now deprecated `data_partner` field.

source


Denotes the source of the account&#39;s employment records provided in the Argyle API. `Source` value will be the same as `link_item` when a company has an in-house solution for managing employment data:

`link_item`=&quot;uber&quot;

`source`=&quot;uber&quot; 

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

`link_item`=&quot;homedepot&quot;

`source`=&quot;workday&quot; 



Time at which the account was connected. Timestamps follow the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) standard.


updated_at


Time at which the account was updated. Timestamps follow the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) standard.


connection.status


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. Please note, that this does not mean the data pull has finished. Use the `availability` field to check if data has been synced.

`error` – account is not linked to the Link item. Argyle is not able to pull data for the account. See `connection.error_code` below for details.


connection.error_code


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

Possible values: `account_disabled`, `account_inaccessible`, `account_incomplete`, `auth_required`, `expired_credentials`, `invalid_account_type`, `invalid_auth`, `invalid_credentials`, `invalid_mfa`, `login_attempts_exceeded`, `mfa_not_configured`, `mfa_timeout`, `service_unavailable`, `system_error`, `tos_required`, `trial_period_expired`, `unsupported_auth_type`, `unsupported_mfa_method`.

Each `error_code` has a corresponding `error_message` (see below).


connection.error_message

Provides additional information on why the connection error occurred. Each `error_message` corresponds to a particular `error_code` (see above). The list below is formatted as:

`error_code` - error_message

Possible values:

`account_disabled` - this user's employment account appears to be suspended or disabled.

`account_inaccessible` - this user's account is not currently accessible. Our team has been notified and is investigating.

`account_incomplete` - this user's employment account is not yet active.

`auth_required` - this user's connection has expired and requires re-authentication.

`expired_credentials` - this user provided credentials which are out of date (i.e., a password reset is required).

`invalid_account_type` - this user provided credentials for the wrong account type (e.g., a passenger account rather than a driver account, or an admin account rather than an employee account).

`invalid_auth` - this user's account login was unsuccessful, either due to invalid credentials or unsuccessful multi-factor authentication.

`invalid_credentials` - this user provided invalid credentials.

`invalid_mfa` - this user did not provide the correct multi-factor authentication response.

`login_attempts_exceeded` - this user provided invalid credentials too many times, causing them to be temporarily unable to attempt further logins.

`mfa_not_configured` - this user has not configured multi-factor authentication for their employment account, restricting access to the user's employment data.

`mfa_timeout` - this user did not complete multi-factor authentication.

`service_unavailable` - the platform this user is attempting to connect to is currently unavailable. See the [Coverage page]() in Console for additional information.

`system_error` - Argyle encountered a problem connecting to this account. Our team has been notified and is investigating.

`tos_required` - this user has not accepted the Terms of Service presented by their payroll provider, preventing access to their employment account.

`trial_period_expired` - this user's employment account is in a trial account, and is currently disabled because the trial period has expired.

`unsupported_auth_type` - this user tried to log in using single sign-on (e.g., Google, Facebook), which Argyle does not currently support.

`unsupported_mfa_method` - this user's employment account uses a multi-factor authentication method that Argyle does not currently support.

connection.updated_at


Timestamp denoting the last time connection status was updated. Timestamps follow the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) standard.


pay_distribution.status


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&#39;s employment account.

`scanning` - scanning existing pay allocations prior to update process.

`updating` - updating the user&#39;s pay distribution.

`success` - pay distribution update successful.

`error` – pay distribution update unsuccessful. See the `pay_distribution.error_code` below for details.


pay_distribution.error_code

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

Possible values: `confirmation_timeout`, `incompatible_config`, `invalid_mfa`, `mfa_not_configured`, `mfa_timeout`, `missing_allocation_type`, `not_supported`, `not_supported_by_employer`, `rejected_bank_account`, `rejected_routing_number`, `service_unavailable`, `system_error`, `unsupported_allocation_type`, `unsupported_bank_accounts`,  `unsupported_mfa_method`, `waiting_period`.

Each `error_code` has a corresponding `error_message` (see below).

pay_distribution.error_message

Provides additional information on why the pay distribution update error occurred. Each `error_message` corresponds to a particular `error_code` (see above). The list below is formatted as:

`error_code` - error_message

Possible values:

`confirmation_timeout` - this user did not finish setting up their new pay distribution.

`incompatible_config` - the pay allocation details that have been submitted are not supported by this user's employment account.

`invalid_mfa` - this user did not provide the correct multi-factor authentication response.

`mfa_not_configured` - this user has not configured multi-factor authentication for their employment account, restricting access to the user's employment data.

`mfa_timeout` - this user did not complete multi-factor authentication.

`missing_allocation_type` - one or more of this account's pay allocations is missing a type (percent/amount/remainder), causing Argyle to be unable to update the user's pay distribution information.

`not_supported` - this user's employment account does not support updating pay distribution information.

`not_supported_by_employer` - this user's employment account does not support changes to pay distribution information. This may be because the employer has disabled users from editing this information.

`rejected_bank_account` - the provided bank account cannot be used for pay distribution update. Please provide a different bank account.

`rejected_routing_number` - the provided routing number is considered invalid by this user's employment account.

`service_unavailable` - this user's employment platform is experiencing downtime and is currently unable to process updates to pay allocations.

`system_error` - Argyle encountered a problem when reading or updating pay distribution information. Our team has been notified and is investigating.

`unsupported_allocation_type` - one or more of this account's pay allocations is not currently supported, causing Argyle to be unable to update the user's pay distribution information. Supported allocation types are percent, amount and remainder.

`unsupported_bank_accounts` - this user's employment account includes pay allocations to bank account types that Argyle does not yet support, like HSAs.

`unsupported_mfa_method` - this user's employment account uses a multi-factor authentication method that Argyle does not currently support.

`waiting_period` - pay distribution update is temporarily unavailable. This can happen when an employer requires a waiting period after recent pay distribution updates or after initial account creation.

pay_distribution.updated_at


Timestamp denoting the last time pay distribution was updated. Timestamps follow the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) standard.


availability

The `availability` object shows the synchronization `status` and the `updated_at` fields for each data resource (e.g., documents, vehicles, payouts, etc.) within the account. Event data resources (e.g. payouts, 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 the [Gradual Data Delivery](/docs/products/data-structure#gradual-data-delivery) section in the [Data Structure Guide]().

availability.status

Denotes the status of the data scan. Possible values:

`in_progress` - initial data pull is in progress.

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

`sync_failed` - data pull failed. Please refer to `connection.error_code` to troubleshoot potential problems.

availability.updated_at


Timestamp of the last data scan. Timestamps follow the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) standard.


availability.available_count


The number of available events (e.g. 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


Denotes the end point of the time interval, for which the events (e.g. activities, payouts) are available. Timestamps follow the [ISO 8601](https://en.wikipedia.org/wiki/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


Denotes the start point of the time interval, for which the events (e.g. activities, payouts) are available. Timestamps follow the [ISO 8601](https://en.wikipedia.org/wiki/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`.


status


`status` is deprecated in favor of `connection.status`.


error_code


`error_code` is deprecated in favor of `connection.error_code`.


data_partner


data_partner is deprecated in favor of `link_item`.


Accounts

The account object (Link item connected)

The account object (documents uploaded via invalid credentials flow)

The account object (documents uploaded via questionnaire flow)


The identifier of the account to be retrieved


Retrieve an account


Only return accounts for the data partner with the provided ID.



Only return accounts for the user with the provided ID.



The number of account objects to be returned. The default is 10. Max value is 200.


List accounts

Delete an account

Invites

Forms

Represents the status of the form. Possible values:

`submitted`: Signifies that a form has been submitted by the user with all mandatory fields completed.

data.employer_name

The value entered by the user when prompted for their employer name. Only available if you have configured this form in Link Customizer. This field will be present if the user initiated the document upload flow via the **Can't find your employer?** button.

data.payroll_platform

The value selected by the user when prompted for their payroll platform. Only available if you have configured this form in Link Customizer. This field will be present if the user initiated the document upload flow via the **Can't find your employer?** button.

data.paystubs

A list of paystub documents uploaded by the user. Only relevant if you have configured paystubs in Link Customizer.

data.form_1099

A list of 1099 documents uploaded by the user. Only relevant if you have configured 1099 documents in Link Customizer.

data.form_w2

A list of W2 documents uploaded by the user. Only relevant if you have configured W2 documents in Link Customizer.

<file>.file_id

<file>.status

Represents the status of the file. Possible values:

`AVAILABLE`: Signifies that the file can be viewed/downloaded using the URL reference provided in the `url` field

<file>.url

URL reference where the file can be found. The `url` contains a publicly accessible URL to the file. The URL is valid for one hour.