Redirects API v2
Redirect a visitor from a specific URL path to a different target URL.
The target URL may represent a dynamic resource (such as a Page, Product or Category), or a static resource (like a file in the Media Library or an external URL).
Dynamic resources are subject to change. A web page may undergo several revisions to its URL over time. Evance attempts to eliminate multiple/chained redirects by converting the target URL into a resource and ID pair. Even after several revisions to the target's URL, your redirect will still be as efficient as when you added it.
Static resources aren't subject to the same changes. That may not be the case when redirecting to an external URL, but that's out of our control and will need to be managed manually on change.
Scopes
Access to the Redirects API requires that the client have the following scopes granted:
content- Permits write access to add, update or remove redirects.content.readonly- Read only access to search or get redirect data.
The Redirect object
Redirect objects may be entered by matching a
path to a target URL or to a resource and
a resourceId.
country
Optional ISO-3166 alpha-2 country code (e.g. GB).
Applicable to sites with more than one locale. May be used in conjunction with language to
restrict the redirect rule to site locales matching both language and country codes. If supplied, a
languagecode is required. |
createdOn
read-only
The datetime in ISO-8601 format when the Redirect rule was created (e.g. 2026-11-18T13:50:42+00:00). |
id
read-only
The Redirect ID is an unsigned 64-bit integer, which is unique across all Redirects and all Evance Accounts - no other Redirect on our Platform will have the same id.
|
language
Optional ISO-639-1 two letter language code (e.g. en).
Applicable to sites with more than one locale. May be used to restrict the redirect rule to site locales matching language only. Or, may also be used in conjunction with country to
restrict the redirect rule to site locales matching both language and country codes. |
path
required
The URL path to redirect from. When the user visits this path, they will be redirected to the target/
resource.
|
resource
required
The redirect may be associated with a dynamic resource, or a fixed url. The available values for the resource are:
If you do you not know the |
resourceId
An unsigned 64-bit integer representing the ID of a dynamic resource.
or null for static resources.
|
target
Either a path to a file, page, product, category or even an external website (absolute URL) to redirect the user to. Required for static resources. May be set to null for dynamic resources. |
Example: redirect rule with a dynamic resource
A redirect rule for a dynamic resource such as page,
category or product will have a target with
a null value and a resourceId greater than zero, which
identifies the resource object.
{
"id": 3066,
"resource": "page",
"resourceId": 42309,
"path": "/redirect-from",
"target": null,
"language": null,
"country": null,
"createdOn": "2019-11-09T01:02:00+00:00",
}
Example: redirect rule with a static resource
A redirect rule for a static resource
(
url) will have either an absolute URL or path in target and
a resourceId of null.
{
"id": 4842,
"resource": "url",
"resourceId": null,
"path": "/redirect-external",
"target": "https://www.example-store.com",
"language": null,
"country": null,
"createdOn": "2019-11-09T01:02:00+00:00",
}
List/search redirects
GET
/api/v2/redirects.json
Get or search for one or more redirect rules using a range of accepted query parameters:
createdOn:min
Return redirect rules with a createdOn datetime greater than or equal to the
datetime supplied in ISO-8601 format (e.g. 2026-11-18T13:50:42+00:00)
|
createdOn:max
Return redirect rules with a createdOn datetime less than or equal to the datetime
supplied in ISO-8601 format (e.g. 2026-11-18T13:50:42+00:00)
|
createdOn:after
Return redirect rules with a createdOn datetime greater than the datetime supplied
in ISO-8601 format (e.g. 2026-11-18T13:50:42+00:00)
|
createdOn:before
Return redirect rules with a createdOn datetime less than the datetime supplied
in ISO-8601 format (e.g. 2026-11-18T13:50:42+00:00)
|
id:in
Return redirect rules specified within a comma-separated list of Redirect IDs. |
id:min
Return redirect rules with an ID greater than or equal to that specified. |
id:max
Return redirect rules with an ID less than or equal to that specified. |
id:after
Return redirect rules with an ID greater than that specified. |
id:before
Return redirect rules with an ID less than that specified. |
path
Return redirect rules matching the supplied path. |
resource
Return redirect rules matching the supplied resource. Accepted values are:
|
resourceId:in
Return redirect rules matching the resource IDs within a comma-separated list. When querying by resourceId:in ensure to supply resource to
avoid unexpected results.
|
target
Return redirect rules matching a target URL, including redirect rules associated with both dynamic and static resources. |
JSON response
Evance will return a JSON object containing the following properties:
success
A successful search request containing zero or more results will always return a true value.
|
status
An integer matching the HTTP response code. A successful request will have a status of 200.
|
data
An array containing zero or more Redirect data objects. |
pagination
Search results include a pagination object contain information about the current page, total pages, the limit per page and the total number of results available.
|
links
An object containing links to traverse available search results.
|
Example: finding all redirect rules for a page ID
Find all redirect rules associated with a known web page and its ID.
resource=page
&
resourceId:in=42309
Response
{
"success": true,
"status": 200,
"data": [
{
"id": 3066,
"resource": "page",
"resourceId": 42309,
"path": "/redirect-from",
"target": null,
"language": null,
"country": null,
"createdOn": "2019-11-09T01:02:00+00:00",
}
],
"pagination": {
"page": 1,
"limit": 100,
"total": 1,
"totalPages": 1
},
"links": {
"self": "https://examples.evance.me/api/v2/redirects.json",
"previous": null,
"next": null
}
}
Example: finding all redirect rules for a target URL
Let's assume that the page in our previous example has a URL of /my-web-page.
target=/my-web-page
Response
{
"success": true,
"status": 200,
"data": [
{
"id": 3066,
"resource": "page",
"resourceId": 42309,
"path": "/redirect-from",
"target": null,
"language": null,
"country": null,
"createdOn": "2019-11-09T01:02:00+00:00",
}
],
"pagination": {
"page": 1,
"limit": 100,
"total": 1,
"totalPages": 1
},
"links": {
"self": "https://examples.evance.me/api/v2/redirects.json",
"previous": null,
"next": null
}
}
Get a single Redirect
GET
/api/v2/redirects/{id}.json
Retrieve a single Redirect rule using its ID.
URL parameters
id
required
The ID of the Redirect is supplied as a path parameter. |
Response
Returns an object with the following properties:
success
A boolean where a value of true represents a successful request.
|
status
The HTTP status code e.g. 200 for a successful request.
|
data
Contains the Redirect object. |
Example JSON response
{
"success": true,
"status": 200,
"data": {
"id": 3066,
"resource": "page",
"resourceId": 42309,
"path": "/redirect-from",
"target": null,
"language": null,
"country": null,
"createdOn": "2019-11-09T01:02:00+00:00",
}
}
Add a new Redirect
POST
/api/v2/redirects.json
Add a new redirect rule.
Request body
Your request body must contain an object including:
data
required
Containing a Redirect object. |
Example: Adding by resource & ID
You may add a new redirect from a path to a dynamic resource (such
as page, product or category)
using the resource's ID. Let's say we have a web page with an ID of 486435 and we want
to redirect from /redirect-from-path to its current URL.
{
"data": {
"resource": "page",
"resourceId": 486435,
"path": "/redirect-from-path"
}
}
Example: Adding by target URL
Supplying only the path and target allows Evance
to auto-detect the resource type. Allowing you to add redirects for both dynamic and static resources. The target URL
may be:
- The current URL of a dynamic resource (
page,productorcategory) - The path to a file in the Media Library
- The absolute URL to an external website
{
"data": {
"path": "/redirect-external",
"target": "https://www.external-website.com",
}
}
Success response
If the Redirect rule was created successfully you should receive a response with a 201 status
code:
success
A boolean where a value of true means the Redirect was created successfully.
|
status
The HTTP status code e.g. 201 means the Redirect was created successfully. |
data
Contains the Redirect object you created including its new id. |
Error responses
If the Redirect could not be created you will encounter a response with a 422 status code:
success
A boolean where a value of false means the Redirect could not be created.
|
status
A response code of 422 means the Redirect could not be created and you should
check the errors property for further information. |
context
The context property indicates where the error occurred. For a 422 error this
will typically contain a value of data, indicating that there was an error
with the data object supplied. |
errors
Contains an array of error objects, each will have the following properties:
|
Update a Redirect
PUT
/api/v2/redirects/{id}.json
Updating a redirect rule by its ID requires the content OAuth
scope.
URL parameters
id
required
The ID of your Redirect object |
Request body
Your request body must contain an object including:
data
required
Containing updates to your Redirect object. |
Example JSON request
To update a Redirect you must PUT JSON to this resource within a data object. You do
not need to supply all properties and may choose to only supply properties that require modifying.
For example, let's say you want to modify where an existing redirect rule sends the visitor to by changing the redirect
path.
{
"data": {
"path": "/new-redirect-from"
}
}
Success response
If the Redirect was updated successfully you should receive a response with a 200 status
code:
success
A boolean where a value of true means the Redirect was created successfully.
|
status
The HTTP status code e.g. 200 means the Redirect was updated successfully. |
data
Contains the Redirect object you updated. |
Error responses
If the Redirect could not be updated you will encounter a response with either a 400,
404or
422status code:
success
A boolean where a value of false means the Redirect could not be updated.
|
status
|
context
|
errors
Contains an array of error objects, each will have the following properties:
|
Delete a Redirect
DELETE
/api/v2/redirects/{id}.json
Delete a redirect rule by its ID.
URL parameters
id
required
The ID of your Redirect object |
Request body
Does not require a payload
Success response
If the Redirect rule was deleted successfully you should receive a response with a 204 status
code and no body.
Error responses
If the Redirect could not be deleted you may encounter a response with a 400, or 404 status
code:
success
A boolean where a value of false means the Redirect could not be deleted.
|
status
|