InMobi DSP Cost API

The InMobi Cost API enables you to access the cost metrics (billable amount) for your campaigns running on the InMobi DSP. You can use the data to calculate your Return on Ad Spent (RoAS).

Pre-requisites 

Before you start the integration, make sure you have:

  • An active or paused campaign on InMobi DSP. 
  • Got Cost API Authentication credentials from the InMobi team. 

The API Keys and API Secret authorize access to the InMobi Cost API and generate a temporary access token. The base URL for all API requests is https://api.cdr.inmobi.com/api/v3.

Note

If you are an existing InMobi DSP customer, the base URL https://dashboard.dsp.inmobi.com/api/v2 remains active and redirects you to the base URL https://api.cdr.inmobi.com/api/v2.

However, to leverage new DSP CostAPI features, use https://api.cdr.inmobi.com/api/v3.

Integrate Cost API

You can integrate the InMobi Cost API using the following four APIs:

  • Authentication API: Generates a temporary token using the client API key for authorization. 
  • Report creation API: Requests the media cost report by specifying a date range, custom dimension (or measure), and filtering on dimension (if required).
  • Report status API: Check for report status. 
  • Report download API: Download the report once it is available. 

Data query guidelines 

The API data query guidelines are as follows: 

Value Data type Description
OK String The API call was processed without any error.
success String Message for successful integration.
200 Number Refers to the https status code.
64d9e0bb-ad9c-4235-8b6e-2d1e6ad40cb3 String The ID of the segment created in the InMobi DSP

Dimensions and Measures

InMobi Cost API keys have been categorized among Dimensions and Measures

  • Dimensions refer to the keys that identify the attributes of the DSP campaigns, for example, Date, InMobi Account ID, Advertiser Name, Campaign ID, Campaign Name, Country, etc. 
  • Measures refer to the campaign's metrics, for example, Impressions, Clicks, Installs, Events, Media Cost, Click-through Rate (CTR), Conversion Rate (CR), Install per mille (IPM), etc. 

API endpoints  

You must add Cost API endpoints at the end of the API Base path to initiate API calls. The Cost API offers the following endpoints: 

/programmatic & /network

Use this endpoint for Android and iOS (non-SKAN) campaigns. The dimensions and measures for /programmatic & /network are as follows:

Type Fields Data type Description
Dimension date String Date (YYYY-MM-DD) of reporting data
Dimension inmobi_account_id String Unique ID for the advertiser on InMobi Platform
Dimension advertiser_name String Name of the advertiser
Dimension campaign_id String Unique ID for the campaign on InMobi Platform
Dimension campaign_name String Name of the campaign
Dimension country String The country where the ad rendered, for example, India
Dimension os String The user's device operating system. The value can be android or iOS.
Dimension publisher_app_bundle String Bundle ID of the publisher app where the ad rendered. For example, com.kiloo.com
Dimension publisher_app_name String Name of the publisher app where the ad rendered. For example, Subway Surfers
Dimension advertiser_app_bundle String Bundle ID of the advertiser app for which the ad rendered. For example, com.domain_name.com
Dimension advertiser_app_name String Name of the app for which the ad was rendered. For example, Subway Surfers
Dimension exchange String Programmatic exchange source where the media was bought. For example, AppLovin, Vungle, etc.
Dimension event_name String The user action as a primary or secondary event. For example, registrations,add_to_cart, etc.
Dimension device_type String Type of the user's device. For example, Smartphone, tablet, UNKNOWN, etc.
Dimension channel String InMobi Channel via which the advertiser bought the media
Dimension ad_id String Unique ID for the ad
Dimension ad_name String Ad name in the platform
Dimension ad_type String Type of the ad rendered
Measure impressions Integer Number of ads renders
Measure clicks Integer Number of clicks on the ads
Measure installs Integer Number of app downloads
Measure events Integer Number of user actions driven by the ad
Measure media_cost Double An indicative billable amount
Measure ctr Double Click Through Rate = (Clicks / Impressions) * 100
Measure cr Double Conversion Rate = (Installs / Clicks) * 100
Measure ipm Double Install Per Mille = (Installs / Impressions) * 1000
Measure ecpm Double Cost Per Thousand Impressions = (Media Cost / Impressions) * 1000
Measure ecpc Double Cost Per Click = Media Cost / Clicks
Measure ecpi Double Cost Per Install = Media Cost / Installs
Measure ecpe Double Cost Per Event = Media Cost / Events

Note:

If you don’t provide any dimensions or measures value, the API returns a default report with the following fields:

  • Dimensions: date, inmobi_account_id, advertiser_name, campaign_id, campaign_name, country, os, publisher_app_bundle, exchange, event_name, device_type, and channel.
  • Measures: impressions, clicks, installs, events, media_cost, ctr, cr, ipm, ecpm, ecpc, ecpi,and ecpe.

/skan

Use this endpoint for iOS SKAN & Probabilistic Attribution campaigns. The dimensions and measures for /skan are as follows:

Type Fields Data type Description
Dimension date String Date (YYYY-MM-DD) of reporting data
Dimension inmobi_account_id String Unique ID for the advertiser on InMobi Platform
Dimension advertiser_name String Name of the advertiser
Dimension campaign_id String Unique ID for the campaign on InMobi Platform
Dimension campaign_name String Name of the campaign
Dimension country String The country where the ad was rendered. For example, India
Dimension os String The user's device operating system, the value is iOS by default.
Dimension publisher_app_bundle String Bundle ID of the publisher app where the ad rendered.
Dimension publisher_app_name String Name of the publisher app where the ad rendered. For example, Call of Duty.
Dimension advertiser_app_bundle String Bundle ID of the advertiser app.
Dimension advertiser_app_name String Name of the advertiser app. For example, Call of Duty
Dimension exchange String Programmatic exchange from where the media was bought. Supported only for probabilistic attribution campaigns. For example, AppLovin, Vungle, etc.
Dimension event_name String The user action to be tracked as a primary or secondary event. Example: registrations, add_to_cart, etc.
Dimension ad_id String Unique ID for the ad. Supported only for probabilistic attribution campaigns.
Dimension ad_name String Ad name in the platform. Supported only for probabilistic attribution campaigns.
Dimension ad_type String Type of the ad rendered. Supported only for probabilistic attribution campaigns.
Measure impressions Integer Number of ads renders
Measure clicks Integer Number of clicks on the ads
Measure skan_installs Integer Number of app downloads through SKADNetwork attribution
Measure installs Integer Number of app downloads through Probabilistic attribution
Measure skan_events Integer Number of user actions driven by the ad through SKADNetwork attribution
Measure probabilistic_events Integer Number of user actions driven by the ad through Probabilistic attribution
Measure media_cost Double An indicative billable amount
Measure ctr Double Click Through Rate = (Clicks / Impressions) * 100
Measure ecpm Double Cost Per Thousand Impressions = (Media Cost / Impressions) * 1000
Measure ecpc Double Cost Per Click = Media Cost / Clicks

Note:

If you don’t provide any dimensions or measures value, the Cost API returns a default report with the following fields:

  • Dimensions: date, inmobi_account_id, advertiser_name, campaign_name, country, os, publisher_app_bundle, exchange, and event_name.
  • Measures: impressions, clicks, skan_installs, installs, skan_events, probabilistic_events, media_cost, ctr, ecpm, and ecpc.

Call APIs

After adding the required API endpoints, you can call the Cost APIs as follows: 

Step 1: Call the Authentication API. 

The Authentication API generates a temporary token using the client API key for authorization. The token is valid for 8 hours only.  

  1. Provide the token in the authorization field for subsequent calls to the API endpoint. 
  2. Generate a token to call APIs. Contact your InMobi account manager to access the client ID-key pair. 

You can call the API using a POST or a cURL request 

Sample POST request  

POST URL: https://api.cdr.inmobi.com/api/v3/auth/token

Request body: 

{

clientId : string,

clientSecret : string

} 

Request field details:

Request Field Value Mandatory
Body clientId placeholder_ID Yes
Body clientSecret placeholder_key Yes

Sample POST response 

{

“status”: “SUCCESS”,

“code”: 200,

“data”:

 {

 “token”:string,

 “validTill”: YYYY-MM-DDTHH:MM:SS

 },

“message”: "Request processed successfully"

} 

Response field details:

Fields Description
status
  • The status of the API call.
code
  • The code for the status.
    • 200: SUCCESS
    • 500: error
    • 400: Bad Request
data
  • Provides authorization token and validity details
token
  • The temporary token for the API call.
  • Valid for 8 hours only
  • Provide this token in the authorization field for subsequent API calls.
validTill
  • Expiry timestamp of the token
message
  • Final message for the confirmation of the status of the API call.

cURL Request

You can also call the Authentication API using the following cURL request:

curl --location --request POST 'https://api.cdr.inmobi.com/api/v3/auth/token' \ 
--header 'Content-Type: application/json' \ 
--data-raw '{ 
"clientId": "<YOUR-CLIENT-ID>", "clientSecret": "<YOUR-CLIENT-SECRET>" 
}' 

Step 2: Call the Report Creation API.

The Report Creation API requests the report by specifying a date range, custom attributes (dimension or measure), and filtering on dimension (if required). You can call the API using a POST or a cURL request.

Sample POST request

POST URL:

Notes:

  • *PA refers to Probabilistic attribution. Probabilistic attribution uses statistics and machine learning to guess how likely it is that an event led to a conversion or revenue. It's often used in mobile marketing when device IDs are not available.
  • To avoid duplicate data retrieval for iOS probabilistic attribution campaigns when using both the /programmatic and /skan endpoints, include the "os":["Android"] filter in the /programmatic endpoint API call. This filter helps streamline data extraction and ensures accuracy across platforms.

Header:

{ 
 clientId : string, 
 clientSecret : string 
} 

Body:

{ 
“startDate”: “<YYYY-MM-DD>”, 
“endDate”: “<YYYY-MM-DD>”, 
"dimensions": ["campaign_name", "country", "publisher_app_bundle"], 
"measures": ["impressions", "clicks", "installs", "media_cost"], 
"filters": 
 { 
 "os": ["Android"] 
 } 
} 

Request field details:

Request Field Value Mandatory
Header Authorization The token generated in the Authentication API response. Yes
Body startDate The start date for the report in the YYYY-MM-DD format. Yes
Body endDate The end date for the report in the YYYY-MM-DD format. Yes
Body dimensions The name of the Dimension you want to include in the report. Find Dimensions based on your end points. No
Body measures The name of the Measures you want to include in the report. Find Measures based on your end points. No
Body filters Add array values to the Dimensions if any. No

Sample POST response

{ 
 "status": "SUCCESS",
 "code": 200,
 "data": {
 "reportID": "<string>",
 "report_status": "available",
 "report_message": "Report available for download."
 }
 "message": "Report processed successfully"
} 

Response field details:

Field Description
status
  • The status of the API call.
code
  • The code for the status.
    • 200: SUCCESS
    • 500: ERROR
    • 400: Bad Request
data
  • Provides report details
reportID
  • Unique ID for each query
reportStatus
  • The status of the request.
    • SUBMITTED: Query successfully submitted.
    • FAILED: Query failed.
message
  • Final message for the confirmation of the status of the API call

cURL request

curl --location --request POST 'https://api.cdr.inmobi.com/api/v3/reports/network' \
--header 'Authorization: <YOUR-AUTH-TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{ "startDate": "<START_DATE>",
"endDate": "<END_DATE>", "dimensions": ["<DIMENSION_NAME>"], "measures": ["<MEASURE_NAME>"], "filters": 
{"<DIMENSION_NAME>": ["<DIMENSION_VALUE>", "<DIMENSION_VALUE>"]}
}'

You can also call the Report Creation API using the following cURL request:

Step 3: Call the Check Report Status API.

You can check the status of the report you called using the Report Creation API. You can call the API using a GET or cURL request.

Sample GET request

GET URL: https://api.cdr.inmobi.com/api/v3/reports//status

Header:

{
`Authorization: YOUR_TOKEN`
}

Request field details:

Request Field Value Mandatory
Path Variable (in GET URL) reportID The ID of the report Yes
Header Authorization The token generated in the Authentication API response. Yes

Sample response

{
"status": "SUCCESS",
"code": 200,
"data":
 {
 "reportStatus": "report.status.available",
 "reportStatusDescription": "Report available for download.",
 "message": "Request processed successfully"
 }
}

Response field details:

Field Description
status
  • The status of the API call.
code
  • The code for the status.
    • 200: SUCCESS
    • 500: ERROR
    • 400: Bad Request
data
  • Provides authorization token and validity details
reportStatus
  • The status of the request.
    • Available: The report ran successfully and available to download
    • Running: The report generation is in process
    • submitted: query successfully submitted by the user
    • failed: query failed
reportStatusDescription
  • Shows report status description.
message
  • Final message for the confirmation of the status of the API call

cURL

curl --location --request GET 'https://api.cdr.inmobi.com/api/v3/reports/<YOUR-REPORT-ID>/status' \
--header 'Authorization: <YOUR-AUTH-TOKEN>'

You can also call the Check Report Status API using the following cURL request:

Step 4: Call Report Download API

You can download the final CostAPI report using a GET or cURL request.

Sample GET Request

GET URL: https://api.cdr.inmobi.com/api/v3/reports//download

Header:

{
`Authorization: YOUR_TOKEN`
}

Request field details:

Request Field Value Mandatory
Path Variable (in GET URL) reportID The ID of the report Yes
Header Authorization The token generated in the Authentication API response. Yes

Sample GET Response

The CSV file of the report starts downloading on your system.

cURL Request

You can also call the Download Report API using the following cURL request:

curl --location --request GET 'https://api.cdr.inmobi.com/api/v3/reports/<YOUR-REPORT-ID>/status' \
--header 'Authorization: <YOUR-AUTH-TOKEN>'

Common API Errors

You may get the following errors during an API call. Based on the description provided, you can troubleshoot the errors.

Error Description
client.cred.invalid The provided credentials are invalid. Check your clientId and clientSecret and try again.
token.generation.failed There is an error while generating the token. Try again later.
authentication.token.invalid The provided token is invalid. Regenerate the token and try again.
request.date.format_invalid The startDate and/or endDate parameter in your request have an invalid format. Update the format for startDate and/or endDate field and try again.
client.bad_request The data can be fetched only for the last 90 days.
client.bad_request The start date must be less than or equal to the end date.
client.bad_request Check the startDate and endDate of the report and try again.
client.bad_request Use the v3 API for custom dimensions and measures.
client.bad_request Measures are not supported in filters. Invalid filters found: [filter_name].
client.bad_request Invalid attributes found: Dimensions: [dimension_name], Measures: [measure_name], Filters: [filter_name].
reportId.missing The report you are trying to access doesn't exist. Check the report ID and try again.

On This Page

Last Updated on: 16 Oct, 2024