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#
-
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}
-
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}
-
Compare the fields within the
availability
object with the data stored in your system. -
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:
-
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}
-
Query the payouts endpoint with the following query:
/payouts?from_start_date=available_from&account=account_id&to_start_date=available_to
whereaccount
is the account ID, andavailable_from
andavailable_to
are timestamps from the webhook payload. Use the next URL available in the response to retrieve the paginated resources. -
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. -
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 withadded_from
andadded_to
timestamps from the webhook payload. -
Subscribe to
payouts.updated
to be notified when existing payouts change. An example of this would be when status of payout changes fromscheduled
tocompleted
. The webhook payload provides the date range that was updated (updated_from
andupdated_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 fromactive
toterminated
.added
webhooks are triggered when a new resource object is added—for example, a newpayouts
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:
- Fetch the latest account information from
/accounts/{id}
. - Compare the
availability
field with the information stored in your database for resources that you are interested in. - If the
updated_at
field has a newer date, you should fetch the corresponding resource for that particular account and store the results.