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

API authentication:

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

Environments#

Argyle API operates in two separate environments:

• Production
• 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.

You can link the sandbox accounts through Argyle Console via Flows 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 our Link Configuration Reference.

API Environment URLs:

• https://api-sandbox.argyle.com/v1
• https://api.argyle.com/v1

Sandbox credentials:

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.

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.

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:

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

Field validation error response:

1// Example:
2// $ curl -X POST -u <key_id>:<key_secret> https://api-sandbox.argyle.com/v1/webhooks
3
4{
5    "name": [
6        "This field is required."
7    ],
8    "url": [
9        "This field is required."
10    ]
11}

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:

• The data source does not support that field (i.e. it does not hold that information).
• 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.

Example profile object:

1{
2    "id": "47b216e2-d334-4235-bc1e-185d15ab18d0",
3    "account": "010db8b4-a724-47fc-a17e-733b656312a2",
4    "employer": "walmart",
5    "created_at": "2019-11-29T09:00:16.384575Z",
6    "updated_at": "2019-11-29T09:00:16.384624Z",
7    "first_name": "John",
8    "last_name": "Smith",
9    "full_name": "John Smith",
10    "email": "[email protected]",
11    "phone_number": null,
12    "birth_date": "1990-04-28",
13    "picture_url": "https://profile.picture.com/picture.jpeg",
14    "address": {
15        "line1": null,
16        "line2": null,
17        "city": null,
18        "state": null,
19        "postal_code": null,
20        "country": null
21    },
22    "ssn": "***-**-**15",
23    "marital_status": null,
24    "gender": "male",
25    "metadata": {}
26}

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.

If for example you have 900 connected users, after calling GET https://api-sandbox.argyle.com/v1/users?limit=200 you will receive a response that lists 200 users. At the top of the response is the next URL:

1"next": "https://api-sandbox.argyle.com/v1/users?cursor=cD0yABCyLTA5LTI2KzEzJTNBBTMlM0E1OC4yNTUwMjYlMkIwMCUzQTAw&limit=200"

To retrieve the next 200 users, call GET https://api-sandbox.argyle.com/v1/users?cursor=cD0yABCyLTA5LTI2KzEzJTNBBTMlM0E1OC4yNTUwMjYlMkIwMCUzQTAw&limit=200 (the URL of the next field).

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

Example — List Link items:

1// curl 'https://api.argyle.com/v1/link-items?limit=2'
2
3{
4    "count": 20575,
5    "next": "https://api.argyle.com/v1/link-items?cursor=cD0yMDIxLTEwLTA2KzA5JTNBMzAlM0EyOC40MDQxODclMkIwMCUzQTAw&limit=10&offset=10",
6    "previous": null,
7    "results": [
8        {
9            "id": "starbox",
10            "item_id": "0176ba6f-c70b-45a8-bd6e-6d7e13b9bfad",
11            "name": "Starbox",
12            "type": "retail",
13            "has_two_fa": false,
14            "is_disabled": false,
15            "kind": "employer",
16            "known_limitations": "Starbox only makes the past 2 years of Payouts data available.",
17            "status": "issues",
18            "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.",
19            "logo_url": "https://company.com/logo.jpg",
20            "features": {
21                "pay_distribution_update": {
22                    "supported": true,
23                    "max_allocations": 2,
24                    "amount_allocation": true,
25                    "percent_allocation": true,
26                    "amount_precision": "0.01",
27                    "percent_precision": "0.01",
28                    "action_types": []
29                }
30            }
31        },
32        {
33            "id": "suzys_cupcakes",
34            "item_id": "0176ac6f-c70b-45a8-fd6e-6d7e13b9bfad",
35            "name": "Suzy's Cupcakes",
36            "type": "retail",
37            "has_two_fa": true,
38            "is_disabled": false,
39            "kind": "employer",
40            "known_limitations": "Suzy's Cupcakes only makes the last 2 digits of SSN available. The rest is obfuscated.",
41            "status": "healthy",
42            "status_details": null,
43            "logo_url": "https://company.com/logo.jpg",
44            "features": {
45                "pay_distribution_update": {
46                    "supported": true,
47                    "max_allocations": 1,
48                    "amount_allocation": false,
49                    "percent_allocation": true,
50                    "amount_precision": null,
51                    "percent_precision": null,
52                    "action_types": []
53                }
54            }
55        }
56    ]
57}

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.