UserIQ Custom Data APIs

The UserIQ Custom Data API gives development teams more control over attributes associated with users and accounts. The UserIQ Custom Data API is available to customers with a valid API access token.

post account/update

Adds/updates account attribute data for a specific account. If the account does not exist, the account will be created.

Resource URL
https://api.useriq.com/api/1.0/account_data/update

Resource Information
Request Type: POST
Response Format: JSON

Headers

1. useriq-api-key (required): Your valid API key generated from the Site settings page

2. Content-Type=application/json

Parameters

account_id (required)
The account_id of the account to be updated with the associated custom data attribute (Note: this should match the value passed in the UserIQ tracking code as 'account_id').
Example: 123
key (required)
Description: The name of the custom data attribute (this will show up in the list of user and/or account attributes when defining audience filters and segments).
Example: 'account_subscription_level'
value (required)
The value of the custom data attribute
Example: 'Platinum'
account_name (optional)The account name. Note, for an existing account, when this is supplied with a non-null value, it overrides the existing account name.

Example Request:

HTTP

https://api.useriq.com/api/1.0/account_data/update 
body
{
"account_id": "1234",
"account_name": "iron steel inc",
"key": "account_subscription_level",
"value": "Platinum" 
}

Example Result

{ "result":"success" }

Response Codes
200: OK. Request processed successfully
400: Bad Request. API request could not be understood by the server.
401: Unauthorized. Invalid API access token.

post user/update

Adds/updates user attribute data for a specific user. If the user does not exist, the user will be created.

Resource URL
https://api.useriq.com/api/1.0/user_data/update

Resource Information
Request Type: POST
Response Format: JSON

Headers

1. useriq-api-key (required): Your valid API key generated from the Site settings page

2. Content-Type=application/json

Parameters

user_id (required)
The user_id of the user record to be updated with the associated custom data attribute (Note: this should match the value passed in the UserIQ tracking code as 'user_id').
Example: 123
key (required)
Description: The name of the custom data attribute (this will show up in the list of user and/or account attributes when defining audience filters and segments).
Example: 'account_subscription_level'
value (required)
The value of the custom data attribute
Example: 'Platinum'
user_name (optional) The user name. Note for an existing user, when this is supplied with a non-null value, it overrides the existing username.
Example 'Tom Burdon'
account_id (optional)The account_id that this user belongs to. When supplied with an existing account_id, it binds this user to the target account. This parameter is ignored if the account_id does not already exist.
Example: '123'

Example Request:

HTTP

https://api.useriq.com/api/1.0/user_data/update 
body 
    { 
      "user_id":"1234",
      "user_name" : "Sam Blake",
      "account_id" : "123", 
      "key":"account_subscription_level", 
      "value":"Platinum" 
    }

Example Result
{ "result":"success" }

Response Codes
200: OK. Request processed successfully
400: Bad Request. API request could not be understood by the server.
401: Unauthorized. Invalid API access token.

user/update_bulk

Adds/updates user attribute data for multiple users and/or key-value pairs. The users will be created if they do not exist.

Resource URL
https://api.useriq.com/api/1.0/user/update_bulk

Resource Information
Request Type: POST
Response Format: JSON

Headers

1. useriq-api-key (required): Your valid API key generated from the Site settings page

2. Content-Type=application/json

Parameters

user_data (required)
The array of user data to be updated in bulk. There is a limit of 500 elements in the user_data array. Each element in the array should include the following 3 fields:

user_id (required)
The user_id of the user record to be updated with the associated custom data attribute (Note: this should match the value passed in the UserIQ tracking code as 'user_id').
Example: 123
key (required)
Description: The name of the custom data attribute (this will show up in the list of user and/or account attributes when defining audience filters and segments).
Example: 'account_subscription_level'
value (required)
The value of the custom data attribute
Example: 'Platinum'
user_name (optional) The user name. Note that for an existing user, when this is suplied with a non null value, it overrides the existing user name.
Example 'Tom Burdon'
account_id (optional) The account_id that this user belongs to. When supplied with an existing account _id, it binds this user to the target account. This parameter is ignored if the account_id does not already exist.
Example: '123'

Example Request:

HTTP

https://api.useriq.com/api/1.0/user/update_bulk 
body 
     { 
       "user_data": 
                   [ 
                     { 
                       "user_id": "123",
                       "user_name": "Sam Blake",
                       "account_id": "123", 
                       "key": "account_subscription_level", 
                       "value": "Platinum" 
                     }, 
                     { 
                       "user_id": "456",
                       "user_name": "Tony Griffin",
                       "account_id": "123", 
                       "key": "account_subscription_level", 
                       "value": "Gold" 
                     } 
                   ] 
     }

Example Result
{ "result":"success" }

Response Codes
200: OK. Request processed successfully
400: Bad Request. API request could not be understood by the server.
401: Unauthorized. Invalid API access token.

Account/update_bulk

Adds/updates account attribute data for multiple accounts and/or key-value pairs. If the target accounts do not exist, they will be created.

Resource URL
https://api.useriq.com/api/1.0/account/update_bulk

Resource Information

Request Type: POST
Response Format: JSON

Headers

1. useriq-api-key (required): Your valid API key generated from the Site settings page

2. Content-Type=application/json

Parameters

account_data(required)
The array of account data to be updated in bulk. There is a limit of 500 elements in the account_data array. Each element in the array should include the following 3 fields:

Account_id (required)
The account_id of the account record to be updated with the associated custom data attribute (Note: this should match the value passed in the UserIQ tracking code as ‘account_id').
Example: 123
key (required)
Description: The name of the custom data attribute (this will show up in the list of accounts and/or account attributes when defining audience filters and segments).
Example: 'account_subscription_level'
value (required)
The value of the custom data attribute
Example: 'Platinum'
account_name (optional)The account name. Note, for an existing account, when this is supplied with a non-null value, it overrides the existing account name.

Example Request:

HTTP

https://api.useriq.com/api/1.0/account/update_bulk 
body 
     { 
       "account_data": 
                       [ 
                         { 
                           "account_id": "123",
                           "account_name: "foo company", 
                           "key": "foo", 
                           "value": "bar" 
                         }, 
                         { 
                           "account_id": "456",
                           "account_name: "foo1 company", 
                           "key": "foo1", 
                           "value": "bar1" 
                         } 
                       ] 
     }

Example Result
{ "result":"success" }

Response Codes
200: OK. Request processed successfully
400: Bad Request. API request could not be understood by the server.
401: Unauthorized. Invalid API access token.

post campaign/reset_user

Resets campaigns for a user so that they will be delivered again if filter criteria are met.

Resource URL
https://api.useriq.com/api/1.0/campaign/reset_user

Resource Information
Request Type: POST
Response Format: JSON

Headers

useriq-api-key (required): Your valid API key generated from the Site settings page

Parameters

user_id (required)
The user_id of the user record to be updated with the campaign reset (Note: this should match the value passed in the UserIQ tracking code as 'user_id').
Example: 123
c_id (required)
Description: The UserIQ campaign ID to be reset.
Example: '9876'
redirect_url (optional)
The URL that a user should be redirected to after the reset is complete
Example: 'https%3A%2F%2Fgoogle.com%0A'

Example Request:

HTTP

https://api.useriq.com/api/1.0/campaign/reset_user?user_id=1234&c_id=9876&redirect_url=https%3A%2F%2Fgoogle.com%0A
  -H
    useriq-api-key:572d7372829a3211a73d9c2cb790ffe3

Example Result
{ "result":"success" }

Response Codes
200: OK. Request processed successfully
400: Bad Request. API request could not be understood by the server.
401: Unauthorized. Invalid API access token.

get campaign/list

Get a list of campaigns for your site.

Resource URL
https://api.useriq.com/api/1.0/campaign/list

Resource Information
Request Type: GET
Response Format: JSON

Headers

useriq-api-key (required): Your valid API key generated from the Site settings page

Parameters

status (optional)
Description: The status of the campaigns you would like returned. If no status parameter is specified, we will return all campaigns for the site that are not Archived.
Possible values (case sensitive):
Active
Paused
Preview
Archived
page_number (optional)
Description: The page number of results you would like to retrieve. We will return up to 100 results per page. DEFAULT: 1
Example: 1

Example Request:

Text

https://api.useriq.com/api/1.0/campaign/list
https://api.useriq.com/api/1.0/campaign/list?status=Active
  -H
    useriq-api-key:572d7372829a3211a73d9c2cb790ffe3

Example Result
{
"results": [
{
"created_at": "2015-08-21T15:24:31Z",
"id": 1111,
"is_version_parent": null,
"name": "Home Page",
"status": "Preview",
"url_to_show_on": "http://mycompany.com/index.html",
"version_parent_id": null,
"version_segment_id": null
},
{
"created_at": "2015-09-1T21:45:07Z",
"id": 1112,
"is_version_parent": null,
"name": "Dashboard",
"status": "Paused",
"url_to_show_on": "http://mycompany.com/dashboard",
"version_parent_id": null,
"version_segment_id": null
},
...
],
"page": 1,
"results_per_page": 33,
"total_results": 33
}

Response Codes
200: OK. Request processed successfully
400: Bad Request. API request could not be understood by the server.
401: Unauthorized. Invalid API access token.

get campaign/search

Get a list of campaigns for your site that contain or match a query provided.

Resource URL
https://api.useriq.com/api/1.0/campaign/search

Resource Information
Request Type: GET
Response Format: JSON

Headers

useriq-api-key (required): Your valid API key generated from the Site settings page

Parameters

query (required)
Description: The string you would like to try and match to a campaign's name. This parameter is case insensitive.
Example: my%20campaign

Example Request:

Text

https://api.useriq.com/api/1.0/campaign/search
https://api.useriq.com/api/1.0/campaign/search?query=my%20campaign
  -H
    useriq-api-key:572d7372829a3211a73d9c2cb790ffe3

Response Codes
200: OK. Request processed successfully
400: Bad Request. API request could not be understood by the server.
401: Unauthorized. Invalid API access token.

get campaign/results

Gets results for a given campaign provided. This endpoint provides an array of results in batches of 100. You can supply a page_number parameter to get additional results (see below).

Resource URL
https://api.useriq.com/api/1.0/campaign/results

Resource Information
Request Type: POST
Response Format: JSON

Headers

useriq-api-key (required): Your valid API key generated from the Site settings page

Parameters

c_id (required)
Description: The UserIQ campaign ID you would like to get results for.
Example: 123
page_number (optional)
Description: The page number of results you would like to retrieve. We will return up to 100 results per page. DEFAULT: 1
Example: 1

Example Request:

HTTP

https://api.useriq.com/api/1.0/campaign/results?c_id=9876
  -H
    useriq-api-key:572d7372829a3211a73d9c2cb790ffe3

Example Result
{
"results": [{
"action_taken": "completed",
"created_at": "2016-10-03T19:27:25Z",
"customer_user_id": "jwhitmer@omegafi.com",
"interaction": null,
"interaction_state": null,
"last_step_seen": null,
"updated_at": "2016-10-03T19:41:13Z",
"visitor_id": "8769448b3e90b14b",
"visitor_name": "",
"visitor_email": "",
"cvar1_name": null,
"cvar1_value": null,
"cvar2_name": null,
"cvar2_value": null,
"cvar3_name": null,
"cvar3_value": null,
"cvar4_name": null,
"cvar4_value": null,
"cvar5_name": null,
"cvar5_value": null,
"cvar6_name": null,
"cvar6_value": null,
"cvar7_name": null,
"cvar7_value": null,
"cvar8_name": null,
"cvar8_value": null,
"cvar9_name": null,
"cvar9_value": null,
"cvar10_name": null,
"cvar10_value": null,
"cvar11_name": null,
"cvar11_value": null,
"cvar12_name": null,
"cvar12_value": null,
"cvar13_name": null,
"cvar13_value": null,
"cvar14_name": null,
"cvar14_value": null,
"cvar15_name": null,
"cvar15_value": null,
"cvar16_name": null,
"cvar16_value": null,
"cvar17_name": null,
"cvar17_value": null,
"cvar18_name": null,
"cvar18_value": null,
"cvar19_name": null,
"cvar19_value": null,
"cvar20_name": null,
"cvar20_value": null
}, ...
],
"page": 1,
"results_per_page": 100,
"total_results": 5429
}

Response Codes
200: OK. Request processed successfully
400: Bad Request. API request could not be understood by the server.
401: Unauthorized. Invalid API access token.

How Can We Help?

Articles in this section

post account/update

post user/update

user/update_bulk

Account/update_bulk

post campaign/reset_user

get campaign/list

get campaign/search

get campaign/results

Comments

How Can We Help?

Articles in this section

post account/update

post user/update

user/update_bulk

Account/update_bulk

post campaign/reset_user

get campaign/list

get campaign/search

get campaign/results

Related articles