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.
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 the webhooks reference for a complete list of examples for webhook subscription calls.
Keeping in sync with new accounts
1. Subscribe to the accounts.updated
webhook event:
POST /v1/webhooks
{
"config": {
"include_resource": true
},
"events": [
"accounts.added"
],
"name": "Added Accounts",
"url": "<https://my.site/webhooks>"
}
2. You start receiving webhook payloads for every newly created account:
{
"event": "accounts.added",
"name": "Added Accounts",
"data": {
"account": "<account-id>",
"user": "<user-id>",
"resource": {
"availability": {
"payouts": {
...
},
...
}
}
}
3. Compare the data.resource.availability
field 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>
.
Making decisions when enough information about payouts is 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.
curl -X POST https://api.argyle.com/v1/webhooks \
-u test_client:test_secret \
-H "Content-Type: application/json" \
-d '{"events": ["payouts.partially_synced"],
"name": "payouts.partially_synced_cr",
“config”: { “days_synced” : 30 },
"url": "https://webhook.site/url"}'
{
"event": "payouts.partially_synced",
"name": "30 days synced",
"data": {
"account": "12db5af4-fd5f-4d1f-bd98-0360df770aa8",
"user": "abdb5af4-fd5f-4d1f-bd10-0360df77012c",
"days_synced": 30,
"available_from": "2019-06-07T20:12:09Z",
"available_to": "2019-06-23T23:57:31Z",
"available_count": 324
}
}
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 for further decisioning.
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 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/<account-id>
endpoint:
{
"availability": {
"activities": {
"available_count": 16,
"available_from": "2021-07-24T21:45:14Z",
"available_to": "2021-09-11T21:32:04Z",
"status": "in_progress",
"updated_at": "2021-09-13T14:51:10.516590Z"
},
"documents": {
"status": "synced",
"updated_at": "2021-09-13T14:49:48.593578Z"
},
"employments": {
"status": "synced",
"updated_at": "2021-09-13T14:49:48.593578Z"
},
"payouts": {
"available_count": 9,
"available_from": "2021-07-24T23:54:59Z",
"available_to": "2021-09-11T23:06:36Z",
"status": "in_progress",
"updated_at": "2021-09-13T14:51:10.516590Z"
},
"profiles": {
"status": "synced",
"updated_at": "2021-09-13T14:49:48.593578Z"
},
"reputations": {
"status": "synced",
"updated_at": "2021-09-13T14:49:48.593578Z"
},
"vehicles": {
"status": "synced",
"updated_at": "2021-09-13T14:49:48.593578Z"
}
},
...
}
Go through the stored accounts.id
in your system and for each:
1. Fetch the latest account information from /accounts/<account-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.