Support Home > Analytics, Reports & API > Premium Publisher API Postback Triggers

Premium Publisher API Postback Triggers

As a Premium Publisher API user, you can manage your Free App Analytics apps, campaigns, segments, trackers, and postback triggers without ever logging into the Free App Analytics UI. This powerful API offers the same functionality as the UI and is designed to be used in lieu of the Free App Analytics UI.

NOTE: The Premium Publisher API documentation refers to the trigger for a postback as opposed to the postback, itself. The postback is the payload of data sent, the trigger is the event which causes a postback to be fired.

NOTE: The Premium Publisher API and the Free App Analytics Dashboard function independently.

Creating Triggers

  1. Use the Get Template call to retrieve valid postback templates for your app.

    2.  

    Returns a list of Postback Templates that are available for the given appId.

 

GET:

/apps/{appId:int}/postbacks/templates

 

  • curl -D- -X GET -H "Authentication-Key: F5BC0519-8415-4720-925F-35EBCCFAB2ED" \
https://api.kochava.com/apps/17/postbacks/templates
  • GET /apps/17/postbacks/templates HTTP/1.1
Host: api.kochava.com
Authentication-Key: F5BC0519-8415-4720-925F-35EBCCFAB2ED

 

Header:

Field Type Description
Authentication-Key String Your super secret Publisher api key.

 

Success 200:

Field Type Description
data Object[] A list of Template objects.
success Boolean Indicates if the request was successful.
errors String[] A list of errors that occurred while processing the request.
messages String[] A list of information messages about the request.
warnings String[] A list of warnings that occurred while processing the request.
nextToken String A token that is used to retrieve the next page of results, null if not applicable to the request.
previousToken String A token that is used to retrieve the previous page of results, null if not applicable to the request.
meta Object Currently not used.

 

Sample Response:

HTTP/1.1 200 OK
{
    "success":true,
    "meta":null,
    "nextToken":null,
    "previousToken":null,
    "errors":[],
    "warnings":[],
    "messages":[],
    "data":[
        {
            "id":2209,
            "network_id":3,
            "platform":"",
            "name":"mmDSP",
            "context_meta":[
                 {
                      "label":{
                          "name":"App ID",
                          "description":"Provided by mmDSP"
                      },
                      "input":{
                           "id":"cpi_jumptap_app_id",
                           "type":"text",
                           "required":false,
                           "default_value":""
                      }
                 },
                 {
                      "label":{
                           "name":"Fingerprint Lookback",
                           "description":"The lookback window for fingerprint reconciliation."
                      },
                      "input":{
                           "id":"cpi_jumptap_fingerprint_lookback_window",
                           "type":"select",
                           "required":"true",
                           "default_value":"7",
                           "options":[
                                {"value":1,"label":"1 day"},
                                {"value":2,"label":"2 days"},
                                ...
                            ],
                      }
                 },
                 {
                      "label":{
                           "description": "Automatically delay postback delivery for this time duration",
                           "name":"Delivery Delay"
                      },
                      "input":{
                           "type":"select",
                           "options":[
                                {"value":0,"label":"Realtime Delivery"},
                                {"value":30000,"label":"30 Second Delay"},
                                ...
                            ],
                           "default_value":0,
                           "id": "deferred_for"
                      }
                 },
                 {
                      "label":{
                           "description": "Max times to attempt redelivery in event of posting failure",
                           "name":"Retry Attempts"
                      },
                      "input":{
                           "type":"select",
                           "options":[
                                {"value":0,"label":"Do Not Retry"},
                                {"value":1,"label":"1 Attempt"},
                                ...
                            ]
                           "default_value":3,
                           "id": "max_delivery_attempts"
                      }
                 }
            ]
        },
        ...
    ]
}

 

HTTP Status Codes:

Field Description
401 The Authentication Key sent with the request is invalid.
403 The Authentication Key is not authorized to access the requested resource.

 

  1. Create the Trigger.

    2.  

    Creates a new Postback Trigger for the app in the request body.

 

POST:

/postbacks

 

NOTE: The Trigger is the event which causes a postback to be fired.

 

  • curl -D- -X POST -H "Authentication-Key: F5BC0519-8415-4720-925F-35EBCCFAB2ED" \
-H "Content-Type: application/json" \
-d '{"context":{"cpi_openxperformance_fingerprint_lookback_window":"14", \
"cpi_openxperformance_device_id_lookback_window":"25"},"type":"event","app_id":17,"title": \
"OpenX Performance","template_id":2602,"filter_str":"event_name"}' \
https://api.kochava.com/postbacks
  • POST /campaigns HTTP/1.1
Host: api.kochava.com
Authentication-Key: F5BC0519-8415-4720-925F-35EBCCFAB2ED
Content-Type: application/json

{
    "context":{
         "cpi_openxperformance_fingerprint_lookback_window":"14",
         "cpi_openxperformance_device_id_lookback_window":"25"
    },
    "type":"event",
    "app_id":17,
    "title":"OpenX Performance",
    "template_id":2602,
    "filter_str":"event_name"
}

 

Header:

Field Type Description
Authentication-Key String Your super secret Publisher api key.

 

Success 200:

Field Type Description
data Object[] A list with a single Trigger object.
success Boolean Indicates if the request was successful.
errors String[] A list of errors that occurred while processing the request.
messages String[] A list of information messages about the request.
warnings String[] A list of warnings that occurred while processing the request.
nextToken String A token that is used to retrieve the next page of results, null if not applicable to the request.
previousToken String A token that is used to retrieve the previous page of results, null if not applicable to the request.
meta Object Currently not used.

 

Sample Response:

HTTP/1.1 201 OK
{
    "success":true,
    "meta":null,
    "nextToken":null,
    "previousToken":null,
    "errors":[],
    "warnings":[],
    "messages":[],
    "data":[
        {
            "id":54636,
            "app_id":17,
            "type":"event",
            "title":"OpenX Performance",
            "template_id":2602,
            "filter_str": "Purchase".
            "active":false,
            "date_created":1394048564,
            "context":{
                 "cpi_openxperformance_fingerprint_lookback_window":"7",
                 "cpi_openxperformance_device_id_lookback_window":"30"
            }
        }
    ]
}

 

HTTP Status Codes:

Field Description
401 The Authentication Key sent with the request is invalid.
400 The request data has malformed syntax. The request should not be repeated without modifications. A common cause of this is invalid JSON in the request body.
500 An unexpected server side condition occurred that prevented the request from being fulfilled. This issue is on us so you should try your request again shortly to see if the problem has been resolved.

 

  1. Use the Get Trigger method to verify the Trigger.

    2.  

    Returns a single Postback Trigger with the given id.

 

GET:

/apps/{appId:int}/postbacks/{id:int}

 

  • curl -D- -X GET -H "Authentication-Key: F5BC0519-8415-4720-925F-35EBCCFAB2ED" \
https://api.kochava.com/apps/17/postbacks/54636
  • GET /apps/17/postbacks/54636 HTTP/1.1
Host: api.kochava.com
Authentication-Key: F5BC0519-8415-4720-925F-35EBCCFAB2ED

 

Header:

Field Type Description
Authentication-Key String Your super secret Publisher api key.

 

Success 200:

Field Type Description
data Object[] A list with a Trigger object.
success Boolean Indicates if the request was successful.
errors String[] A list of errors that occurred while processing the request.
messages String[] A list of information messages about the request.
warnings String[] A list of warnings that occurred while processing the request.
nextToken String A token that is used to retrieve the next page of results, null if not applicable to the request.
previousToken String A token that is used to retrieve the previous page of results, null if not applicable to the request.
meta Object Currently not used.

 

Sample Response:

HTTP/1.1 200 OK
{
    "success":true,
    "meta":null,
    "nextToken":null,
    "previousToken":null,
    "errors":[],
    "warnings":[],
    "messages":[],
    "data":[
        {
            "id":54636,
            "app_id":17,
            "type":"install",
            "title":"OpenX Performance",
            "template_id":2602,
            "active":false,
            "date_created":1394048564,
            "context":{
                 "cpi_openxperformance_fingerprint_lookback_window":"7",
                 "cpi_openxperformance_device_id_lookback_window":"30"
            }
        }
    ]
}

 

HTTP Status Codes:

Field Description
401 The Authentication Key sent with the request is invalid.
403 The Authentication Key is not authorized to access the requested resource.
404 The requested resource/entity was not found.

Updating Triggers

  1. Use the Get Pending Setup call to retrieve any incomplete Triggers.

    2.  

    Returns a list of Postback Templates that need to be setup for the given appId.

 

GET:

/apps/{appId:int}/postbacks/incomplete

 

  • curl -D- -X GET -H "Authentication-Key: F5BC0519-8415-4720-925F-35EBCCFAB2ED" \
https://api.kochava.com/apps/17/postbacks/incomplete
  • GET /apps/17/postbacks/incomplete HTTP/1.1
Host: api.kochava.com
Authentication-Key: F5BC0519-8415-4720-925F-35EBCCFAB2ED

 

Header:

Field Type Description
Authentication-Key String Your super secret Publisher api key.

 

Success 200:

Field Type Description
data Object[] A list with Postback Template objects.
success Boolean Indicates if the request was successful.
errors String[] A list of errors that occurred while processing the request.
messages String[] A list of information messages about the request.
warnings String[] A list of warnings that occurred while processing the request.
nextToken String A token that is used to retrieve the next page of results, null if not applicable to the request.
previousToken String A token that is used to retrieve the previous page of results, null if not applicable to the request.
meta Object Currently not used.

 

Sample Response:

HTTP/1.1 200 OK
{
    "success":true,
    "meta":null,
    "nextToken":null,
    "previousToken":null,
    "errors":[],
    "warnings":[],
    "messages":[],
    "data":[
        {
            "id":2209,
            "network_id":3,
            "name":"mmDSP",
            "platform":"",
            "context_meta":[
                 {
                      "label":{
                          "name":"App ID",
                          "description":"Provided by mmDSP"
                      },
                      "input":{
                           "id":"cpi_jumptap_app_id",
                           "type":"text",
                           "required":false,
                           "default_value":""
                      }
                 },
                 {
                      "label":{
                           "name":"Fingerprint Lookback",
                           "description":"The lookback window for fingerprint reconciliation."
                      },
                      "input":{
                           "id":"cpi_jumptap_fingerprint_lookback_window",
                           "type":"select",
                           "required":"true",
                           "default_value":"7",
                           "options":[{"value":1,"label":"1 day"},{"value":2,"label":"2 days"}]
                      }
                 }
            ]
        },
        ...
    ]
}

 

HTTP Status Codes:

Field Description
401 The Authentication Key sent with the request is invalid.
403 The Authentication Key is not authorized to access the requested resource.

 

  1. Using the list of incomplete Triggers, update as needed.

    2. NOTE: The Trigger is the event which causes a postback to be fired.

  2. Use the Get Trigger method to verify the Trigger.

Deleting Triggers

Deletes a Postback Trigger with the given ID.

 

Delete:

/postbacks/{id:int}

 

  • curl -D- -X DELETE -H "Authentication-Key: F5BC0519-8415-4720-925F-35EBCCFAB2ED" \
https://api.kochava.com/postbacks/54636
  • DELETE /postbacks/54636 HTTP/1.1
Host: api.kochava.com
Authentication-Key: F5BC0519-8415-4720-925F-35EBCCFAB2ED

 

Header:

Field Type Description
Authentication-Key String Your Publisher API key.

 

Sample Response:

HTTP/1.1 200 OK

 

HTTP Status Codes:

Field Description
401 The Authentication Key sent with the request is invalid.
404 The requested resource/entity was not found.
400 The request data has malformed syntax. The request should not be repeated without modifications. A common cause of this is invalid JSON in the request body.
500 An unexpected server side condition occurred that prevented the request from being fulfilled. This issue is on us so you should try your request again shortly to see if the problem has been resolved.

 
 

Last Modified: Nov 11, 2022 at 1:20 pm