Upgrade Guide

See what's changed and learn how to upgrade to Link 5 and API v2.


Support for Link 4 has ended and API v1 is no longer receiving updates as of January 1, 2024.

Overview#

Link 5 delivers a more intuitive, straightforward experience, so you can upgrade your onboarding flows, improve your UX, and boost conversions without having to provide any additional customer education.

API v2 enables us to better optimize, add new features, and enhance our data security going forward. Expect faster response times and an all-around superior experience that unlocks the full potential of Link 5.

Visit our Blog Post to learn more about the improvements we've made in Link 5 and API v2.

Upgrading#

If you are using Console to send URL invitations to connect new and existing users, the new Link 5 experience will automatically be applied anytime a new user enters Link from an email or text invitation, or returns to Link through the URL of a previous invite.

If you embed Link, read through the list of changes below and then follow the steps in our Link Upgrade Guide for your respective platform to upgrade from a previous version of Link: Web, iOS, Android, or React Native.

API v2#

In API v1, requests were made to the https://api.argyle.com/v1 base URL.
In API v2, requests are made to the https://api.argyle.com/v2 base URL.

Previous API keys created in Console for API v1 can be used to make requests to API v2 endpoints.

We recommend deleting all previously created v1 webhooks and subscribing to v2 webhooks when using API v2.

Additional resources:

Changes#

Notable changes#

  • User tokens are now required in all Link initializations. All user tokens will now expire in one hour.

  • Link keys have been deprecated and are no longer required in Link 5 initializations.

  • Numeric Item IDs are replacing Link items IDs.

  • The contents of PDF reports can now be retrieved in JSON format.

  • When retrieving an Item, the response includes:

    • A new field_coverage object, which lists which data fields the Item supports and does not support
    • A new direct_deposit_switch object, which lists the Item's deposit switching capabilities

  • Item Filters is a new endpoint in API v2, which allows you to:

    • Filter Item's by what data fields they support
    • Filter for Item's that currently support or do not support new connections
    • Filter for Item's that support specific deposit switch settings

Link 4 — Link 5#

If you are embedding Link, we have simplified and reduced the number of parameters required to initialize Link to two required parameters, four optional parameters, and our optional callback functions:

ParameterTypeDescription
sandboxrequiredDetermines the environment: true for Sandbox, false for Production.
userTokenrequiredUser tokens are now required in all Link initializations.
flowIdoptionalCustomizes the Link connection experience. A previously created customizationId can be used with the flowId parameter, and will still be available in the new Flows section of Console.
ddsConfigoptionalInitializes a deposit switch.
itemsoptionalRestrict Link search to a single Item or list of Items.
accountIdoptionalUsed to directly connect a user to an existing account.
"Callback Name"optionalFunctions triggered by events in Link that can be used to automate taking additional action.

Link's introduction screen

  • Optional and disabled by default
  • All text is now fully customizable using the Flows section of Console
  • A direct link to the document upload flow can be added

Link's search experience

  • Suggested Items are based on your most common account connections
  • Specific Items can be placed at the top of the Popular search list using Flows in Console

Link's login screen

  • Customers can now select how they prefer to log in before entering an Item's specific login screen
  • SSO logins are now more prominent

  • The login screen has been simplified to improve the connection experience

Link's web modal size has changed from 375x667 to 390x720.

"Take photo" is now available during document upload on mobile devices.

Customers are now notified when an expected deposit switch does not occur, which can happen when a selected Item does not support deposit switching or your specific deposit switch settings.

API v1 — API v2#

Users

  • Changed — When creating a user, a user_token is now returned in the response
  • Renamed — data_providers_connected is now items_connected
  • Added — external_id

User Tokens

Invites

  • Endpoint renamed from /user-invite-templates and /user-invites
  • An invite_template_id is no longer required to send an invite

Accounts

  • Changed — The updated_at property of the availability object now shows the timestamp of the most recent change rather than the timestamp of the most recent account scan
  • Renamed — link_item is now item
  • Renamed — pay_distribution is now direct_deposit_switch
  • Removed — data_partner
  • Removed — status
    • Now available only within the connection object
  • Removed — error_code
  • Removed — was_connected
  • Added — scanned_at
    • scanned_at = null indicates the account was never connected (in API v1: was_connected = false)

Items

  • Endpoint renamed from /link-items
  • Changed — Item id has a new format — item_123456789
  • Added — features object
    • Includes the field_coverage object, which lists which data fields the Item supports and does not support
    • Includes the direct_deposit_switch object, which lists the Item's deposit switching capabilities

Item Filters

  • New endpoint in API v2

Identities

  • New endpoint in API v2 that merges the /profiles and /employments API v1 endpoints
  • Renamed — status is now employment_status
  • Renamed — type is now employment_type
  • Renamed — hire_datetime is now hire_date
  • Renamed — termination_datetime is now termination_date
  • Removed — platform_user_id
  • Removed — the hire_dates array of strings
  • Removed — the terminations array of objects

Paystubs

  • Endpoint renamed from /payouts
  • Renamed — payout_date is now paystub_date
  • Renamed — payout_period is now paystub_period
  • Removed — overtime
  • Removed — bonuses
  • Removed — commission
  • Removed — type

Payroll Documents

  • Endpoint renamed from /documents
  • Changed — ocr_data object is now outside of the metadata object

Deposit Destinations

  • Endpoint renamed from /pay-allocations
  • Renamed — bank_account is now ach_deposit_account

Gigs

  • Endpoint renamed from /activities
  • Renamed — num_tasks is now task_count
  • Renamed — start_date is now start_datetime
  • Renamed — end_date is now end_datetime
  • Removed — link_item
  • Removed — data_partner
  • Removed — complete_data_available
  • Removed — route
  • Removed — all_timestamps
  • Removed — income.taxes

Shifts

  • New endpoint in API v2.
  • Contains breaks and other shift data found in /activities in API v1

Vehicles

  • Removed — type_description

Ratings

  • Endpoint renamed from /reputations

Reports

  • Added — accounts array
  • Added — external_id
  • Added — /reports/availability endpoint
  • Added — /reports/{id}.json endpoint (retrieving a VOIE report in JSON replaces the API v1 /income-totals endpoint)

User Uploads

  • New endpoint in API v2.
  • Contains uploaded document data found in /forms in API v1

User Forms

  • Contains only response form data found in /forms in API v1

Target Deposit Destinations

  • Endpoint renamed from /pay-distribution-configs/encrypt
  • Renamed — bank_account is now ach_deposit_account
  • Renamed — entire_allocation is now entire_paycheck
  • Renamed — allocation_id is now deposit_destination
  • Renamed — remove-allocation is now remove-destination when removing a bank account
  • Renamed & Changed — allow_editing is now allow_restoring_destinations and default value is now false
  • Removed — default_allocation_type
  • Changed — Only the accounts.removed webhook is sent when an account is deleted. Account deletion will no longer cause other .removed webhooks to be sent.

Identities Webhooks

  • Changed — identities.added merges the profiles.added and employments.added v1 webhooks
  • Changed — identities.updated merges the profiles.updated and employments.updated v1 webhooks

Paystubs Webhooks

  • Renamed — payouts.added is now paystubs.added
  • Renamed — payouts.updated is now paystubs.updated
  • Renamed — payouts.partially_synced is now paystubs.partially_synced
  • Renamed — payouts.fully_synced is now paystubs.fully_synced

Payroll Documents Webhooks

  • Renamed — documents.added is now payroll_documents.added
  • Renamed — documents.updated is now payroll_documents.updated
  • Renamed — documents.removed is now payroll_documents.removed
  • Renamed — documents.ocr_completed is now payroll_documents.ocr_completed
  • Renamed — documents.ocr_failed is now payroll_documents.ocr_failed

Deposit Destinations Webhooks

  • Renamed — pay_allocations.added is now deposit_destinations.added
  • Renamed — pay_allocations.updated is now deposit_destinations.updated
  • Renamed — pay_allocations.removed is now deposit_destinations.removed

Deposit Switching Webhooks

  • Renamed — accounts.pay_distribution_updated is now direct_deposit_switches.completed
  • Renamed — accounts.pay_distribution_failed is now direct_deposit_switches.failed

Activities Webhooks

  • Renamed — activities.added is now gigs.added
  • Renamed — activities.updated is now gigs.updated
  • Renamed — activities.removed is now gigs.removed
  • Renamed — activities.partially_synced is now gigs.partially_synced
  • Renamed — activities.fully_synced is now gigs.fully_synced

Ratings Webhooks

  • Renamed — reputations.added is now ratings.added
  • Renamed — reputations.updated is now ratings.updated

User Uploads Webhooks

  • Added — user_uploads.added
  • Added - user_uploads.removed
  • Added - user_uploads.ocr_completed
  • Added — user_uploads.ocr_failed
  • Added — user_uploads.ocr_authenticity

User Forms Webhooks

  • Renamed — forms.submitted is now user_forms.submitted
  • Renamed — forms.removed is now user_forms.removed
  • Removed — forms.ocr_completed
  • Removed — forms.ocr_failed
Updating Argyle status...
© 2024 Argyle Systems Inc.argyle.com