>  Switch To Link 5 and API v2 Documentation

Data Retrieval

Learn how you can retrieve data via the Argyle API.

The two most common scenarios for retrieving data via the Argyle API are:

  • Gradual data delivery. A user has just connected their account and Argyle has started fetching the data. You want to make a business decision (for example, loan underwriting) based on the data as soon as possible while the user is still present.
  • Continuous data access. A user has connected their account some time ago and you want to receive updates on their data to make less time-sensitive decisions—for example, to make sure that the user is still employed and receiving payments.

Gradual data delivery#

The data pull from the payroll platform starts immediately after a new account is linked. An account is considered to be linked when a user enters their login details and Argyle has successfully authenticated their credentials.

Delivery times can vary, depending on the data retrieval speed a payroll platform can support. Employment types such as gig work with a higher number of discrete activities and payouts can also influence delivery times.

You should design your integration with the Argyle API by leveraging Argyle webhooks to gradually receive data when it becomes available. profiles.added, employments.added, and other added webhooks trigger when the Argyle API scans a data resource and makes the data available for retrieval.

Webhooks let you stay up-to-date with any new data added, updated, or deleted in real-time. For example, when the user links a new work account, Argyle immediately calls an HTTP endpoint on your system to let you know about the event.

You can configure some webhooks to also return the full resource. In these cases, you receive the relevant data gradually, when it becomes available, instead of having to call for it.

For other webhooks, you receive properties that help you build optimal queries for Argyle data retrieval. When you receive a notification from these webhooks, you will know that the data is available, have relevant properties, and you can then initiate data retrieval.

Learn how to subscribe to webhooks and see our Webhooks Reference for a complete list of examples for webhook subscription calls.

Keep new accounts in sync#

  1. Subscribe to the accounts.updated webhook event:

    1// POST /v1/webhooks
2
3{
4    "config": {
5        "include_resource": true
6    },
7    "events": [
8        "accounts.added"
9    ],
10    "name": "Added Accounts",
11    "url": "<https://my.site/webhooks>"
12}

  2. Start receiving webhook payloads for every newly created account:

    1{
2    "event": "accounts.added",
3    "name": "Added Accounts",
4    "data": {
5        "account": "<account-id>",
6        "user": "<user-id>",
7        "resource": {
8            "availability": {
9                "payouts": {
10                    "..."
11                },
12                "..."
13            }
14        }
15    }
16}

  3. Compare the fields within the availability object with the data stored in your system.

  4. If these are different, fetch the corresponding resources from the Argyle API using: GET /v1/payouts?account=<account-id>.

Make decisions when enough payout data has synced#

Webhooks can help you make decisions based on partial historical information of payouts. Follow this guidance to speed up and empower your decision making:

  1. Subscribe to the payouts.partially_synced webhook with a custom range of days to sync. You can subscribe to this webhook multiple times—for example, you could request the last 30 days, then 90 days or any time period that suits your needs for this data. This way you will know when the most relevant (recent) data is available and can take immediate action.

    Example webhook subscription:

    1curl -X POST https://api.argyle.com/v1/webhooks \
2  -u test_client:test_secret \
3  -H "Content-Type: application/json" \
4  -d '{
5    "events": ["payouts.partially_synced"], \\
6    "name": "payouts.partially_synced_cr", \\
7    “config”: { “days_synced” : 30 }, \\
8    "url": "https://webhook.site/url"
9  }'

    Example webhook:

    1{
2    "event": "payouts.partially_synced",
3    "name": "30 days synced",
4    "data": {
5        "account": "12db5af4-fd5f-4d1f-bd98-0360df770aa8",
6        "user": "abdb5af4-fd5f-4d1f-bd10-0360df77012c",
7        "days_synced": 30,
8        "available_from": "2019-06-07T20:12:09Z",
9        "available_to": "2019-06-23T23:57:31Z",
10        "available_count": 324
11    }
12}

  2. Query the payouts endpoint with the following query: /payouts?from_start_date=available_from&account=account_id&to_start_date=available_to where account is the account ID, and available_from and available_to are timestamps from the webhook payload. Use the next URL available in the response to retrieve the paginated resources.

  3. Subscribe to payouts.fully_synced to be notified when the initial account sync of all historical payouts is finished. Whenever the webhook is triggered, you will know that all the historical data is available.

  4. Subscribe to payouts.added to be notified when new payouts are added after the initial sync. Argyle scans all accounts and other changes in data periodically. Use the same API call, but with added_from and added_to timestamps from the webhook payload.

  5. Subscribe to payouts.updated to be notified when existing payouts change. An example of this would be when status of payout changes from scheduled to completed. The webhook payload provides the date range that was updated (updated_from and updated_to) along with an array of payout IDs that were updated (updated_payouts) to make syncing of the data more convenient.

Continuous data access#

To continuously receive users' data, subscribe to the updated or added webhooks for the relevant data endpoint:

  • updated webhooks are triggered when there is new data in an account resource—for example, employments.status changes from active to terminated.
  • added webhooks are triggered when a new resource object is added—for example, a new payouts object is added when a user received a new paystub.

In addition to webhook subscriptions, Argyle recommends performing a periodic data sync. To determine whether some account resources need to be synchronized, compare your stored availability section with the availability section from the Argyle API /accounts/{id} endpoint:

1{
2    "availability": {
3        "activities": {
4            "available_count": 16,
5            "available_from": "2021-07-24T21:45:14Z",
6            "available_to": "2021-09-11T21:32:04Z",
7            "status": "in_progress",
8            "updated_at": "2021-09-13T14:51:10.516590Z"
9        },
10        "documents": {
11            "status": "synced",
12            "updated_at": "2021-09-13T14:49:48.593578Z"
13        },
14        "employments": {
15            "status": "synced",
16            "updated_at": "2021-09-13T14:49:48.593578Z"
17        },
18        "payouts": {
19            "available_count": 9,
20            "available_from": "2021-07-24T23:54:59Z",
21            "available_to": "2021-09-11T23:06:36Z",
22            "status": "in_progress",
23            "updated_at": "2021-09-13T14:51:10.516590Z"
24        },
25        "profiles": {
26            "status": "synced",
27            "updated_at": "2021-09-13T14:49:48.593578Z"
28        },
29        "reputations": {
30            "status": "synced",
31            "updated_at": "2021-09-13T14:49:48.593578Z"
32        },
33        "vehicles": {
34            "status": "synced",
35            "updated_at": "2021-09-13T14:49:48.593578Z"
36        }
37    },
38    "..."
39}

Go through the stored accounts.id in your system and for each:

  1. Fetch the latest account information from /accounts/{id}.
  2. Compare the availability field with the information stored in your database for resources that you are interested in.
  3. If the updated_at field has a newer date, you should fetch the corresponding resource for that particular account and store the results.
Updating Argyle status...
© 2024 Argyle Systems Inc.argyle.com