Introduction

Learn about the Argyle API, authentication, environments, security, errors, null values, pagination, rate limiting, and concurrency.

The Argyle API is built on RESTful principles. It returns JSON encoded-responses and accepts JSON payloads. This data is only available through HTTPS to ensure the security of the data being transferred.

You can view the latest updates to the Argyle API—including any new data fields added—in the API Changelog.


Authentication

The Argyle API uses HTTP Basic Auth. The username is your api_key_id and the password is your api_key_secret.

Find your api_key_id and api_key_secret on the Argyle Console.

If invalid credentials are provided, a 401 Unauthorized response code is returned with the corresponding JSON body.

You must use different credentials depending on the environment you are in. If credentials for the wrong environment are used, a 401 Unauthorized response code is returned with the corresponding JSON body.

🚧

To protect your credentials from being revealed on the client-side, invoke the Argyle API from your own server-side applications only.

$ curl -u api_key_id:api_key_secret https://api-sandbox.argyle.com/v1/accounts
{
    "detail": "Invalid username/password."
}
{
    "detail": "Invalid environment."
}

Environments

Argyle API operates in two separate environments: production and sandbox.

The sandbox environment returns mock data. Use the sandbox to test the basic functionality of the API. In the production environment you're working with real account data. Use the production environment to retrieve data from real accounts connected via Argyle Link.

🚧

In the sandbox environment, you can only use the credentials provided below and in the Link Emulator. These are test work accounts.

You can link the sandbox accounts through Argyle Console via the Emulator tab or through your own instance of Argyle Link. To connect sandbox accounts via Argyle Link, you must set the apiHost to point to the sandbox API endpoint.

Find more information on how to configure Link in the Link reference.

API environment URLs
Sandbox <https://api-sandbox.argyle.com/v1>
Production <https://api.argyle.com/v1>
Sandbox credentialsBobSarahJoe
Email[email protected][email protected][email protected]
Usernametest_1test_2test_3
Passwordpassgoodpassgoodpassgood
Verification Code808180828083
Phone number(800) 900-0001(800) 900-0002(800) 900-0003
Driver's licenseD1230001D1230002D1230003

Sandbox environment

Within the Sandbox environment, Argyle provides two slightly different data sets:

  • Rideshare/Delivery — if you select a gig company like Uber or Doordash, the data has more activity information (duration, distance, etc).
  • General — if you select any other company or payroll platform, the data reflects traditional employment records.

When running in a Sandbox environment, you can connect work accounts with the provided sandbox credentials only.

Make sure to select the appropriate credential items. For example, a company called Wellmart might require username and password, while another company, Udre, requires email and password.

📘

Note that inactive sandbox accounts are automatically deleted 60 days after creation.


Security

Follow these best practices to secure your API keys:

  • Do not embed API keys directly in code. API keys that are embedded in code can be accidentally exposed to the public. For example, you may forget to remove the keys from code that you share. Instead of embedding your API keys in your applications, store them in environment variables or in files outside of your application’s source tree.
  • Do not store API keys in files inside your application’s source tree. If you store API keys in files, keep the files outside your application’s source tree to help ensure your keys do not end up in your source code control system. This is particularly important if you use a public source code management system such as GitHub.
  • Review your code before publicly releasing it. Ensure that your code does not contain API keys or any other private information before you make your code publicly available.
  • Delete unneeded API keys to minimize exposure to attacks.
  • Limit one API key pair's usage to a specific system of your platform backend. This limits the scope of each key. If an API key is compromised, you can delete or regenerate the impacted key without needing to update your other API keys.

Errors

In case of an error, an appropriate HTTP response code is sent. The JSON object in the response body contains a single key detail that has a description of an error.

Error status codes

Error codeDescription
200 - OKEverything worked as expected.
201 - CreatedResource has been created.
204 - No ContentOperation has been accepted and no content in response has been sent.
400 - Bad RequestThe request was unacceptable, often due to missing required parameter.
401 - UnauthorizedNo valid API key provided.
402 - Request FailedThe parameters were valid but the request failed.
403 - ForbiddenThe API key doesn't have permissions to perform the request.
404 - Not FoundThe requested resource doesn't exist.
409 - ConflictArguments in the request are in conflict with the server state.
429 - Too Many RequestsToo many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502, 503, 504 - Server ErrorsSomething went wrong on Argyle's end. (These are rare.)

If there is a field validation problem in a POST request, the response JSON object contains all of the fields and their corresponding validation errors.

{
    "detail": "Authentication credentials were not provided."
}
$ curl -X POST -u <key_id>:<key_secret> https://api-sandbox.argyle.com/v1/webhooks
{"name":["This field is required."],"url":["This field is required."]}

Null values

Sometimes in the API call response, you see null as the returned value for a given field. This can happen for one of two reasons:

  1. The data source does not support that field (i.e. it does not hold that information).
  2. The field is supported by the data source but the data in it is not present. This could happen due to optional fields, inactive accounts, etc.
{
    "id": "47b216e2-d334-4235-bc1e-185d15ab18d0",
    "account": "010db8b4-a724-47fc-a17e-733b656312a2",
    "employer": "walmart",
    "created_at": "2019-11-29T09:00:16.384575Z",
    "updated_at": "2019-11-29T09:00:16.384624Z",
    "first_name": "John",
    "last_name": "Smith",
    "full_name": "John Smith",
    "email": "[email protected]",
    "phone_number": null,
    "birth_date": "1990-04-28",
    "picture_url": "https://profile.picture.com/picture.jpeg",
    "address": {
        "line1": null,
        "line2": null,
        "city": null,
        "state": null,
        "postal_code": null,
        "country": null
    },
    "ssn": "***-**-**15",
    "marital_status": null,
    "gender": "male",
    "metadata": {}
}

Pagination

All top-level API resources have support for bulk fetches via "list" API methods. For instance, you can list payouts, list documents, etc.

Each of the responses has next and previous page URLs provided for easier querying of the next and previous results pages. You can use the limit parameter to define the number of results on a page.

When retrieving resources in bulk, make sure to follow the next and previous page URLs to avoid retrieving the same resource multiple times and eliminate redundant calls. Following the URLs means no two requests can happen in parallel — this is by design as it helps to avoid 429 rate limiting responses and retrieving the data can be done in a much more efficient stream-like manner.

In case you want to achieve more throughput, try utilizing concurrency by fetching data from multiple users in parallel.


Pagination Arguments


limit integer optional

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


List Response Object


next string

The URL to request the next page. The returned value is null if this is the last page.


previous string

The URL to request the previous page. The returned value is null if this is the first page.


results array of objects

An array containing the resources requested.


curl 'https://api.argyle.com/v1/link-items?limit=2'
{
    "count": 20575,
    "next": "https://api.argyle.com/v1/link-items?cursor=cD0yMDIxLTEwLTA2KzA5JTNBMzAlM0EyOC40MDQxODclMkIwMCUzQTAw&limit=10&offset=10",
    "previous": null,
    "results": [
        {
            "id": "starbox",
            "item_id": "0176ba6f-c70b-45a8-bd6e-6d7e13b9bfad",
            "name": "Starbox",
            "type": "retail",
            "has_two_fa": false,
            "is_disabled": false,
            "kind": "employer",
            "known_limitations": "Starbox only makes the past 2 years of Payouts data available.",
            "status": "issues",
            "status_details": "Following Walmart's acquisition of Starbox, most Starbox services have been switched off as of 2021-07-15. In Link, users who search for Starbox are now asked to connect their Walmart account instead.",
            "logo_url": "https://company.com/logo.jpg",
            "features": {
                "pay_distribution_update": {
                    "supported": true,
                    "max_allocations": 2,
                    "amount_allocation": true,
                    "percent_allocation": true,
                    "amount_precision": "0.01",
                    "percent_precision": "0.01",
                    "action_types": []
                }
            }
        },
        {
            "id": "suzys_cupcakes",
            "item_id": "0176ac6f-c70b-45a8-fd6e-6d7e13b9bfad",
            "name": "Suzy's Cupcakes",
            "type": "retail",
            "has_two_fa": true,
            "is_disabled": false,
            "kind": "employer",
            "known_limitations": "Suzy's Cupcakes only makes the last 2 digits of SSN available. The rest is obfuscated.",
            "status": "healthy",
            "status_details": null,
            "logo_url": "https://company.com/logo.jpg",
            "features": {
                "pay_distribution_update": {
                    "supported": true,
                    "max_allocations": 1,
                    "amount_allocation": false,
                    "percent_allocation": true,
                    "amount_precision": null,
                    "percent_precision": null,
                    "action_types": []
                }
            }
        }
    ]
}

Rate limiting

The Argyle API employs a number of safeguards against bursts of incoming traffic to help maximize its stability. If you send many requests in quick succession you may see error responses that show up as status code 429 (Too Many Requests). In this case, you need to put that request back into a queue to retry with an exponential backoff

The Argyle API allows a rate of 50 RPS (requests per second).

Running a large volume of closely-spaced requests can lead to rate limiting. Often this can occur as part of an analytical or a migration operation.


Concurrency

You should limit the number of concurrent requests that are in-flight at once. Limiting the number of users that are being processed at once ensures that users are synchronized fully before starting to process another user.

When fetching data from multiple services or multiple instances of the same service, try to avoid repeating the same queries. This can be done with a caching layer between your program and Argyle API. Argyle doesn't do HTTP caching to ensure the data being retrieved is up-to-date.