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.
  • The path may not include query strings.
  • If supplied as an absolute URL, only it's path will be saved.
  • Locale prefixes (e.g. /en-us) will be removed from the path and stored in the language and country properties.
  • Paths may not reference /admin or /api URLs, and may be ignored when referencing other reserved routes.
resource required
The redirect may be associated with a dynamic resource, or a fixed url. The available values for the resource are:
  • page
    A dynamic resource. Supply the page's id in the resourceId property.
  • category
    A dynamic resource. Supply the category's id in the resourceId property.
  • product
    A dynamic resource. Supply the product's id in the resourceId property.
  • url
    A static resource. Supply the URL to a file or external website address in the target property.

If you do you not know the resource and its resourceId, you can opt to supply the target URL only and Evance will automatically check for the correct settings.

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:
  • page
  • category
  • product
  • url
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.
  • limit - the number of results to return per page
  • page - the current page number
  • total - the total number of available results
  • totalPages - the total number of available pages of results
links
An object containing links to traverse available search results.
  • self - the URL for the current search.
  • previous - a URL for the previous results page, or nullif there isn't one.
  • next - a URL for the next results page, or null if there isn't one


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, product or category)
  • 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:

  • name - The property name that encountered an error.
  • message - A human readable error message.
  • ref - An error reference string (e.g. error.not-unique if the alias supplied is already in use).

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
  • 400 may indicate that the ID was not provided.
  • 404 means Redirect could not be found by the ID provided.
  • 422 means the Redirect could not be updated due to errors in the data data.
context
  • parameters means the error is with the required id URL parameter.
  • data indicates an error within the Redirect data.
errors

Contains an array of error objects, each will have the following properties:

  • name - The property name that encountered an error.
  • message - A human readable error message.
  • ref - An error reference string (e.g. error.not-unique if the alias supplied is already in use).

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
  • 400 may indicate that the ID was not provided, or the Redirect could not be deleted for an unknown reason.
  • 404 indicates that the ID was provided, but the Redirect could not be found.