advertiser-api-guides | Segments API Guide

The InMobi Segments API allows advertisers to customise ad experiences based on user segments. Using the Segments API, advertisers can customise ads for a specific audience helping improve ad relevance and thus generate more revenue for the promoted app.

Device ID Guidelines

Segments are defined through device IDs, namely, Apple’s IDFA (ida) or Google’s Advertising ID (gpId). See table below for details

iOS

Parameter Name Parameter Type Description
ida String Identifier for advertiser without hashing. For iOS 6 and above. For more information, click here.

Android

Parameter Name Parameter Type Description
gpId String Google Play Advertising ID, without hashing. Please see here for more information.

Defining Segments

The goal of defining a segment could be either positive targeting or suppression (i.e., negative targeting).

Example:

  1. In remarketing, a common use case is to target users who have not opened the app for 30 days or more (“Dormant Users”), or users who are high-purchasing users (“High Value Users”). For these cases, a targeting list is required.
  2. Advertisers can share a suppression list to exclude those users from a campaign’s targeting. These are primarily used for user acquisition campaigns to negatively target users who have already downloaded the advertiser’s app.

Note: The same user can be tagged to more than one segment

Segmenting for User Acquisition and Remarketing

Once segment is created, it will be available for targeting at account level. A campaign manager can use this segment to include or exclude the property at Adgroup level.

API Components

The Segments API has 3 components:

  1. Creating a segment
  2. Adding and deleting users from a segment
  3. Refreshing a segment

Creating a Segment

To serve ads based on user segments, a segment needs to be created first. The parameters for creating a segment are listed below:

Parameter

Data Type

Required (Yes/No)

Description

propertyId

String

Yes

Property ID as registered with InMobi. Click here for details on registering a property with InMobi.

segmentNames

String

Yes

Segment name (unique for a property ID), lower-case unique check applied, max 2000 utf-8 characters

dst

String

Yes

To indicate the various campaign types the advertiser would like to share the segment with. The acceptable values for dst currently are:

  • ua (for User Acquisition
  • ifc (for Remarketing)

trackingPartner

String

Yes

Name of the Tracking Partner registered on InMobi. If not registered, please get it registered.

Format for sending requests: GET Method

URL Format

http://advertiser.inmobiapis.com/tpce/v1/segment?dst=dst&trackingPartner=trackingPartner&propertyId=propertyId&segmentName=segmentName

URL Example

http://advertiser.inmobiapis.com/tpce/v1/segment?segmentName=FirstSegment&dst=ifc&trackingPartner=Leanplum&propertyId=ffd89901feb145c1b3c3b22e36fa5af7

JSON Response for Success

  • For User Acquisition: 

    {
    "status":"OK",
    "message":"success",
    "code":"200"
}

  • For Remarketing: 

    {
    "status":"OK",
    "message":"success",
    "code":"200"
}

JSON Response for Failure

For User Acquisition: 

{
    "status":"error_status",
    "message":"error_message",
    "code":"error_code"
}

Adding and deleting users from a segment

Advertisers can add or remove a list of devices from an existing segment using this API. The parameters for adding or deleting devices from a segment are listed below:

Note: Refer to the Installs document before tagging an user to a segment.

Parameter

Data Type

Required (Yes/No)

Description

propertyId

String

Yes

The property ID as registered with InMobi. Click here for details on registering a property with InMobi.

segmentIds

String

Yes

List of segment IDs (separated by semicolons) that the user is present in.

segmentNames

String Yes

List of segment names (separated by semicolons) that the user is present in.

Note: This will be used for Remarketing.

ida

String

Yes

Device identifier adhering to the guidelines in the device ID section. This one is mandatory for iOS.

gpId

String

Yes

Device identifier adhering to the guidelines in the device ID section. It is mandatory for Android.

action

String

Yes

Possible values are add and delete.

These are actions to be performed for a user on given property and segment IDs. Use this parameter to:

  • add a user to a segment
  • or delete the user from a segment

dst

String

Yes

The currently acceptable values for dst are:

  • ua (for User Acquisition)
  • ifc (for Remarketing)

Multiple values can be separated using a semicolon. Example: …&dstList={ua; ifc}&...

Format for sending requests

Adding and deleting a single user: GET Method

URL Format

http://advertiser.inmobiapis.com/tpce/v1/usersegment?action=add&dstList=dstList&gpId=gpId&propertyId=propertyId&segmentIds=segmentIds

URL Example

http://advertiser.inmobiapis.com/tpce/v1/usersegment?action=add&dstList=ua&gpId=c532730e-cc24-4edd-a8d6-236e9ed8f1c9&propertyId=561d12f676eb466aa6ad048210c5da49&segmentIds={1;2;3}

JSON Response for Success 

{
    "status":"OK",
    "message":"success",
    "code":"200"
}

JSON Response for Failure 

 {
    "status":"error_status",
    "message":"error_message",
    "code":"error_code"
 }

Notes:

  • Device IDs are sent independently in the query parameters
  • Double quotes are not required around any parameter
  • Segment IDs need to be semicolon-separated, and within a curly bracket
Adding and deleting multiple users: POST Method

Advertisers can upload bulk segment data to add or delete multiple users from a segment. A maximum of 10 MB of data can be uploaded in .CSV format. The .CSV file must be zipped.

Note: You can submit a list of user ids via file upload. The file should have the predefined headers.

URL Format

http://advertiser-content.inmobiapis.com/tpce/v1/upload/usersegment?propertyId=propertyId&segmentNames=segmentNames&segmentIds=segmentIds&dstList=dstList&action=add/delete

URL Example

http://advertiser-content.inmobiapis.com/tpce/v1/upload/usersegment?propertyId=propertyId&segmentNames=segmentName1&segmentIds=segmentId2&dstList={ua,ifc}&action=add

CSV File Headers

gpId, ida

Example

202cb962ac59075b964b07152d234b70

Response Content Headers

  • Content Type: multipart/form-data
  • Accept-Encoding: gzip
  • Content-Disposition: attachment; filename="xyzfilename"
  • Content-Type: text/csv
  • Content-Transfer-Encoding: binary

JSON Response for Success 

{
    "status":"OK",
    "message":"success_message xxxxxx",
    "code":"200",
    "jobUrl":"job url to check status of file upload"
}

Note: The jobUrl will give a JSON response indicating whether the job has succeeded, failed, or is in progress.

JSON Response for Failure 

{
    "status": "BAD_REQUEST",
    "message": "Invalid file Content found : Internal errors encountered..java.util.NoSuchElementException: No value present",
    "code":"1004"
}

Refreshing a segment

Advertisers can refresh a segment to update the list of users added to it. The parameters for refreshing the list of devices in a segment are listed below:

Parameter

Data Type

Required (Yes/No)

Description

propertyId

String

Yes

gpmId of the app (provided by InMobi team)

segmentIds

String

Yes

Segment id of the segment to be added/refreshed (received from createSegment API)

segmentNames

String Yes

Name of the segment to be added/refreshed (received from createSegment API)

Note: This is used for Remarketing.

dstList

String

Yes

The currently acceptable value is ifc (for Remarketing).

Source

String

Yes

The source for this segment data

Format for sending request: POST Method

URL Format

http://advertiser-content.inmobiapis.com/tpce/v1/upload/segment/refresh

URL Example

https://advertiser-content.inmobiapis.com/tpce/v1/upload/segment/refresh?propertyId=sampleGpmId&segmentName=sampleSegmentName&dst=ifc

Response Content Headers

  • Content Type: multipart/form-data
  • Accept-Encoding: gzip
  • Content-Disposition: attachment; filename="xyzfilename"
  • Content-Type: text/csv
  • Content-Transfer-Encoding: binary

JSON Response for Success 

{
    "status":"OK",
    "message":"success_message xxxxxx",
    "code":"200",
    "jobUrl":"job url to check status of file upload"
}

JSON Response for Failure 

{
    "status": "BAD_REQUEST",
    "message": "Invalid file Content found : Internal errors encountered..java.util.NoSuchElementException: No value present",
    "code":"1004"
}

Notes:

  • A maximum of 50 MB of data can be uploaded in .CSV format. The .CSV file must be zipped
  • The .CSV file can contain upto two columns (ida and gpid)
  • Of the two columns, only one can be "non-blank" in each row
  • The first row should contain one or more of following headers - ida or gpId. The corresponding rows may contain the deviceIds

File Compression Command: gzip file.csv

This would create a gzipped file called file.csv.gz