Custom Visitor Traits API

You can use this Administrative API if you have a need to manage Custom Visitor Traits programmatically (rather than creating and updating them in the Conductrics Admin).

📘
API Keys and such
To keep this page relatively clear, we're omitting certain details from the example snippets:

These examples assume that your account is available at https://api-v3.conductrics.com. Your account may use a different endpoint (URL), especially if you're using a private Conductrics server or if your Conductrics account is located outside of the United States.

These examples show a pretend account code (acc-xxxxxx). You will need to replace that with your actual account code.

You also need to provide the admin API key for your account, either as a query parameter called apikey (so, ?apikey=admin-xxxxxxxx) or as a HTTP header called x-conductrics-apikey.

All of the above details are available in the Conductrics Admin, under Developers > API Info & Keys. If you get an "Unauthorized" message when trying to use these APIs, it's likely that one of these items wasn't provided correctly.

Getting a List of Custom Visitor Traits

You can get the list of custom visitor traits for your account via a GET request to this URL (substituting your own account code):

https://api-v3.conductrics.com/admin/acc-xxxxxx/visitor-features

Let's say a few traits have been defined already in the Conductrics Admin, with two values for "status" and two values for "source", like so:

Conductrics will respond with a structure like the following:

{
  "status": 200,
  "data": {
    "features": {
      "status:vip": {
        "name": "VIP"
      },
      "status:new": {
        "name": "Newbie"
      },
      "source:email": {
        "name": "e-mail"
      },
      "source:search": {
        "name": "Organic"
      }
    },
    "types": {
      "status": {
        "name": "Status"
      },
      "source": {
        "name": "Source"
      }
    }
  }
}

Note that there are two types defined, but all four features appear together.

The features part is an object that contains your traits, keyed by the trait code as a name/value pair, which always includes a colon. Each trait is represented by a nested object that includes the friendly name for the trait.
The types part is structured similarly. It's an object that contains the trait "types" (the parts before the colons in the trait codes) and each type is represented by a nested object that includes the friendly name for the type.

🚧
Allowed Characters
Like other "API codes" in Conductrics, the codes for your traits and types may contain letters, numbers, underscores, and hyphens, up to 100 characters. The friendly names may contain up to 50 characters.

📘
Ignore the "id" and "badges"
Within the features structure, you may see an additional id field at the trait level (alongside the name) for some of your traits, such as id=#f12 or similar. This is an internal identifier and can be ignored. The code is what's important from an integration and usage perspective.
Similarly, each type may include a badges field, which the Conductrics Admin uses for display purposes. You don't need to send it back when making changes (it's ignored if you do).

Creating or Updating a Trait Type

To create a trait type, or to change an existing one, issue a PUT request to a URL that ends with the type's code. For instance, for the source type:

https://api-v3.conductrics.com/admin/acc-xxxxxx/visitor-features/types/source

The body of your request should be a JSON object with these parts:

type - an object with the friendly name for the type (and any other settings for the type, as returned by the GET request).
features - an object containing all of the traits that should belong to this type, keyed by the full trait code (including the type code and the colon), just like in the GET response.
create_only - optional. If true, the request will fail (with HTTP status 409) if the type already exists, rather than changing it. This is handy if you want to make sure you don't accidentally overwrite a type that someone already set up.

For instance, to add a source:affil trait to the fictitious source type from the GET response shown above, you might PUT something like the following:

{
  "type": {
    "name": "Source"
  },
  "features": {
    "source:email": {
      "name": "e-mail"
    },
    "source:search": {
      "name": "Organic"
    },
    "source:affil": {
      "name": "Affiliate"
    }
  }
}

Conductrics will respond with the type and traits as saved (including the internal ids), plus a created flag that tells you whether the type is new:

{
  "status": 200,
  "data": {
    "created": false,
    "type": {
      "code": "source",
      "name": "Source"
    },
    "features": {
      "source:email": {
        "name": "e-mail",
        "id": "#f3"
      },
      "source:search": {
        "name": "Organic",
        "id": "#f4"
      },
      "source:affil": {
        "name": "Affiliate",
        "id": "#f5"
      }
    }
  }
}

Your other trait types (and their traits) are not affected. In this example, the status type and its traits stay just as they were.

🚧
Caution
The traits you provide replace whatever traits the type had previously. Any existing trait for the type that you leave out of features is removed. Likewise, the type object replaces the type's previous settings, and each trait object replaces that trait's previous settings (such as any conditions set up in the Conductrics Admin). So if a type was set up in the Conductrics Admin, you will probably want to GET the existing structure first as shown above, make whatever changes you need for that type on your side, and then PUT it back.

📘
Renaming
To rename a type or trait, PUT it with the new friendly name. Codes can't be changed. Changing a code is the same as removing the old trait or type and adding a new one.

If something about the request isn't valid (for instance, a code with characters that aren't allowed, a name that's too long, or a trait whose code doesn't start with the type's code), Conductrics will respond with HTTP status 400 and an err message that explains the problem.

Removing a Trait Type

To remove a trait type along with all of its traits, issue a DELETE request to the same URL used for creating or updating it:

https://api-v3.conductrics.com/admin/acc-xxxxxx/visitor-features/types/source

Conductrics will respond with a deleted flag:

{
  "status": 200,
  "data": {
    "deleted": true
  }
}

If the type didn't exist in the first place, deleted will be false (this isn't treated as an error).

To remove just some of a type's traits, rather than the whole type, use the PUT request described above, leaving out the traits you want to remove.

🚧
System-Managed Types
Some trait types are created and maintained automatically by Conductrics (for instance, the ones used for interaction analysis or for surveys). Those types can't be changed or removed via these requests. Conductrics will respond with HTTP status 400 if you try.