POST - Send

The Transactional API is made for 1-to-1 interactions. It allows you to push a specific user ID or to a group of IDs (device token, install ID or custom user ID).

Use it to send action-oriented or time-sensitive push notifications.

  • Action-oriented notifications: New message, friend request, reached credit limit, user's turn in a game, etc.
  • Time-sentitive notifications: Delivered order, delayed flight, canceled train, etc.

Request structure


The Transactional API exposes a POST send endpoint:

Here is a valid cURL example:

curl -H "Content-Type: application/json" -H "X-Authorization: batch_rest_api_key" -X POST -d "@payload.json" ""

There are two keys you will need to use when calling the API:

batch_rest_api_keyYour company REST API key. It identifies your account and gives you access to our APIs. You can find it in ⚙ Settings → General.
batch_api_keyYour app's API key. It allows you to choose the app you want to push. Each app has a different API key. You can find it in ⚙ Settings → General.

You will find both keys in your dashboard settings: API Keys

Please note Batch manages each platform separately, so you will have to call the API twice with a different Dev/Live API key if you want to target iOS and Android.

Insufficient privileges issue: You may see that error in the REST API key field. This happens because the REST API key is only visible to managers. Make sure the managers of the account share that key with you or ask them to grant you access through the team manager.


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 with all the parameters you chose to add: Targeting, recurrence and more.

Let's see the parameters in detail.

group_idString - Required
Name of your campaign, useful for analytics purposes (see Analytics → Notifications → Transactional) . The group_id shouldn't be unique, it's a key to group your transactional push analytics.
You can use the letters a-z, A-Z, the numbers 0-9, underscores and hyphens.

labelsArray of Strings - Optional - Max. 3 labels
An array containing the label codes you want to attach to your notification. You can use labels to implement frequency capping: make sure that you create the labels before using them and that you fill the "code" field when setting them up. Labels are NOT supported for token recipients.
priorityString - Optional
Defines the priority of your message on iOS (APNS) and Android (GCM) .
Acceptable values include: normal or high .
Default value on iOS is high. Default value on Android is normal.
On Android, use the high priority if you have a messaging/voip app and if you notice delivery issues due to native (Doze) or constructor related (Samsung Smart Manager, etc) energy saving features. High priority Android notifications can drain your user's battery faster since they 'wake up' the device and open a network connection.

time_to_liveInteger - Optional - iOS / Android only
Time, in seconds, after which the notification will be considered as invalid and should not be delivered after attempting to send it at least once, in any case.
By default, all notifications are sent with a TTL of 14 days.
A time_to_live of zero results in attempting to deliver the notification once, and will discard it if the device was offline. Negative values are invalid.

gcm_collapse_keyObject - Optional - Android only
Defines how notifications are managed when an offline device goes online (enabled by default) .
If enabled, the device will only show the most recent notification. If disabled, it will show all the notifications received when the device was offline. You should disable the collapse key if all your notifications matter (E.g. messages, etc) . You can use up to 3 different collapse keys if you want users to get only one notification of each kind when coming online (E.g. marketing messages, alert, etc) .

push_typeString - Optional - Android/iOS. Default: 'alert'
Defines whether notifications should show an alert or be silent to trigger a background action.
Acceptable values are alert and background .
Setting this to 'background' will disable the message and media keys: you will need to remove them from your call.
iOS 13 will ignore silent notifications that don't define a background push_type, even though their custom payload defines a silent push.
On iOS, {\"aps\":{\"content-available\":1}} will automatically be appended to the final payload to wake up the app in the background.

skip_media_checkBoolean - Optional
Batch performs a HEAD request on your media URL to prevent you from sending invalid images, or ones too big.
Checks include but are not limited to a valid Content-Type and Content-Length.
If your server doesn't support this, you can disable these checks by setting this option to true.
Acceptable values include: true or false. Default: false

recipientsObject - Required
An object containing who you want to push, by tokens or Custom IDs.
Supports up to 10,000 push tokens /custom IDs/Install IDs.
At least one of the three parameters must be included.
tokensArray of strings -
An array containing the push tokens to push.
custom_idsArray of strings -
An array containing the custom user IDs to push. Custom IDs are case and whitespace sensitive.
install_idsArray of strings -
An array containing the installation IDs to push. It should be the unmodified installation ID given by the SDK's user module.
advertising_idsArray of strings -
An array containing the advertising IDs to push, IDFA on iOS and GAID on Android. It should be the unmodified advertising ID collected from the device.
messageObject - Required, disallowed when push_type is 'background'
An object containing the message to be delivered.
titleString -
Optional (except for web push) . Title of the push notification. On iOS , the title will only appear on the Apple Watch or in the notification center (since iOS 8) .
E.g.{"title":"Don't give up!"}
bodyString -
Required . Body text of the push notification.
E.g.{"body":"Just keep training, you'll get better"}
mediaObject - Optional - Disallowed when push_type is 'background'
An object containing an icon, a picture, an audio or a video file's URL.
iconString -
Android / Windows 10 - URL of the icon file. The file must be a PNG or JPG image, with a minimum width of 192px and must be hosted on an HTTPS server that responds to HEAD requests. It must not be larger than 5MB.
pictureString -
iOS 10+ / Android / Windows 10 - URL of the picture file. The file must be a PNG or JPG image with a minimum width and height of 300px. It must be hosted on an HTTPS server that correctly responds to HEAD requests and must not be larger than 5MB.
Note: On iOS, make sure your server complies to App Transport Security or that you’ve added the appropriate exceptions in your app and app extension. Here is how a push with an image attachement looks: Example .
audioString -
iOS 10+ - URL of the audio file. The file must be a MP3 file hosted on an HTTPS server that responds to HEAD requests. It must not be larger than 10MB. Here is how a push with an audio attachement looks: Example .
videoString -
iOS 10+ - URL of the video file. The file must be a MPEG-4 file hosted on an HTTPS server that responds to HEAD requests. It must not be larger than 30MB. Here is how a push with a video attachement looks: Example .
deeplinkString - Optional
A URL that points to a specific part of your app (i.e. The news you mention in your notification, etc) . The deeplink URL is usually a link based on a URL scheme that you specify within your app, but can be a relative one if you decide to read it manually.
sandboxBoolean - Optional
Flag specifying whether the APNS sandbox should be used. No effect for Android applications or Custom IDs. Default: false.
wp_templateString - Optional
Flag specifying what Windows Toast template should be used. Use "legacy" if you push Windows 8.1 or Windows Phone 8.1, "generic" for UWP (Windows 10). Default: "legacy".
custom_payloadString - Optional (only available on paid plans)
A JSON string that can contain additional parameters that your application can handle when receiving push notifications if configured to do so. The only forbidden key is com.batch .
Format is {\"x\":\"y\"} .
landingObject - Optional
An object describing the landing message. This will display a landing view allowing you to have complex interactions following a push notification. The landing message object will be described further below

Here is how a minimal and valid JSON payload looks like:

  "group_id": "welcome",
  "recipients": {
    "tokens": ["USER_PUSH_TOKEN"]
  "message": {
    "title": "Hello!",
    "body": "How's it going?"
  "custom_payload": "{\"tag\":\"wake up push\", \"landing_screen\":\"greeting\"}"

The landing message object

A landing message must have the following format.

themeString - Required
The code of the theme to use for your landing view
imageString - Optional
The url of the image to use if the theme contains one
image_descriptionString - Optional
The description of the image used for accessibility purposes
E.g.{"image_description":"Boeing 747"}
tracking_idString - Optional
A tracking ID that you will receive in your application if set
headerString - Optional
The text of the header
titleString - Optional
The text of the title
E.g.{"title":"Update to the latest version!"}
bodyString - Optional
The text of the body
E.g.{"body":"Lots of bug and security fixes"}
actionsArray of objects - Required
A list of actions available in the landing message. The action object will be described further below

If your theme contains the close button, the actions array is not strictly required.

The action object

Each action in the landing message must be defined as follows.

actionString - Required
The action name. Must match with the actions you register in your mobile application. Not strictly required, if null the close action will be used
labelString - Required
The label of the call to action
argsObject - Optional
An object containing arbitrary data that will be passed to your action as is



If the POST to the API endpoint is successful you will receive an HTTP 201 confirmation and a unique token representing the transaction.


Please keep this token: It will be useful to see the list of push tokens you targeted in the debug tool and it will also help in getting faster support.

If you don't receive the notification after a successful POST, make sure your app is not opened in the foreground (iOS) and check again your integration.


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

  • AUTHENTICATION_INVALID (Http status code: 401, Error code: 10)
  • 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)
  • TOO_MANY_REQUESTS (Http status code: 429, Error code: 60)
    If you get a "too many requests" response, please wait for at least 5 seconds before trying again. Further requests might still return this error.


Batch provides a simple debug tool that lets the list of all the targeted push tokens for any given API call. Go to ⚙️ Settings → Debug and input the token generated by the API on each successful call:

Transactional Debug

The advanced analytics view gives you detailed information for a specific transactional push:

  • SENT: The total amount of sent push notifications.
  • NOT FOUND: Number of Custom User ID or installation ID are not linked to any push token.
  • UNDELIVERABLE: Number of push tokens that were flagged as invalid by Apple/Google. Your app may have been uninstalled.
  • ERRORS: Number of APNS/GCM/WNS errors.


Can I do a single API request for both iOS and Android?

Batch manages iOS and Android notifications separately to take advantage of the features that each OS has (e.g. silent push notifications, GCM collapse key, etc). This is why you will need to call the Transactional API once per OS.

Our APIs are asynchronous and respond very fast. Batch will send a push notification, provided that a valid device token is tied to the custom user ID you are targeting. However, if the custom user ID does not exist for the app you targeted, the call will fail silently.

My device doesn't seem to receive any notifications

Here are some suggestions in case your device doesn't receive any notifications:

  • Invalid token: Make sure the device token you are targeting is still valid using the Debug tool (iOS / Android).
  • Wrong environment: On iOS, try adding {"sandbox":true} to your json payload.
  • Invalid custom user ID: Make sure the custom user ID (iOS / Android) was registered by Batch for the OS you are targeting using the Debug tool (iOS / Android).

If you are still having issues receiving notifications, please take a look at our troubleshooting sections (iOS / Android).