POST - Create request

The Export API is a feature only available on the Enterprise plan.

The Export API allows you to create export requests, get their status and the link to download the file when ready. Exports are performed asynchronously & generated files have a TTL of one month. This page documents the creation endpoint.

Lookback

Some kind of exports are logs of detailed events that happened. Those raw events are not kept forever and will stop being available to export after a while: this is documented in the "Lookback" duration for each event kind. Any data older than the lookback period, even if requested with from, will be missing.
Exports that represent a snapshot of data (such as Userbase) do not have this limitation.

Headers

In order to authenticate with the API, you need to provide your company REST API Key as the value of the X-Authorization header.

Post data

The body of the request must contain a valid JSON payload describing the request to be executed, and information about the concerned user.

Here is a how a complete JSON payload looks like:

{
  "from": "2019-08-14T22:00:00",
  "to": "now",
  "events": ["push_sent", "push_open", "push_error"],
  "ids": ["install_id", "custom_id"]
}

Id	Description
`from`	string - Required 'now' or UTC Date in the 'YYYY-MM-ddTHH:mm:ss' format E.g.`"2019-08-14T22:00:00"`
`to`	string - Required 'now' or UTC Date in the 'YYYY-MM-ddTHH:mm:ss' format E.g.`"2019-08-14T22:00:00"`
`events`	array of strings - Required See version detail for each type.
`ids`	array of strings - Required See version detail for each type. E.g.`["install_id","custom_id","advertising_id"]`

Push Campaign

Lookback

90 days

Event list

Id	Description
`events`	array of string - Required events availables for push campaign E.g.`["push_sent","push_open","push_error"]`

Push Campaign IDs

https://api.batch.com/1.0/BATCH_API_KEY/export/campaign/CAMPAIGN_TOKEN/ids

Here is a valid cURL example:

curl -H "Content-Type: application/json" \
     -H "X-Authorization: BATCH_REST_API_KEY" \
     -X POST -d "@payload.json" "https://api.batch.com/1.0/BATCH_API_KEY/export/campaign/CAMPAIGN_TOKEN/ids"

Output example

install_id;custom_id;advertising_id;event_type
INSTALLATION_ID;CUSTOM_USER_ID;ADVERTISING_ID;push_sent
INSTALLATION_ID;CUSTOM_USER_ID;ADVERTISING_ID;push_opened
INSTALLATION_ID;CUSTOM_USER_ID;ADVERTISING_ID;push_error

Push Campaign Events

https://api.batch.com/1.0/BATCH_API_KEY/export/campaign/CAMPAIGN_TOKEN/events

Here is a valid cURL example:

curl -H "Content-Type: application/json" \
     -H "X-Authorization: BATCH_REST_API_KEY" \
     -X POST -d "@payload.json" "https://api.batch.com/1.0/BATCH_API_KEY/export/campaign/CAMPAIGN_TOKEN/events"

Output example

install_id;custom_id;advertising_id;event_date;event_type
INSTALLATION_ID;CUSTOM_USER_ID;ADVERTISING_ID;2017-07-24T00:00:00;push_sent
INSTALLATION_ID;CUSTOM_USER_ID;ADVERTISING_ID;2017-07-24T09:00:00;push_opened
INSTALLATION_ID;CUSTOM_USER_ID;ADVERTISING_ID;2017-07-24T09:00:00;push_error

Transactional

Lookback

90 days

Event list

Id	Description
`events`	array of string - Required events availables for transactional E.g.`["push_sent","push_open","push_error"]`

Transactional IDs

https://api.batch.com/1.0/BATCH_API_KEY/export/transactional/GROUP_ID/ids

Here is a valid cURL example:

curl -H "Content-Type: application/json" \
     -H "X-Authorization: BATCH_REST_API_KEY" \
     -X POST -d "@payload.json" "https://api.batch.com/1.0/BATCH_API_KEY/export/transactional/GROUP_ID/ids"

Output example

install_id;custom_id;advertising_id;event_type
INSTALLATION_ID;CUSTOM_USER_ID;ADVERTISING_ID;push_sent
INSTALLATION_ID;CUSTOM_USER_ID;ADVERTISING_ID;push_error
INSTALLATION_ID;CUSTOM_USER_ID;ADVERTISING_ID;push_opened

Transactional Events

https://api.batch.com/1.0/BATCH_API_KEY/export/transactional/GROUP_ID/events

Here is a valid cURL example:

curl -H "Content-Type: application/json" \
     -H "X-Authorization: BATCH_REST_API_KEY" \
     -X POST -d "@payload.json" "https://api.batch.com/1.0/BATCH_API_KEY/export/transactional/GROUP_ID/events"

Output example

install_id;custom_id;advertising_id;event_date;event_type;transactional_token
INSTALLATION_ID;CUSTOM_USER_ID;ADVERTISING_ID;2017-07-24T09:00:00;push_sent;5bc1861d86c96c22685a6b6cbcc72
INSTALLATION_ID;CUSTOM_USER_ID;ADVERTISING_ID;2017-07-24T09:00:00;push_error;5bc1861d86c2c22685a6b6cbcc72
INSTALLATION_ID;CUSTOM_USER_ID;ADVERTISING_ID;2017-07-24T09:00:00;push_opened;5bc18616d02c22685a6b6cbcc72

In-app Campaign

Lookback

90 days

Event list

Id	Description
`events`	array of string - Required events availables for in-app campaign E.g.`["inapp_shown","inapp_clicked","inapp_closed"]`

In-app Campaign IDs

https://api.batch.com/1.0/BATCH_API_KEY/export/in-app-campaign/CAMPAIGN_TOKEN/ids

Here is a valid cURL example:

curl -H "Content-Type: application/json" \
     -H "X-Authorization: BATCH_REST_API_KEY" \
     -X POST -d "@payload.json" "https://api.batch.com/1.0/BATCH_API_KEY/export/in-app-campaign/CAMPAIGN_TOKEN/ids"

Output example

install_id;custom_id;advertising_id;event_type
INSTALLATION_ID;CUSTOM_USER_ID;ADVERTISING_ID;inapp_shown
INSTALLATION_ID;CUSTOM_USER_ID;ADVERTISING_ID;inapp_clicked
INSTALLATION_ID;CUSTOM_USER_ID;ADVERTISING_ID;inapp_closed

In-app Campaign Events

https://api.batch.com/1.0/BATCH_API_KEY/export/in-app-campaign/CAMPAIGN_TOKEN/events

Here is a valid cURL example:

curl -H "Content-Type: application/json" \
     -H "X-Authorization: BATCH_REST_API_KEY" \
     -X POST -d "@payload.json" "https://api.batch.com/1.0/BATCH_API_KEY/export/in-app-campaign/CAMPAIGN_TOKEN/events"

Output example

install_id;custom_id;advertising_id;event_date;event_type;cta;cta_position
INSTALLATION_ID;CUSTOM_USER_ID;ADVERTISING_ID;;2017-07-24T00:00:00;inapp_supplied;;
INSTALLATION_ID;CUSTOM_USER_ID;ADVERTISING_ID;2017-07-24T09:00:00;inapp_shown;;
INSTALLATION_ID;CUSTOM_USER_ID;ADVERTISING_ID;2017-07-24T09:00:00;inapp_clicked;batch.CustomAction;1
INSTALLATION_ID;CUSTOM_USER_ID;ADVERTISING_ID;2017-07-24T09:00:00;inapp_clicked;batch.dismiss;1
INSTALLATION_ID;CUSTOM_USER_ID;ADVERTISING_ID;2017-07-24T09:00:00;inapp_clicked;batch.deeplink;0
INSTALLATION_ID;CUSTOM_USER_ID;ADVERTISING_ID;2017-07-24T09:00:00;inapp_closed;;

Reachability

A reachability event is generated when an installation's reachability status changes, meaning a change in one of these attributes:

is_reachable: true if the installation has a push token
is_optin: true if the installation enabled push notifications for the app
has_custom_id : true if the installation is linked to a user profile with a Custom User ID

https://api.batch.com/1.0/BATCH_API_KEY/export/reachability/events

Lookback

90 days

Request

Here is a valid cURL example:

curl -H "Content-Type: application/json" \
     -H "X-Authorization: BATCH_REST_API_KEY" \
     -X POST -d "@payload.json" "https://api.batch.com/1.0/BATCH_API_KEY/export/reachability/events"

The body of the request must contain a valid JSON payload describing the request to be executed, and information about the concerned user.

Here is a how a complete JSON payload looks like:

{
  "from": "2019-08-14T22:00:00",
  "to": "now",
  "ids": ["install_id", "custom_id"]
}

Id	Description
`from`	string - Required 'now' or UTC Date in the 'YYYY-MM-ddTHH:mm:ss' format E.g.`"2019-08-14T22:00:00"`
`to`	string - Required 'now' or UTC Date in the 'YYYY-MM-ddTHH:mm:ss' format E.g.`"2019-08-14T22:00:00"`
`ids`	array of strings - Required See version detail for each type. E.g.`["install_id","custom_id","advertising_id"]`

Output example

install_id;custom_id;advertising_id;event_date;event_type;is_reachable;is_optin;has_custom_id
INSTALLATION_ID;CUSTOM_USER_ID;ADVERTISING_ID;2017-07-24T00:00:00;reachability;true;true;false

Userbase

Lookback

Not applicable

Request

https://api.batch.com/1.0/BATCH_API_KEY/export/userbase

Here is a valid cURL example:

curl -H "Content-Type: application/json" \
     -H "X-Authorization: BATCH_REST_API_KEY" \
     -X POST -d "@payload.json" "https://api.batch.com/1.0/BATCH_API_KEY/export/userbase"

Post data

The body of the request must contain a valid JSON payload describing the request to be executed, and information about the concerned user.

Here is a how a complete JSON payload looks like:

{
  "ids": ["install_id", "custom_id", "advertising_id"],
}

Output example

install_id;custom_id;advertising_id;is_optin_push;install_date;last_start_date;smart_segment
INSTALLATION_ID;CUSTOM_USER_ID;ADVERTISING_ID;true;2017-07-24T09:00:00;2017-07-24T10:00:00;2017-07-24T11:00:00;Engaged

Responses

Success

If the POST to the API endpoint is successful you will receive an HTTP 202 confirmation and a unique request_id representing the request.

{ "requestId": "110e8400-e29b-11d4-b543-446655440000" }

Please keep this token: It will be useful to check the status and get the result of your request.

Failure

If the user in the POST data is currently being processed, the API will return a HTTP 409 Conflict status code.

If the POST data does not meet the API requirements you will receive an actionable error message. Contact us at support@batch.com if you need further support.

AUTHENTICATION_INVALID (Http status code: 401, Error code: 10)
API_MISUSE (Http status code: 403, Error code: 12)
ROUTE_NOT_FOUND (HTTP status code: 404, Error code: 20)
MISSING_PARAMETER (HTTP status code: 400, Error code: 30)
MALFORMED_PARAMETER (HTTP status code: 400, Error code: 31)
MALFORMED_JSON_BODY (HTTP status code: 400, Error code: 32)
SERVER_ERROR (HTTP status code: 500, Error code: 1)
MAINTENANCE_ERROR (HTTP status code: 503, Error code: 2)

Documentation > API > Export API

POST - Create request

Lookback

Headers

Post data

Push Campaign

Lookback

Event list

Push Campaign IDs

Output example

Push Campaign Events

Output example

Transactional

Lookback

Event list

Transactional IDs

Output example

Transactional Events

Output example

In-app Campaign

Lookback

Event list

In-app Campaign IDs

Output example

In-app Campaign Events

Output example

Reachability

Lookback

Request

Output example

Userbase

Lookback

Request

Post data

Output example

Responses

Success

Failure