iQ JavaScript Extension API | iQ Profiles

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 configuration programmatically using a save or save-as. After making changes with the API you must still log into the application to publish.

iQ JavaScript Extension API only works with profiles that do not inherit other libraries. If a profile inherits a library, it cannot be accessed with this endpoint. Likewise, library profiles cannot be accessed by this endpoint.

Example cURL Request

curl --location --request PATCH 'https://platform.tealiumapis.com/v3/tiq/accounts/{account}/profiles/{profile}' \
--header 'Authorization: Bearer eyJ0eXAiOi...' \
--header 'Content-Type: application/json' \
--data-raw '

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.

See the Tealium API V3 Getting Started guide to learn about generating a bearer token from the API key.

Profile fields

Profiles are JSON objects that contain the following possible fields:

Field	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`.
`parentVersion`	String	Optional	The originating profile version for the `save` or `saveAs` operations.
`notes`	String	Required	Additional notes about the publish version.
`operationList`	Array	Required	A list of operation objects. For example, multiple JavaScript extensions.
`op`	String	Required	The operation to perform: `add`, `replace`, or `remove`.
`path`	String	Required (for replace/remove)	The component type and ID to update, in the format:`/{type}/{id}`.
`value.object`	String	Required	The object type being updated: `variable` or `extension`.
`value.extensionType`	String	Required (for extensions)	For extensions, the type of extension to add.
`value.id`	String	Required (for replace/remove)	The ID of the component. This value must match the ID in the path.
`value.name`	String	Required	Title of the component.
`value.notes`	String	Optional	Additional notes about the component.
`loadRule`	Mixed	A comma-separated list of load rule IDs, or `all` for All Pages.
`value.status`	String	Optional	The on/off status of the component: `active` or `inactive`. Default: `active`
`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.occurrence`	String	Optional	Determines the number of times the JavaScript code extension runs per page load. Values: `Run Once` or `Run Always`. Default: `Run Always`.
`value.scope`	String	Optional	The name of the extension scope or, for tag-scoped extensions, a comma-separated list of tag IDs. `utag Sync` `Pre Loader` `Before Load Rules` `After Load Rules` `DOM Ready` `Tag Scoped Extensions` `After Tag Extensions`
`value.configuration`	Array[object]	Required	The configuration object for the component. This object varies for each type of component. Only one object is allowed in this array field. For example: `{ name: “code” value: “JSON-escaped JavaScript code here” }`

Example Profile object

{
  "versionTitle": "My New Extension",
  "saveType": "saveAs",
  "notes": "Added by v3 API",
  "operationList": [
    {
      "op": "add",
      "path": "/extensions",
      "value": {
        "object": "extension",
        "extensionType": "Javascript Code",
        "name": "Set default page_name",
        "occurrence": "Run Always",
        "scope": "After Load Rules",
        "loadRule": null,
        "notes": "Do not edit this extension manually.",
        "status": "active",
        "selectedTargets": {
          "dev": true,
          "qa": true,
          "prod": false
        },
        "configuration": [
          {
            "name": "code",
            "value": "b.page_name ||= \"Generic Page\";"
          }
        ]
      }
    }
  ]
}

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 an extension use:

"op" : "add",
"path" : "/extensions"

To update a specific extension, add the ID to the path:

"op" : "replace",
"path" : "/extensions/503"

Create extension

This PATCH method takes a profile object and additional extension fields.

Example Body

{
  "versionTitle": "My New Extension",
  "saveType": "saveAs",
  "notes": "Added by v3 API",
  "operationList": [
    {
      "op": "add",
      "path": "/extensions",
      "value": {
        "object": "extension",
        "extensionType": "Javascript Code",
        "name": "Set default page_name",
        "occurrence": "Run Always",
        "scope": "After Load Rules",
        "notes": "Do not edit this extension manually.",
        "status": "active",
        "selectedTargets": {
          "dev": true,
          "qa": true,
          "prod": false
        },
        "configuration": [
          {
            "name": "code",
            "value": "b.page_name ||= \"Generic Page\";"
          }
        ]
      }
    }
  ]
}

Update extension

This PATCH method takes a profile object and additional extension fields.

Example Body

{
  "versionTitle": "My New Extension",
  "saveType": "saveAs",
  "notes": "Added by v3 API",
  "operationList": [
    {
      "op": "replace",
      "path": "/extensions",
      "value": {
        "object": "extension",
        "extensionType": "Javascript Code",
        "name": "Set default page_name",
        "occurrence": "Run Always",
        "scope": "After Load Rules",
        "notes": "Do not edit this extension manually.",
        "status": "active",
        "selectedTargets": {
          "dev": true,
          "qa": true,
          "prod": false
        },
        "configuration": [
          {
            "name": "code",
            "value": "b.page_name ||= \"Generic Page\";"
          }
        ]
      }
    }
  ]
}

Delete extension

This PATCH method takes a profile object and additional extension fields.

Example request

{
  "versionTitle": "My New Extension",
  "saveType": "saveAs",
  "notes": "Added by v3 API",
  "operationList": [
    {
      "op": "remove",
      "path": "/extensions/503",
      "versionTitle": "Remove an extension",
      "value":{
        "object": "extension",
        "id": 503,
        "extensionType": "Javascript Code"
      }
    }
  ]
}

Error messages

Potential error messages for this endpoint:

Error Code	Error Message
400	`"Validate patch request failed due to path extension id and value.id not equal"` `"Validate patch request failed due to unsupported extension type {extensionType}"` `"Unsupported extension type {extensionType}"` `"Validate patch request failed due to %s"` `"Cannot set tag scope extension with tags that do not exist, id: {ID} - {account} \| profile: {profile}"` `"Cannot set extension scope to sync if the setting is not turned on - {account} \| profile: {profile}"` `"Error in getting next extension id - {account} \| profile: {profile}"` `"Profile libraries are out of date, merge changes before patching profile - {account} \| profile: {profile}"` `"Not Supported"` `"patchProfile.arg2.notes: must not be empty"`
404	`"Extension validation failed - extensionId: {id} \| account: {account} \| profile: {profile}. Cause: not found"` `"Users are currently viewing the same account: {account} profile: {profile}"` `"Extension ID {id} not found in the profile {profile}"` `"Account: {account}, profile: {profile} not found"`
409	`"Conflict with profile extension: _id: {id}, extType: {extType}, title: {title}"` `"Error saving profile: {profile} for account: {account}, duplicate versions: {versions}"` `"The given publish revision {revision} was not found - account: {account} \| profile: {profile}"`
500	`"An error occurred"` `"Profile: {profile} inherits from library profile"` `"Unable to invoke request: unknown host, see logs for more detail."` `"Error processing json for extension - account: {account} \| profile: {profile}"` `"Error saving profile metadata - account: {account} \| profile: {profile}"` `"Error saving profile - account: {account} \| profile: {profile}"` `"Error saving profile(legacy) - {account} \| profile: {profile}"`