> ## Documentation Index
> Fetch the complete documentation index at: https://docs.argyle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Upgrade Guide

> Upgrading to Link 5 and API v2.

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

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

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

<Note>
  *Visit our* [Blog Post](https://argyle.com/blog/announcing-argyle-2/) *to learn more about the improvements we've made in Link 5 and API v2.*
</Note>

## Upgrading

<div className="argyle-divider" />

### Link 5

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](/upgrade-guide#changes) below and then follow the steps in our [Link Upgrade Guide](/link/upgrade) for your respective platform to upgrade from a previous version of Link: [Web](/link/upgrade#web), [iOS](/link/upgrade#ios), [Android](/link/upgrade#android), or [React Native](/link/upgrade#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.

<Note>
  We recommend deleting all previously created v1 webhooks and [subscribing to v2 webhooks](/api-guide/webhooks) when using API v2.
</Note>

Additional resources:

* [API v2 Reference](/api-reference/users)
* [API v2 Postman](/api-guide/postman)
* [Argyle API Introduction Guide](/api-guide/overview)
* [Changes: API v1 — API v2](/upgrade-guide#api-v1--api-v2)
* [Migrating Link item IDs to Item IDs](/api-reference/items#migrate)

## Changes

<div className="argyle-divider" />

### Notable changes

* [User tokens](/link/user-tokens) are now required in all [Link initializations](/link/initialization). 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](/api-reference/items#object) are replacing Link items IDs.

* The contents of PDF reports can now be [retrieved in JSON format](/api-reference/reports#retrieve-json).

* When [retrieving an Item](/api-reference/items#retrieve), the response includes:

* A new [`field_coverage`](/api-reference/items#object-features-field_coverage) object, which lists which data fields the Item supports and does not support

* A new [`direct_deposit_switch`](/api-reference/items#object-features-direct_deposit_switch) object, which lists the Item's deposit switching capabilities

* [Item Filters](/api-reference/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](/link/initialization/overview#required-initialization-parameters) required to initialize Link to two required parameters, four optional parameters, and our optional callback functions:

| Parameter       | Type     | Description                                                                                                                                                                                                                                                                                       |
| --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| sandbox         | required | Determines the environment: `true` for [Sandbox](/overview/sandbox-testing), `false` for Production.                                                                                                                                                                                              |
| userToken       | required | [User tokens](/link/user-tokens) are now required in all Link initializations.                                                                                                                                                                                                                    |
| flowId          | optional | [Customizes](/console/flows/embedded-experiences) the Link connection experience. A previously created `customizationId` can be used with the `flowId` parameter, and will still be available in the new <a href="https://console.argyle.com/flows" target="_blank">Flows</a> section of Console. |
| ddsConfig       | optional | Initializes a [deposit switch](/workflows/deposit-switching).                                                                                                                                                                                                                                     |
| items           | optional | [Restrict Link search](/workflows/account-connections#list) to a single [Item](/overview/data-structure/items) or list of Items.                                                                                                                                                                  |
| accountId       | optional | Used to [directly connect](/workflows/account-connections#direct-login) a user to an existing account.                                                                                                                                                                                            |
| "Callback Name" | optional | [Functions](/link/reference/callbacks) triggered by events in Link that can be used to automate taking additional action.                                                                                                                                                                         |

<Tabs>
  <Tab title="Redesigns:">
    Link's introduction screen

    * Optional and disabled by default
    * All text is now fully customizable using the <a href="https://console.argyle.com/flows" target="_blank">Flows</a> section of Console
    * A direct link to the [document upload](/workflows/document-processing) flow can be added

          <img src="https://mintcdn.com/argyle/lpddaw6ggr_B1oHD/images/argyle-guides/upgrade-guide/intro-screen.png?fit=max&auto=format&n=lpddaw6ggr_B1oHD&q=85&s=95d4f18ac7bf893385be94c36c117ed2" alt="Link's introduction screen in Link 5 is fully customizable, and can link directly to the document upload flow." width="3200" height="2000" data-path="images/argyle-guides/upgrade-guide/intro-screen.png" />

    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 <a href="https://console.argyle.com/flows" target="_blank">Flows</a> in Console

          <img src="https://mintcdn.com/argyle/lpddaw6ggr_B1oHD/images/argyle-guides/upgrade-guide/search-screen.png?fit=max&auto=format&n=lpddaw6ggr_B1oHD&q=85&s=fb0469332454c679fc96512f9f640164" alt="Link 5's search screen can be used without the need for an intro screen, and shows more popular employers and payroll providers at a glance." width="3200" height="2000" data-path="images/argyle-guides/upgrade-guide/search-screen.png" />

    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

          <img src="https://mintcdn.com/argyle/lpddaw6ggr_B1oHD/images/argyle-guides/upgrade-guide/login-methods.png?fit=max&auto=format&n=lpddaw6ggr_B1oHD&q=85&s=df830ea4f1a6f6156c6adf46357bf2ce" alt="Different login methods such as SSO are selectable and more prominent in Link 5." width="3200" height="3274" data-path="images/argyle-guides/upgrade-guide/login-methods.png" />

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

          <img src="https://mintcdn.com/argyle/lpddaw6ggr_B1oHD/images/argyle-guides/upgrade-guide/login-screen.png?fit=max&auto=format&n=lpddaw6ggr_B1oHD&q=85&s=4ee43d4c3036cea0fe0e3043fefc3f0f" alt="Different login methods such as SSO are selectable and more prominent in Link 5." width="3200" height="3274" data-path="images/argyle-guides/upgrade-guide/login-screen.png" />

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

    <img src="https://mintcdn.com/argyle/lpddaw6ggr_B1oHD/images/argyle-guides/upgrade-guide/web-link-modal.png?fit=max&auto=format&n=lpddaw6ggr_B1oHD&q=85&s=6a26122e9196b7186fc69df36f6b62f8" alt="Link's web modal size has increased." width="3200" height="2000" data-path="images/argyle-guides/upgrade-guide/web-link-modal.png" />
  </Tab>
</Tabs>

<Tabs>
  <Tab title="Additional features:">
    "Take photo" is now available during document upload on mobile devices.

    <img src="https://mintcdn.com/argyle/lpddaw6ggr_B1oHD/images/argyle-guides/upgrade-guide/photo-doc.png?fit=max&auto=format&n=lpddaw6ggr_B1oHD&q=85&s=c3d567166e0b0d72321cb9f67ceeaaf3" alt="Take photo is now an option in Link 5 when uploading payroll documents including W-2s, 1099s, and paystubs." width="3200" height="2000" data-path="images/argyle-guides/upgrade-guide/photo-doc.png" />

    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.

    <img src="https://mintcdn.com/argyle/lpddaw6ggr_B1oHD/images/argyle-guides/upgrade-guide/dds-error.png?fit=max&auto=format&n=lpddaw6ggr_B1oHD&q=85&s=5afce91b9a1e7e4d51760f3a5c75620f" alt="In Link 5, users are notified when a deposit switch does not occur so they know to reach out for help or more information." width="3200" height="2000" data-path="images/argyle-guides/upgrade-guide/dds-error.png" />
  </Tab>
</Tabs>

### API v1 — API v2

<Tabs>
  <Tab title="Endpoints:">
    #### Users

    * Changed — When [creating a user](/api-reference/users#create), a `user_token` is now returned in the response
    * Renamed — `data_providers_connected` is now `items_connected`
    * Added — `external_id`

    #### User Tokens

    * Changed — When [creating a user token](/api-reference/user-tokens#create), a `user_token` is now returned in the response

    #### Invites

    * Endpoint renamed from `/user-invite-templates` and `/user-invites`
    * An `invite_template_id` is no longer required to [send an invite](/api-reference/invites#send-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/{id}.json` [endpoint](/api-reference/reports#retrieve-json) (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`
  </Tab>
</Tabs>

<Tabs>
  <Tab title="Webhooks:">
    * 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`
  </Tab>
</Tabs>