Convert API for Experiences Serving (1.1.0)

Download OpenAPI specification:Download

Serve and track experiences to your users using Convert APIs and tools

SDK Key Authentication

In order to authenticate requests to the Convert Tracking/Config API, you need to provide the SDK key secret inside the Authorization header.

Note:

For the Projects that have settings.disable_default_config=true , access will work only through the use of SDK Key Authentication method with the associated endpoints.
For the Projects that have settings.disable_default_config=false , access will work through the use of SDK Key Authentication method with the associated endpoints or without authentication, through the default endpoints.
An SDK key could have a secret associated or not. If it has a secret, it should be provided in the Authorization header. If it doesn't have a secret, the Authorization header should be empty and the request would be authorized if the provided SDK key is found.

Debug Token

In order to return also the draft and paused experiences into the Convert Tracking/Config API, you need to provide the Debug Token inside the convert-debug-token header in the form of convert-debug-token: <debug_token>. The token is a short lived one with a default expiration of 24 hours and can be obtained/renewed by calling Generate Debug Token REST api endpoint.

Project Config

Api endpoint which returns all the configuration of one project inside an account. This can be consumed inside various fullstack sdks

Default Get Project Config

This is the default endpoint that does not need SDK Keys to returns the project's config to be consumed in various sdks

path Parameters

account_id required	integer ID of the account that owns the retrieved/saved data
project_id required	integer ID of the project to be retrieved

query Parameters

environment

string

Filter experiences based on environment.

Responses

Response samples

200
default

Content type

application/json

{"account_id": "string",
"project": {"id": "string",
"name": "string",
"type": "fullstack",
"utc_offset": 0,
"custom_domain": {"domain": "string"
},
"domains": [{"tld": "string",
"hosts": null
}
],
"global_javascript": "string",
"settings": {"allow_crossdomain_tracking": true,
"data_anonymization": true,
"do_not_track": "OFF",
"global_privacy_control": "OFF",
"include_jquery": true,
"include_jquery_v1": false,
"disable_spa_functionality": false,
"do_not_track_referral": false,
"integrations": {"google_analytics": {"enabled": true,
"auto_revenue_tracking": true,
"type": "ga3",
"property_UA": "string"
},
"kissmetrics": {"enabled": true
}
},
"min_order_value": 0,
"max_order_value": 0,
"outliers": {"order_value": {"detection_type": "none"
},
"products_ordered_count": {"detection_type": "none"
}
},
"version": "string"
},
"environments": {"production": {"label": "Production",
"is_default": true
}
}
},
"goals": [{"id": "string",
"name": "string",
"key": "string",
"type": "dom_interaction",
"rules": {"OR": [{"AND": [{"OR_WHEN": [{"rule_type": null,
"value": null,
"matching": null
}
]
}
]
}
]
},
"settings": {"tracked_items": [{"selector": "string",
"event": "string"
}
]
}
}
],
"locations": [{"id": "string",
"key": "string",
"name": "string",
"trigger": {"type": "dom_element",
"selector": "string",
"events": ["click"
]
},
"rules": {"OR": [{"AND": [{"OR_WHEN": [{"rule_type": null,
"value": null,
"matching": null
}
]
}
]
}
]
}
}
],
"audiences": [{"id": "string",
"key": "string",
"name": "string",
"type": "permanent",
"rules": {"OR": [{"AND": [{"OR_WHEN": [{"rule_type": null,
"value": null,
"matching": null
}
]
}
]
}
]
}
}
],
"segments": [{"id": "string",
"key": "string",
"name": "string",
"rules": {"OR": [{"AND": [{"OR_WHEN": [{"rule_type": null,
"value": null,
"matching": null
}
]
}
]
}
]
}
}
],
"experiences": [{"id": "string",
"name": "string",
"key": "string",
"locations": ["string"
],
"site_area": {"OR": [{"AND": [{"OR_WHEN": [{"rule_type": null,
"value": null,
"matching": null
}
]
}
]
}
]
},
"audiences": ["string"
],
"goals": ["string"
],
"status": "draft",
"global_js": "string",
"global_css": "string",
"type": "a/b",
"version": 0,
"variations": [{"id": "string",
"name": "string",
"key": "string",
"traffic_allocation": 10000,
"status": "stopped",
"changes": [{"id": 0,
"type": "defaultCode",
"data": {"css": "string",
"js": "string",
"custom_js": "string"
}
}
]
}
],
"integrations": [{"provider": "baidu",
"enabled": true,
"custom_dimension": "string"
}
],
"environments": ["string"
],
"environment": "string",
"settings": {"min_order_value": 0,
"max_order_value": 0,
"outliers": {"order_value": {"detection_type": "none"
},
"products_ordered_count": {"detection_type": "none"
}
},
"matching_options": {"audiences": "any",
"locations": "any"
}
}
}
],
"archived_experiences": ["string"
],
"features": [{"id": "string",
"name": "string",
"key": "string",
"variables": [{"key": "string",
"type": "boolean"
}
]
}
],
"is_debug": false
}

Sdk-Key Get Project Config

This endpoint returns the project's config to be consumed in various sdks using the SDK Key

Authorizations:

sdkKeyAuthdebuggingTokenAuth

path Parameters

sdk_key

required

string

The SDK key used to retrieve the project's config

query Parameters

environment

string

Filter experiences based on environment.

Responses

Response samples

200
default

Content type

application/json

{"account_id": "string",
"project": {"id": "string",
"name": "string",
"type": "fullstack",
"utc_offset": 0,
"custom_domain": {"domain": "string"
},
"domains": [{"tld": "string",
"hosts": null
}
],
"global_javascript": "string",
"settings": {"allow_crossdomain_tracking": true,
"data_anonymization": true,
"do_not_track": "OFF",
"global_privacy_control": "OFF",
"include_jquery": true,
"include_jquery_v1": false,
"disable_spa_functionality": false,
"do_not_track_referral": false,
"integrations": {"google_analytics": {"enabled": true,
"auto_revenue_tracking": true,
"type": "ga3",
"property_UA": "string"
},
"kissmetrics": {"enabled": true
}
},
"min_order_value": 0,
"max_order_value": 0,
"outliers": {"order_value": {"detection_type": "none"
},
"products_ordered_count": {"detection_type": "none"
}
},
"version": "string"
},
"environments": {"production": {"label": "Production",
"is_default": true
}
}
},
"goals": [{"id": "string",
"name": "string",
"key": "string",
"type": "dom_interaction",
"rules": {"OR": [{"AND": [{"OR_WHEN": [{"rule_type": null,
"value": null,
"matching": null
}
]
}
]
}
]
},
"settings": {"tracked_items": [{"selector": "string",
"event": "string"
}
]
}
}
],
"locations": [{"id": "string",
"key": "string",
"name": "string",
"trigger": {"type": "dom_element",
"selector": "string",
"events": ["click"
]
},
"rules": {"OR": [{"AND": [{"OR_WHEN": [{"rule_type": null,
"value": null,
"matching": null
}
]
}
]
}
]
}
}
],
"audiences": [{"id": "string",
"key": "string",
"name": "string",
"type": "permanent",
"rules": {"OR": [{"AND": [{"OR_WHEN": [{"rule_type": null,
"value": null,
"matching": null
}
]
}
]
}
]
}
}
],
"segments": [{"id": "string",
"key": "string",
"name": "string",
"rules": {"OR": [{"AND": [{"OR_WHEN": [{"rule_type": null,
"value": null,
"matching": null
}
]
}
]
}
]
}
}
],
"experiences": [{"id": "string",
"name": "string",
"key": "string",
"locations": ["string"
],
"site_area": {"OR": [{"AND": [{"OR_WHEN": [{"rule_type": null,
"value": null,
"matching": null
}
]
}
]
}
]
},
"audiences": ["string"
],
"goals": ["string"
],
"status": "draft",
"global_js": "string",
"global_css": "string",
"type": "a/b",
"version": 0,
"variations": [{"id": "string",
"name": "string",
"key": "string",
"traffic_allocation": 10000,
"status": "stopped",
"changes": [{"id": 0,
"type": "defaultCode",
"data": {"css": "string",
"js": "string",
"custom_js": "string"
}
}
]
}
],
"integrations": [{"provider": "baidu",
"enabled": true,
"custom_dimension": "string"
}
],
"environments": ["string"
],
"environment": "string",
"settings": {"min_order_value": 0,
"max_order_value": 0,
"outliers": {"order_value": {"detection_type": "none"
},
"products_ordered_count": {"detection_type": "none"
}
},
"matching_options": {"audiences": "any",
"locations": "any"
}
}
}
],
"archived_experiences": ["string"
],
"features": [{"id": "string",
"name": "string",
"key": "string",
"variables": [{"key": "string",
"type": "boolean"
}
]
}
],
"is_debug": false
}

Experiences Tracking

Endpoint which allows tracking events to be sending to Convert's tracking backend

Sdk-Key Send Tracking

This endpoint allows sending of tracking events to the Convert tracking server via SDK Key authentication

Authorizations:

sdkKeyAuthdebuggingTokenAuth

path Parameters

sdk_key

required

string

The SDK key used to identify the project where that the data belongs to

Request Body schema: application/json

A JSON object containing the tracking events sent to the Convert tracking servers.

accountId	string ID of the account under which the project is setup
projectId	string ID of the project under which the tracking occurs
enrichData	boolean Flag to determine whether the data is gonna be enriched before the events are stored for reporting. For example, in case of a conversion event, if this flag is on and bucketing is not provided, the bucketing stored on the backend datastore for the given visitor ID would be used. Same applies for segments. Note: this flag is only available for some plans
	Array of objects List of visitors tracked. Each visitor can have multiple events.

Responses

Request samples

Payload

Content type

application/json

{"accountId": "string",
"projectId": "string",
"enrichData": true,
"visitors": [{"segments": {"browser": "IE",
"devices": ["ALLPH"
],
"source": "campaign",
"campaign": "string",
"visitorType": "new",
"country": "st",
"customSegments": ["string"
]
},
"visitorId": "string",
"events": [{"eventType": "bucketing",
"data": {"experienceId": "string",
"variationId": "string"
}
}
]
}
]
}

Response samples

200
default

Content type

application/json

{"code": 0,
"message": "string"
}

Send Tracking

This endpoint allows sending of tracking events to the Convert tracking server

path Parameters

account_id required	integer ID of the account that owns the given project
project_id required	integer ID of the project to which the events belong to

Request Body schema: application/json

A JSON object containing the tracking events sent to the Convert tracking servers.

accountId	string ID of the account under which the project is setup
projectId	string ID of the project under which the tracking occurs
enrichData	boolean Flag to determine whether the data is gonna be enriched before the events are stored for reporting. For example, in case of a conversion event, if this flag is on and bucketing is not provided, the bucketing stored on the backend datastore for the given visitor ID would be used. Same applies for segments. Note: this flag is only available for some plans
	Array of objects List of visitors tracked. Each visitor can have multiple events.

Responses

Request samples

Payload

Content type

application/json

{"accountId": "string",
"projectId": "string",
"enrichData": true,
"visitors": [{"segments": {"browser": "IE",
"devices": ["ALLPH"
],
"source": "campaign",
"campaign": "string",
"visitorType": "new",
"country": "st",
"customSegments": ["string"
]
},
"visitorId": "string",
"events": [{"eventType": "bucketing",
"data": {"experienceId": "string",
"variationId": "string"
}
}
]
}
]
}

Response samples

200
default

Content type

application/json

{"code": 0,
"message": "string"
}