Premium Publisher API Postback Triggers

As a Premium Publisher API user, you can manage your Kochava apps, campaigns, segments, trackers, and postback triggers without ever logging into the Kochava UI. This powerful API offers the same functionality as the UI and is designed to be used in lieu of the Kochava 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 Kochava Dashboard function independently.

Creating Triggers

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

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:

Success 200:

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:

2. Create the Trigger.

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.

Example: create an install trigger

Endpoint: POST /postbacks

Headers:

• Authentication-Key: <API_KEY>
• Content-Type: application/json

Body:

{
    "app_id": 87100,
    "type": "install",
    "title": "Install Custom Postback",
    "template_id": 3373,
    "context": { "cpi_mostback_url": "https://example.com/ingest" }
}

Example: create an event trigger

Endpoint: POST /postbacks

Headers:

• Authentication-Key: <API_KEY>
• Content-Type: application/json

Body:

{
    "app_id": 87100,
    "type": "event",
    "title": "Purchase Postback",
    "template_id": 3373,
    "filter_str": "Purchase",
    "context": { "cpi_mostback_url": "https://example.com/ingest" }
}

Example: create a click trigger

Endpoint: POST /postbacks

Headers:

• Authentication-Key: <API_KEY>
• Content-Type: application/json

Body:

{
    "app_id": 87100,
    "type": "click",
    "title": "Click Postback",
    "template_id": 3373,
    "context": { "cpi_mostback_url": "https://example.com/ingest" }
}

Header:

Success 200:

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:

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

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:

Success 200:

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:

List Triggers

Returns a list of all Postback Triggers for the given appId.

Get:

/apps/{appId}/postbacks

GET /apps/87100/postbacks HTTP/1.1
Host: api.kochava.com
Authentication-Key: <API_KEY>

Header:

Update a Trigger

Updates an existing Postback Trigger with the given id.

Patch:

/postbacks/{id}

PATCH /postbacks/689966 HTTP/1.1
Host: api.kochava.com
Authentication-Key: <API_KEY>
Content-Type: application/json

{
    "title": "Install Custom Postback v2",
    "active": true,
    "context": { "cpi_mostback_url": "https://example.com/ingest/v2" }
}

Header:

Required Behavior and Errors

• Destination URL is required in context:
  • Key: context.cpi_<network>_mostback_url (for example: cpi_mostback_url)
• Uniqueness rule per app:
  • Triggers are unique by (template_id, type, filter_str)
  • Only one install or click trigger per template per app
  • Multiple event triggers allowed when filter_str differs
• Duplicate behavior (current):
  • May return HTTP 400 with message like “Duplicate install post-back” even for non-install types
  • Future change: Will return HTTP 409 with a generic duplicate error

Updating Triggers

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

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:

Success 200:

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:

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

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

3. 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:

Sample Response:

HTTP/1.1 200 OK

HTTP Status Codes: