Overview

Learn about the Argyle API.

Introduction#

• The Argyle API is built on RESTful principles.
• The API operates over HTTPS to ensure the security of data being transferred.
• All requests and responses are sent in JSON.

• Visit our API Reference to learn more about each endpoint, and see example requests and responses.
• Subscribe to our Changelog to receive updates on changes to the API.

Creating API keys#

Production and Sandbox API keys can be created in Console.

Authentication#

All API requests are authenticated over standard HTTP basic authentication.

• username — api_key_id
• password — api_key_secret

Example

1$ curl https://api-sandbox.argyle.com/v2/accounts \
2  -u api_key_id: api_key_secret

When making API requests, API keys must match the base URL environment (see below), otherwise a 401-Unauthorized response code will be returned.

Environments#

Argyle provides two environments:

Both Link and the API can be used in either the Sandbox or Production environment.

The Sandbox environment lets you connect sample users in Link, and retrieve their sample data via the API. Visit our dedicated Sandbox Testing Guide for more information.

All API endpoints can be used in either the Sandbox or Production environment, with the exception of an additional Sandbox endpoint that lets you simulate data refreshes and update sample data.

Data availability#

Data is collected in stages after a new account is connected:

Fact data

• Available soon after a payroll connection.
• Static information that tends to change less over time.

Event data

• Retrieved and made available from most recent to least recent.
• Time-dependent information that can go back a number of years.

Fact data is initially used to populate fields within Argyle's data sets. As event data is retrieved, previously populated fields are updated and refined, and new data is added to the relevant fields that were previously empty.

After initial data retrieval, Argyle continuously scans and retrieves any new data that is added to a user's payroll account.

Breaking changes#

Implementations should accommodate additional fields and response values being added to existing endpoints as we continuously expand our data granularity.

Argyle considers the following changes to be breaking:

• Changing authentication or authorization requirements
• Removing or re-naming an endpoint
• Removing or re-naming a webhook
• Removing or re-naming a required request parameter
• Adding a required request parameter (including previously optional parameters)
• Removing or re-naming any field name (including objects, arrays, or individual properties)
• Changing the type of any field, request parameter, or query parameter

Argyle considers the following changes to be non-breaking:

• Adding an endpoint
• Adding a webhook
• Adding an optional request parameter
• Adding additional response fields (including objects, arrays, or individual properties)
• Returning new response field values
• Returning additional enum values, including new errors
• Changes to error messages
• Fixes to HTTP response codes from an incorrect code to a correct code

Security#

Secure your API keys using these best practices:

• Only invoke the Argyle API from your own server-side applications.

• Avoid including or adding checks for your API keys in client-side code.

• Store API keys in environment variables or files outside your application's source tree, instead of embedding them directly in your application.

  Storing API keys outside your application's source tree is particularly important if you use a public source code management system such as Github.

• Use one set of API keys for each backend system on your platform. This limits the scope of compromised API keys.

• Delete unused API keys.

System status#

Argyle publishes the operational status of the API, Link, and Console on status.argyle.com. Incidents and related messaging will be posted on this status page and sent to subscribers automatically.

GET requests made to the following URLs can also be used to retrieve status and incident information programmatically:

Status codes#

The Argyle API uses the following HTTP response codes:

Error responses#

When an error occurs, a JSON object is sent in the response describing the error.

Example

1{ "detail": "Authentication credentials were not provided." }

Field validation errors in POST requests return a JSON object that lists the invalid fields alongside troubleshooting suggestions.

Example

1// Example error response when creating a new webhook:
2
3{ "name": ["This field may not be blank."], "url": ["Enter a valid URL."] }

Null values#

Individual fields may return null values when:

• The data source does not support that field.
• The data source supports the field, but no information is present.

Example

1{
2    "...",
3        "address": {
4            "line1": "759 Victoria Plaza",
5            "line2": null,
6            "state": "NY",
7            "country": "US",
8            "postal_code": "10014"
9        },
10        "first_name": "Bob",
11        "last_name": "Jones",
12        "marital_status": null,
13    "..."
14}

Pagination#

All “List” GET requests (“list paystubs”, “list identities”, etc.) return paginated results.

The number of results per page can be defined by using the limit parameter when making the request. The default number of results per page is 10, and the maximum is 200.

Paginated responses will have next and previous page URLs:

1// List users - GET https://api-sandbox.argyle.com/v2/users
2
3{
4    "next": "https://api-sandbox.argyle.com/v2/users?cursor=bC0yMDIzLTAyLTA5KzE2JTNCMzAlM0EzNC43MDU0MDMlMkIwMCUzQTAw",
5    "previous": null,
6    "results": [
7        { "..." },
8        { "..." }
9    [
10}

To retrieve the next page of results, repeat the GET request using the URL in the next field.

Following the next and previous page URLs helps avoid retrieving duplicate results and eliminates redundant calls. This ensures no two requests can happen in parallel to avoid 429 rate limiting responses.

See concurrency below if you are bulk fetching data using parallel requests.

Rate limiting#

The API allows 50 requests per second. If this rate is exceeded, a 429 status code will be returned.

Rate limiting may occur during periods of high request volume, often related to analytical or data migration operations.

We recommend including a retry method in your applications that responds to 429 status codes by scaling down your request volume and returning rate limited requests to your queue.

Concurrency#

The API does not use HTTP caching to ensure the data you retrieve is up-to-date. Any caching layers used must be between your application and the API.

We recommend limiting the amount of simultaneous requests to the API. This prevents rate limiting and helps avoid repeat queries, resulting in improved data synchronization.

API Reference