Allow your users to access Link

Choose how you want to share Link with your customers

How do you want your customers to connect their financial software?

  1. If you would like to have more control over Link and embed it directly into your app, read Embed Link in your app.
  2. If you prefer an approach that involves no development resources, read Share Link URLs via Portal.

Embed Link in your app

  1. In order to establish a connection to the SMB's financial platform(s), you first need to create a Codat company for them. We recommend you create a company at the same time as your SMB user signs up within your app. That allows you to track their connection status from day one. To create a company, follow the steps in Create a Codat company. Pro tip: you can use our Swagger to try this endpoint out.

🚧

Use your merchant ID for the company name

We recommend that you populate the name value with the ID that you use for the merchant in your internal system so that it’s easier to identify the Codat company that corresponds to your record of the merchant.

  1. From the response to step 1, retain the company ID (hereafter referred to as companyId) (see an example below). It is crucial that you retain this value as you will need it for directing your customers to Link and managing their connections.
  2. In the response to step 1, find the redirect value. Use it in your app to direct the customer to Link, for example, via a 'Connect my accounts' button. Once your customer finishes the Link flow, they will be redirected back to the URL you have set in the Link settings, for example, the next step in your app's flow. To find out more about configuring redirect URLs, read Set up redirect URLs.

Example response to a request to create a new company:

{
  //CompanyId - retain this value
  "id": "1126743b-113d-4d72-b14f-36d6742df487",
   //End of CompanyId
  "name": "Superapp",
  "platform": "",
  //Redirect - use this value to direct your customer to Link
  "redirect": "https://link.codat.io/company/1126743b-113d-4d72-b14f-36d6742df487",
  //End of redirect
  "dataConnections": [],
  "created": "2022-05-16T14:55:21.6076495Z"
}
  1. (Optional) Set up an alert to monitor the connection status of the newly created company. We recommend that you set up an alert for when a user authorizes a data connection so that you can action it within your app.
  2. (Optional) Present your customer with a confirmation screen that shows the integrations they have set up. You can:
(GET) /companies/{companyId}/connections

❗️

Use the redirect Link URL for existing customers

If your customer has connected before and you create a new company then this will likely lead to a new connection(s) being created which you will be billed for based on your contract. To avoid this, direct the existing customers to the redirect Link URL that you can retrieve from the company's metadata available at GET /companies

Allow your customers to view or manage connections

Existing users with active connections

Direct the user to the redirect URL that can be retrieved from a company's metadata. This allows them to modify their connections via the Link UI.

GET /companies/{companyId}

Existing users with pending connections (not authorized)

When a user creates a data connection, but fails to authorize access to their financial platform, a pending data connection is created in the respective Codat company. A pending data connection is a connection that has a pendingAuth status. To learn more about different data connection status, explore Data connections.

In this scenario, you may want to allow your user to authorize this connection by sending them directly to the third-party authentication screen. Use the linkUrl value from the dataConnections array in the company's metadata. This will prompt the user to authorize the connection to their financial platform.

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "string",
  "platform": "string",
  "redirect": "string",
  "lastSync": "2022-05-16T15:17:40.597Z",
  "dataConnections": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "integrationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "sourceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "platformName": "string",
      //Link URL - use it to allow your user to re-authorize in their financial platform
      "linkUrl": "string",
      //End of Link URL
      "status": "string",
      "lastSync": "2022-05-16T15:17:40.597Z",
      "created": "2022-05-16T15:17:40.597Z",
      "sourceType": "string",
      "dataConnectionErrors": [
        {
          "statusCode": "string",
          "statusText": "string",
          "errorMessage": "string",
          "erroredOnUtc": "2022-05-16T15:17:40.597Z"
        }
      ]
    }
  ],
  "created": "2022-05-16T15:17:40.598Z",
  "createdByUserName": "string"
}

Share Link URLs via Portal

Use the Link URL

Use Link URL if your customer connection is meant to be persistent and your customer may need to view or update their connection in the future.

If this is a new user:

  1. Create a company for your customer. You can do this by following the instructions in Adding a new company.
  2. Navigate to the Companies page in Portal.
  3. Find the company that you created for the customer and click Request data next to the company name.
  4. Copy the Link URL from the box that appears and share it with the customer. This will allow the customer to create and authorize a data connection.

If a user already has a connection that hasn't been authorized and is not in an active state, the name of the connected integration will appear next to the company name. In that case, instead of using the Link URL, click the integration name and copy the URL from the Connections section. Share this link with the user to allow them to authorize the connection and activate the connection.

LInk URL to manage an existing connection (bottom text field).LInk URL to manage an existing connection (bottom text field).

LInk URL to manage an existing connection (bottom text field).

Use the Invite company URL

If you want to onboard large numbers of new companies without needing to specify company names or references AND your company and your customer do not need to manage, view, or update connections in the future, use the invite company URL:

  1. Sign in to the Codat portal and navigate to the Companies page.
  2. Click on the Invite company button and copy the URL that displays to share it with your customer. Before sharing, ensure that the page title and body text are correctly configured as per Customize your Link.

❗️

Use the Link URL for existing customers

Using the invite company URL will not allow your customer to view, update or add new connections against the existing Codat company which represents your customer. Instead, regardless of whether your customer has an existing connection(s), they will be asked to identify themselves again, in turn creating a new Codat company and connection(s) which you may be billed for based on your contract.


Did this page help you?