List Methods

The segmentation methods are used to create, update, delete or get info on the lists associated with your project. Lists are used to target a subset of your app users. Available Methods are:

• Create: Create a new list to target a cohort of your users
• Import: add users to an existing list
• Update: Update an existing list
• Delete: Delete an existing list 
• List: Query existing lists
• List Items: Query existing list items
• Info: Get info on a single list

Create

Used to create a list of users that will be associated with your project.

URL

api/external/create/list

Parameters

Parameter	Description
apptoken	Your App token
name	The name of your list
identifier	The identifier used to identify users in the list options are: user_id  external_id profile_id email mobile_number device_id - first android id or IDFV collected device_idfv - current IDFV device_anid - current Android ID device_idfa - IDFA device_adid - Android Ad ID token - Push Token

Example

An example of the url and post data for creating a list with a name, and the chosen identifier to be used in the list.

url = "https://external-api.xtremepush.com/api/external/create/list"
api_data ={ "apptoken": "YOUR_APP_TOKEN",
            "identifier": "email",
            "name": "User with Propensity for Product X",
           }

Example response from a successfully created list

 
{
    "code": 200,
    "message": "List is successfully created",
    "model": {
        "id": 1090,
        "identifier": "email",
        "name": "User with Propensity for Product X",
        "project_id": xxx,
        "suppress": 0
    },
    "success": true
}

The returned response will incude the id of the created list this is used later to import users against theis list, delete/update the list etc.

Import

Used to import/update the list of users that will be associated with your list.

URL

api/external/import/list

Parameters

Parameter	Description
apptoken	Your App token
id	The id of your list
items	Array of identifier items on the list used like below:  "items": [ "email1@xtremepush.com", "email2@xtremepush.com", .... ]
mode	Two options "create" or "delete", defaults to create use with the delete option to remove ids from list.

Example

An example of the url and post data for importing users to a list with the id of the list, and the items to be added to the list.

url = "https://external-api.xtremepush.com/api/external/import/list"
api_data ={ "apptoken": "YOUR_APP_TOKEN",
            "id": "ID_of_YOUR_LIST",
            "items": [
                     "email1@xtremepush.com",
                     "email2@xtremepush.com"
                     ]
           }

Example response from a successful import of users onto a list

 
{
    "code": 200,
    "errors": [],
    "success": true
}

Update

Used to update an existing list.

URL

api/external/update/list

Parameters

Parameter	Description
apptoken	Your App token
id	The id of the list you want to update
more params	The other params are the same as those available in the create method

 

Example

An example of the url and post data for updating a list with a new name, and the chosen identifier to be used in the list.

url = "https://external-api.xtremepush.com/api/external/update/list"
api_data ={ "apptoken": "YOUR_APP_TOKEN",
            "id": 1090,
            "identifier": "email",
            "name": "User with Propensity for Product Y",
           }

Example response from a successfully updated list

 
{
    "code": 200,
    "message": "List is successfully updated",
    "model": {
        "id": 109,
        "identifier": "email",
        "name": "Car Loan Propensity",
        "project_id": 945,
        "suppress": 0
    },
    "success": true
}

 

Delete

Used to delete a list that has previously been created

URL

api/external/delete/list

Parameters

Parameter	Description
apptoken	Your App token
id	The id of the list you want to delete

 

Example

An example of the url and post data for deleting a list with a given id.

url =  "https://external-api.xtremepush.com/api/external/delete/list"
api_data = {
   "apptoken": "YOUR_APP_TOKEN",
   "id": "1090"
}

Example response from a successfully deleted list

 
{
    "code": 200,
    "message": "List is successfully deleted",
    "success": true
}

List

Used to get a list of all the lists associated with your project. All list can be returned if no condition used. Only lists of a certain type will be returned if a condition with specific criteria is provided.

URL

api/external/list/list

Parameters

Parameter	Description
apptoken	Your App token
order	Order the list in either ascending or descending order based on any of the attributes e.g. "order": ["id ASC", "id" ] or "order": ["id DESC", "id" ]
select	Select what attributes to return e.g. "select": ["id", "title"]
condition	Filter the segments based on some criteria e.g. "condition": [ ["id", ">" , 250] ]
limit	Used with offset for pagination e.g. "limit: 50, "offset": 0 returns a max of 50 segments starting at position 0
offset	Used with limit for pagination e.g. "limit: 50, "offset": 0 returns a max of 50 segments starting at position 0

 

Example

An example of the url and post data for getting a list of lists that use email as the identifier with a condition.

url = "https://external-api.xtremepush.com/api/external/list/list"
api_data = { "apptoken": "YOUR_APP_TOKEN",
 "condition":[["identifier", "=" , "email"]] 
 }

Example response from the above request:

 
{
    "code": 200,
    "data": [
        {
            "id": 1090,
            "identifier": "email",
            "name": "Propensity for Product Y",
            "project_id": 945,
            "suppress": 0
        },
        {
            "id": 1091,
            "identifier": "email",
            "name": "Restricted Users",
            "project_id": 945,
            "suppress": 1
        },
        {
            "id": 1092,
            "identifier": "email",
            "name": "Propensity for Product z",
            "project_id": 945,
            "suppress": 0
        }
    ],
    "success": true
}

 

List Items

Used to get all of the list items. Items from all lists would be returned if no condition used. `list_id` condition could be used to get items of a particular list.

URL

api/external/list/list-item

Parameters

Parameter	Description
apptoken	Your App token
order	Order the list in either ascending or descending order based on any of the attributes e.g. "order": ["value"]
select	Select what attributes to return e.g. "select": ["value"]
condition	Filter the segments based on some criteria e.g. "condition": [ ["list_id", "=" , 1] ]
limit	Used with offset for pagination e.g. "limit: 50, "offset": 0 returns a max of 50 segments starting at position 0
offset	Used with limit for pagination e.g. "limit: 50, "offset": 0 returns a max of 50 segments starting at position 0

 

Example

An example of the url and post data for getting items of a particular list

url = "https://external-api.xtremepush.com/api/external/list/list-item"
api_data = { "apptoken": "YOUR_APP_TOKEN",
 "condition":[["list_id", "=" , "1"]] 
 }

Example response from the above request:

 
{
    "code": 200,
    "data": [
        {
            "list_id": 1,
            "value": "user1"
        },
        {
            "list_id": 1,
            "value": "user2"
        }
    ],
    "success": true
}

 

Info

Used to get info on a single list.

URL

api/external/info/list

Parameters

Parameter	Description
apptoken	Your App Token
id	The id of the list you are looking for
select	Select what attributes to return e.g. "select": ["id", "title"]

 

Example

An example of the url and post data for getting info on a list with a given id.

url =  "https://external-api.xtremepush.com/api/external/info/list"
api_data = {
   "apptoken": "YOUR_APP_TOKEN",
   "id": "1090",
}

Example response from an info request

{
    "code": 200,
    "model": {
        "id": 1090,
        "identifier":"email", 
        "name": "User with Propensity for Product Y",
        "project_id": xxx,
        "suppress": 0
    },
    "success": true
}