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.

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

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

Production and Sandbox API keys can be found in Console.

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

Protect your API keys from being revealed. See security for best practices.

Environments#

Argyle provides two environments:

EnvironmentPurposeBase URL
SandboxTestinghttps://api-sandbox.argyle.com/v2
ProductionReal connectionshttps://api.argyle.com/v2

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.

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.

Visit our Data Delivery Guide for more information on data availability after a new account connection.

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

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:

URLDescription
https://status.argyle.com/api/v2/status.jsonSystem-wide operational status
https://status.argyle.com/api/v2/components.jsonIndividual operational status of the API, Link, and Console
https://status.argyle.com/api/v2/summary.jsonBoth system-wide and individual component statuses
https://status.argyle.com/api/v2/incidents.jsonHistory of past incidents, messaging, and time until resolution
https://status.argyle.com/api/v2/scheduled-maintenances.jsonUpcoming scheduled maintenance

Status codes#

The Argyle API uses the following HTTP response codes:

Status codeDescription
200 - OKThe request succeeded.
201 - CreatedThe request succeeded and a new resource was created.
204 - No ContentThe request succeeded and no content was returned.
400 - Bad RequestThe request was invalid and could not be processed.
401 - UnauthorizedInvalid API keys were provided.
402 - Request FailedThe request was valid but could not be processed.
403 - ForbiddenThe API keys provided do not have the necessary permissions required to perform the request.
404 - Not FoundThe requested resource could not be found.
409 - ConflictThe request conflicts with the server state and could not be processed.
429 - Too Many RequestsToo many requests were sent in a given amount of time. See rate limiting.
500, 502, 503, 504 - Server ErrorsThe request failed due to errors on Argyle servers.

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

Updating Argyle status...
© 2024 Argyle Systems Inc.argyle.com