iQ Tags API
iQ Tags API uses a PATCH method to update profile tags.
To learn more about this API and available object fields, see iQ Profiles API and iQ Profiles Objects.
How it works
Use the PATCH method to create, update, and delete components in the iQ Profile object.
PATCH /v3/tiq/accounts/{ACCOUNT}/profiles/{PROFILE}
When you use the PATCH method, you are making changes to your profile tags programmatically using a save or save-as. After making changes with the API, you must still log into the application to publish.
Example cURL request
curl --location --request PATCH 'https://platform.tealiumapis.com/v3/tiq/accounts/{ACCOUNT}/profiles/{PROFILE}' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzUx...MiJ9' \
--header 'Content-Type: application/json' \
--data '
Authentication
The bearer token is used to authenticate all API calls and not the API key. The API key is only used in the authentication call. In addition to the bearer token, the authentication response includes a region-specific hostname that must be used in subsequent server-side API calls.
To learn about generating a bearer token from the API key, see Authentication.
Profile fields
Profile tags are JSON objects that contain the following possible fields:
| OBJECT | TYPE | REQUIRED | DESCRIPTION |
|---|---|---|---|
versionTitle |
String | Optional | The title of the resulting saved version. Default with saveType set to saveAs : API | {TIMESTAMP}Default with saveType set to save: Existing version title |
saveType |
String | Optional | The type of save to perform with the PATCH request: save or saveAs. Default is saveAs. |
notes |
String | Required | Additional notes about the publish version. |
operationList |
Array | Required | A list of operation objects. For example, multiple tags. |
op |
String | Required | The operation to perform: add, replace, or remove. |
path |
String | Required | The component type and ID to update, in the format:/{TYPE}/{ID}. |
value.object |
String | Required | The object type being updated: variable, extension, event, or tag. |
value.tagID |
String | Required | The unique tag template ID. Use a GET request to retrieve the tag ID. Note that this value is different from the tag UID. |
value.status |
String | Optional | The on/off status: active or inactive. |
value.notes |
String | Optional | Notes about the tag. |
value.name |
String | Required (for add/replace) | Name of the tag. |
value.selectedTargets |
Map <string, Boolean> | Optional | An object of environments to publish the component to. { "prod" : true|false, "qa" : true|false, "dev" : true|false } Default: All environments set to true. |
value.tagConfiguration |
Map <String, Object> | Optional | A String and Object Map of tag configurations made available by the vendor. Configurations are specific to each tag. For more information, see the documentation for your tag. |
value.advancedConfiguration |
Object | Optional | A set of advanced configurations corresponding to the tag configuration settings. advConfigBundle — True or FalseadvConfigLoadType — True or FalseadvConfigOptOut — TrueadvConfigSend— True or False advConfigSrc — Text fieldtagTiming — DOM Ready or Prioritized |
value.rules |
Object | Optional | The load rules to apply or exclude from the tag. |
value.dataMappings |
Map <String, String> | Optional | The Tealium IQ variable and its corresponding mapped destination. You can verify the specific format for the mapped variable triggers in the Data Mappings screen in your tag configuration. |
Example request
{
"versionTitle": "version title",
"notes": "notes",
"operationList": [
{
"op": "add",
"path": "/tags",
"value": {
"object": "tag",
"tagId": "7133",
"status": "active",
"notes": "adding tag",
"name": "7133 tag Google Analytics",
"dataMappings": [
{
"variable": "variable_name",
"type": "udo",
"mappings": ["a1", "a2"]
}
],
"selectedTargets": {
"qa": true,
"dev": true,
"prod": true
},
"advancedConfiguration": {
"bundleFlag": true,
"syncLoadType": false,
"optout": true,
"scriptSource": "",
"sendFlag": false,
"tagTiming": "Dom Ready"
},
"tagConfiguration": {
"tracking_id": "123"
},
"rules": {
"apply": [{"and": [{"or": [{"uid": "2", "type": "loadRule"}]}]}],
"exclude": [{"and": [{"or": [{"uid": "3", "type": "loadRule"}, {"uid": "2", "type": "loadRule"}]}]}]
}
}
}
]
}
PATCH operation parameters
Instead of POST, PUT, and DELETE methods, the PATCH method uses the op parameter to specify the action to perform.
The op parameter supports the following values:
add- Create the component.replace- Update the component.remove- Delete the component.
To specify the the type and ID of the component, use the path parameter. The path parameter format is /{TYPE}/{ID}.
For example, to add a tag use:
"op" : "add",
"path" : "/tags"
To update a specific tag, add the ID to the path:
"op" : "replace",
"path" : "/tags/503"
Create tag
This PATCH method takes a profile object and additional tag fields.
Example request
{
"versionTitle": "version title",
"notes": "notes",
"operationList": [
{
"op": "add",
"path": "/tags",
"value": {
"object": "tag",
"tagId": "7133",
"status": "active",
"notes": "adding tag",
"name": "7133 tag Google Analytics",
"dataMappings": [
{
"variable": "variable_name",
"type": "udo",
"mappings": ["a1", "a2"]
}
],
"selectedTargets": {
"qa": true,
"dev": true,
"prod": true
},
"advancedConfiguration": {
"bundleFlag": true,
"syncLoadType": false,
"optout": true,
"scriptSource": "",
"sendFlag": false,
"tagTiming": "Dom Ready"
},
"tagConfiguration": {
"tracking_id": "123"
},
"rules": {
"apply": [{"and": [{"or": [{"uid": "2", "type": "loadRule"}]}]}],
"exclude": [{"and": [{"or": [{"uid": "3", "type": "loadRule"}, {"uid": "2", "type": "loadRule"}]}]}]
}
}
}
]
}
Update tag
This PATCH method takes a profile object and additional tag fields.
Example request
{
"versionTitle": "version title",
"notes": "notes",
"operationList": [
{
"op": "replace",
"path": "/tags/21",
"value": {
"object": "tag",
"tagId": "7133",
"status": "active",
"notes": "adding tag",
"name": "Replace name by API Google Analytics",
"dataMappings": [
{
"variable": "variable_name",
"type": "udo",
"mappings": ["a1", "a2"]
}
],
"selectedTargets": {
"qa": true,
"dev": true,
"prod": true
},
"advancedConfiguration": {
"bundleFlag": true,
"syncLoadType": false,
"optout": true,
"scriptSource": "",
"sendFlag": false,
"tagTiming": "Dom Ready"
},
"tagConfiguration": {
"tracking_id": "123"
},
"rules": {
"apply": [{"and": [{"or": [{"uid": "2", "type": "loadRule"}]}]}],
"exclude": [{"and": [{"or": [{"uid": "3", "type": "loadRule"}, {"uid": "2", "type": "loadRule"}]}]}]
}
}
}
]
}
Delete tag
This PATCH method takes a profile object and additional tag fields.
Example request
{
"versionTitle": "Version 2022.03.22.2108",
"saveType": "saveAs",
"notes":"",
"operationList": [
{
"op": "remove",
"path": "/tags/230",
"value":{
"object":"tag"
}
}
]
}
Error messages
Potential error messages for this endpoint:
| ERROR CODE | ERROR MESSAGE |
|---|---|
| 400 | "Profile libraries are out of date, merge changes before patching profile - {ACCOUNT} | profile: {PROFILE}""patchProfile.arg2.notes: must not be empty" |
| 404 | "Profile not found - account: {ACCOUNT} | profile: {PROFILE}""Profile library not found - account: {ACCOUNT} | profile: {PROFILE}""Profile (legacy) not found - account: {ACCOUNT} | profile: {PROFILE}""Users are currently viewing the same account: {ACCOUNT} | profile: {PROFILE}""Latest version not found - {ACCOUNT} | profile: {PROFILE}" |
| 409 | "Error saving profile: {PROFILE} for account: {ACCOUNT}, duplicate versions: {VERSION}" |
| 500 | "Profile: {PROFILE} inherits from library profile""Error saving profile metadata - account: {ACCOUNT} | profile: {PROFILE}""Error saving profile - account: {ACCOUNT} | profile: {PROFILE}""Error saving profile(legacy) - {ACCOUNT} | profile: {PROFILE}" |
This page was last updated: October 2, 2024