Create a new location

post

https://api.convert.com/api/v2/accounts/{account_id}/projects/{project_id}/locations/add

Defines a new location within a project. Requires a name and a set of rules (e.g., URL contains 'product/', JS condition window.userType === 'premium'). Also requires specifying the trigger type (e.g., 'upon_run' to activate when rules match on page load, or 'manual' to activate via JavaScript call). The Knowledge Base article "Creating Effective Experiences: A Guide to Location Setup" describes different trigger options.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Path Params

account_id

integer

required

ID of the account that owns the retrieved/saved data

project_id

integer

required

ID of the project into which the location is to be stored

Body Params

description

string

length ≤ 500

An optional, more detailed explanation of this location's purpose or the pages/conditions it targets.

status

string

enum

Defaults to active

The current status of a location:

active: The location is active and can be used for targeting experiences.
archived: The location is archived and no longer available for new experiences, but its definition is preserved. Archived locations can often be cloned. Knowledge Base: "Benefits of Archiving Unused Goals, Locations, and Audiences."

Allowed:

name

string

required

length ≤ 100

A user-defined, friendly name for the location (e.g., "All Product Pages", "Homepage Only", "Checkout Funnel"). This name appears in the Convert UI when selecting locations for experiences.

selected_default

boolean

If true, this location will be automatically pre-selected when creating new experiences within the project. Useful for commonly targeted site areas.

rules

object | null

required

Defines the logical structure for combining multiple rule conditions for a Location. It uses a nested OR -> AND -> OR_WHEN structure, similar to Audience rules, but LocationRuleElement types are restricted to page content/URL attributes.

trigger

Defines how and when an experience associated with this location should be activated for a visitor who matches the location's rules. The type determines the activation mechanism. Knowledge Base: "Locations" - "Dynamic Website Triggers".

Responses

201Detailed information for a single location, including its name, status, the rules (URL patterns, JS conditions) that define it, and the trigger type (e.g., 'upon_run', 'manual').

defaultIndicates an error occurred while processing the request. The code provides an HTTP status code, message offers a human-readable explanation or an array of validation errors, and fields (if present) specifies which input fields were problematic.