Redirect URLs

Once your customers have successfully completed authorization of the connection to their data on the Codat Link site, you can redirect them to the locations of your choice.

The following options of redirect configuration are available in the Codat Portal:

  • redirect to a static website
  • redirect with custom query parameters
  • redirect with reserved query parameters

Redirect to a static website

A static website is a single web address you set for every customer to be directed to.

To set up a redirect to a static website:

  1. Open the Codat Portal and log in.
  2. In the left pane, select Link Settings.
  3. On the Link Settings page, find the Redirect URL box and enter the website address that you want to redirect your customers to.
  4. Scroll up the page and select Save Changes.

Redirect with custom query parameters

Codat supports custom query parameters for redirects. You can define your own values for each custom parameter so that you can direct different customers to, for example, different versions of a landing page. To do this, you need to add custom query parameters to the Redirect Parameter.

To set up a redirect with custom query parameters:

  1. Follow steps 1 to 3 in the Redirect to a static website section above.
  2. In the Redirect URL box, enter a base URL along with the parameters you want to use to build the custom redirect. To add a parameter, wrap it in curly braces. For example: https://redirect.site/{customparam}/show.
  3. Scroll up the page and select Save Changes.
  4. Before you send out a Link URL to a customer, modify the string in the URL box by adding a question mark and the parameter name and value to the end of it.
    For example: https://link.codat.io/.../link?customparam=123456.
    If you want to add more than one parameter, separate them with an ampersand (&).
  5. If you use the redirect parameter and Link URL values shown above, your customer is redirected to https://redirect.site/123456/show.

Unspecified custom parameters

It's not possible to specify default parameters. If you don't add a parameter to the Link URL when the redirect is built, it's replaced with an empty string.

For example, if you set your Redirect URL to: https://www.codat.io/{journeyType}/success?ClientType={clientType}, then the link URLs would give the following outcomes:

  • ...f67e946f84c9/link?journeyType=demo&clientType=test would ultimately send you to https://www.codat.io/demo/success?ClientType=test.
  • ...f67e946f84c9/link?clientType=test would ultimately send you to https://www.codat.io//success?ClientType=test.
  • ...f67e946f84c9/link?journeyType=demo would ultimately send you to https://www.codat.io/demo/success?ClientType=.
  • ...f67e946f84c9/link would ultimately send you to https://www.codat.io//success?ClientType=.

🚧

Special character encoding

Please ensure any and all special characters used in the link URL are correctly encoded; otherwise custom parameters may not pull through correctly.

Redirect with reserved query parameters

Codat supports a number of reserved query parameters for redirects. Codat will replace the reserved parameters in your redirects with pre-defined, non-customizable values. This way you can, for instance, redirect your customers through your own flows after they have left the Codat Link site. To do this, you need to add reserved parameters to the Redirect Parameter and the Link URL that you send to your customer.

👍

Before you start:

  • Follow steps 1 to 3 in the Redirect to a static website section above.

To set up a redirect with reserved query parameters:

  1. In the Redirect URL box, enter a base URL along with the reserved parameters you want to use to build the redirect. To add a parameter, wrap it in curly braces. For example: https://redirect.site/{sourceType}/?flow=Codat&statuscode={statusCode}&errormessage={errorMessage}
  2. Scroll up the page and select Save Changes.
  3. If you use the redirect parameter values shown above, your customer is redirected to: https://redirect.site/accounting/?flow=Codat&statuscode=403&errormessage=User%20cancelled.

📘

Availability of reserved query parameters

Please note that the names of the parameters listed in the table below are currently available for the following platforms:
accounting: FreeAgent, Freshbooks, Microsoft Dynamics 365 Business Central, MYOB AccountRight, Pandle, Quickbooks Online, Sage Business Cloud, Wave
banking: Plaid

Codat’s reserved parameters

Substitution values

Additional information

clientId

GUID (Globally Unique Identifier)

Identifier of the client that completes the authorization flow.

Note: As a Codat client you may have multiple Codat instances. Each of those instances will have a separate clientId.

connectionId

GUID

Identifier of the data connection that the authorization flow was completed for.

companyId

GUID

Identifier of the companycompany - An entity (typically an SME) whose data is being connected to via the Codat API. that completes the authorization flow.

integrationId

GUID

Identifier of the integration the company authorized.

sourceId

GUID

Identifier of the data source for the authorized integration.

platform

e.g. xero, sandbox, square, izettlego

Key of the platform as used to reference integrations.

platformName

e.g. Xero, SandBox, Square, iZettle Go

Name of the platform as displayed in the Codat Portal.

sourceType

Accounting, Banking, BankFeed, Commerce, Expense, Other

Name of the source used to retrieve data from.

statusCode

200, 201, 403, 500, 501

Codat standardises the status codes returned by the integrations to the following:

200 = Successful — user’s request has been fulfilled.

201 = No content — successful, but no information about data connection will be available.

Possible scenario: A user visits the Codat Link site with a connection to their accounting source already established, so they do not take any action before exiting the flow.

403 = Not available

Possible scenario: A user chooses to quit the link flow before the linking process is completed.

501 = Platform not supported.

Possible scenario: A user chooses an integration that is not supported by the client. At this point, the client offers them an alternative option outside of the Codat flows.

500 = Internal Server Error

Codat standardises any errors which do not fit into one of the above categories to a 500 code - Internal Server Error.

errorMessage

"User cancelled"
"Unknown error occurred"
"Not supported"

Codat standardises error messages for the status codes. This means that an error message returned in the redirect will always be mapped with the status codes listed in the statusCode line above.

StatusCode 403 = “User cancelled.”

StatusCode 500 = "Unknown error occurred."

StatusCode 501 = "Not supported."

Note: If you want to use the original error message from the integration, use statusText.

statusText

String

String as it's passed back from the integration.

Note: The names of query parameters are case sensitive, e.g. companyId is not the same as companyid.

Configuration examples

Have a look at some examples of how your redirects can be configured with reserved query parameters in several typical scenarios.

Initial configuration: https://www.rocketbank.io/{integrationType}?flow=Codat&statuscode={statusCode}&errormessage={errorMessage}

  1. For a user who authenticates the connection and can be redirected to the next stage in the flow, the redirect would be: https://www.rocketbank.io/accounting?flow=Codat&statuscode=200&errormessage=

  2. For a user who quits the linking process without providing access to their financial data either because a) their platform is not supported or b) they do not wish to provide access to their data, the redirect would behttps://www.rocketbank.io/accounting?flow=Codat&statuscode=403&errormessage=User%20cancelled, where they can upload the relevant documents manually.

  3. For a user who encounters an unexpected error during the linking process, the redirect would be: https://www.rocketbank.io/accounting?flow=Codat&statuscode=500&errormessage= Unknown%20error%20occured, where they can contact your support team for assistance.


Did this page help you?