Set up redirect URLs
Complete your customer's Hosted Link journey with a redirect location
Once your customers have successfully completed authorization of the connection to their data via Link, you can redirect them to another website.
There are a few ways you can redirect your customers:
- Redirect to a static URL
- Redirect with custom query parameters
- Redirect with reserved query parameters
Your redirects will only apply to Hosted Link. For Embedded Link, build out the required redirect configuration within your application.
Not sure how to handle the params in your website? See an example here.
Setting redirect settings
You can find the redirect settings page in the Portal:
- In the navigation bar click Settings
- In the side nav, click Auth flow > Redirects
Redirect to a static URL
A static URL is a single, unchanging web address that every customer would be directed to.
Enter the website address that you want to redirect your customers to in the Redirect URL > URL field.
You can ignore the other settings on the page.
Redirect with reserved query parameters
You can conditionally redirect users based on what happened when authorizing.
Codat supports a number of reserved query parameters for redirects. If you add reserved parameters to the Redirect URL you send to your customer, Codat will replace the parameters with the relevant information.
To set up a redirect with reserved query parameters:
In the Redirect URL > URL field, 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}
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
| 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 company 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. gbol, mqjo, zsth, ugxp | 4 character key of the platform as used to reference integrations. |
| platformName | e.g. Xero, Sandbox, Square | 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: 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 Link 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 | Codat standardises error messages for the status codes. Error messages returned in the redirect will always be mapped with the status codes listed above. 403 = "User cancelled." 500 = "Unknown error occurred." 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. |
| data.company.companyName | String | The name of the connected party within the underlying platform. This maps to the company name property in the company info dataset. |
At present, the data.company.companyName is only supported for the following integrations:
- Accounting: Dynamics 365 Business Central, NetSuite, QuickBooks Online, Sage Intacct, and Xero.
The names of query parameters are case sensitive, e.g. companyId is not the same as companyid.
Example: Use redirect params to see errors in the link flow
Redirect URL:
https://www.mybank.io/{integrationType}?flow=Codat&statuscode={statusCode}&errormessage={errorMessage}
- For a user who authenticates the connection and can be redirected to the next stage in the flow, the redirect would be:
https://www.mybank.io/accounting?flow=Codat&statuscode=200&errormessage= - 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 below would be where they can upload the relevant documents manually.
https://www.mybank.io/accounting?flow=Codat&statuscode=403&errormessage=User%20cancelled - For a user who encounters an unexpected error during the linking process, the redirect below would be where they can contact your support team for assistance.
https://www.mybank.io/accounting?flow=Codat&statuscode=500&errormessage= Unknown%20error%20occured
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:
- 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://mybank.io/{customParam}/show. - Before you send out a Link URL to a customer, modify the URL 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 (&). - If you use the redirect parameter and Link URL values shown above, your customer is redirected to
https://redirect.site/123456/show.
Ensure any and all special characters used in the link URL are correctly encoded; otherwise custom parameters may not pull through correctly.
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.
Example: Redirect behavior when custom parameters are missing
For example, if you set your Redirect URL to the URL below...
https://www.mybank.io/{journeyType}/success?ClientType={clientType}
...the link URLs would give the following outcomes:
| Link URL | Computed redirect |
|---|---|
...f67e946f84c9/link?journeyType=demo&clientType=test | https://www.mybank.io/demo/success?ClientType=test |
...f67e946f84c9/link?clientType=test | https://www.mybank.io//success?ClientType=test |
...f67e946f84c9/link?journeyType=demo | https://www.mybank.io/demo/success?ClientType= |
...f67e946f84c9/link | https://www.mybank.io//success?ClientType= |
Dynamic hosts
It's also possible to send users to completely different websites and subdomains.
| Redirect URL setting | Link URL | Resolves to... |
|---|---|---|
https://{environment}.mybank.io/success | ...f67e946f84c9/link?environment=uat | https://uat.mybank.io/success |
https://mybank{customerType}.io/success | ...f67e946f84c9/link?customerType=business | https://mybank{business}.io/success |
https://{website}/success | ...f67e946f84c9/link?website=mybank.io | https://mybank.io/success |
https://mybank.{region}/success | ...f67e946f84c9/link?region=com | https://mybank.com/success |
https://{business}.io/success | ...f67e946f84c9/link?business=mybank | https://mybank.io/success |
To use this dynamic host behaviour, you'll need to list each allowed host in Allowed redirect URLs.
For the above example, https://{environment}.mybank.io/success, you'd have to explicitly list all valid environments:
https://local.mybank.io/successhttps://uat.mybank.io/successhttps://prod.mybank.io/success
Note: The URLs must be valid URLs, which means they must have https:// or http:// added before them.
Do not use reserved parameters in your redirect hosts.
Allowed redirect hosts
Dynamic hosts will need to be defined here. A different domain suffix would count as a different host - e.g. mybank.io and mybank.com should be listed separately.
If you're not using the dynamic host feature, you don't need to use this setting.