• iOS
  • Android
  • Windows
  • Cordova
  • Web
  • Unity
  • Adobe Air
  • Dashboard
  • API
  • Guides
  • FAQ
  • API > Campaigns API

    POST - Create campaign

    The Campaigns API is made for 1-to-many interactions. Use it if none of the above examples fit your use case. It allows you to target a large audience or users. See here to know more.

    You can use the Campaigns API to send generic/optional notifications. Here are a few examples:

    • Medias: Breaking news, interest based notifications, etc.
    • E-commerce: Flash sales, abandoned cart reminder, etc.
    • Fitness: Workout reminders, subscription offers, etc.

    Request structure

    The create endpoint allows you to create push campaigns and target all your userbase, your own segments (attributes, events) or to segments generated by Batch (country/language, dormant users, app version, etc).

    Route

    The campaigns API exposes a POST create endpoint at: https://api.batch.com/1.1/BATCH_API_KEY/campaigns/create

    Here are examples of valid cURL, PHP or Python requests syntax:

    curl -X POST "https://api.batch.com/1.1/BATCH_API_KEY/campaigns/create" \
    -H "Content-Type: application/json" \
    -H "X-Authorization: BATCH_REST_API_KEY" \
    -d '{
        "name": "Test Campaign",
        "live": true,
        "push_time": "now",
        "messages": [{
            "language": "en",
            "body": "Hello!"
        }]
    }'
    
    use GuzzleHttp\Client;
    $client = new Client();
    $response = $client->request("POST", "https://api.batch.com/1.1/BATCH_API_KEY/campaigns/create", [
        "headers" => [
            "Content-Type" => "application/json",
            "X-Authorization" => "BATCH_REST_API_KEY"
        ],
        "json" => [
            "name" => "Test Campaign",
            "live" => true,
            "push_time" => "now",
            "messages" => [[
                "language" => "en",
                "body" => "Hello!"
            ]]
        ]
    ]);
    
    import requests, json
    response = requests.request("POST", "https://api.batch.com/1.1/BATCH_API_KEY/campaigns/create", 
        headers={
            'Content-Type': 'application/json'
            'X-Authorization': 'BATCH_REST_API_KEY'
        },
        data=json.dumps({
            'name': 'Test Campaign',
            'live': True,
            'push_time': 'now',
            'messages': [{
                'language' => 'en',
                'body' => 'Hello!'
            }]
        })
    )
    

    The BATCH_API_KEY value is either your Live or Dev Batch API key from the settings page of your app within the dashboard (Settings → General). The API key changes push behaviour:

    • Dev API: Only apps built with the Dev API Key will receive notifications.
    • Live API: Depending on the targeting you set for your campaigns, apps built with the Live API key will receive notifications. Apps built with the Dev API key will receive all the notifications you send.

    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 with all the parameters you chose to add for your campaign: campaign name, schedule, recurrency, targeting, messages and more.

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

    {
        "name": "Test Campaign",
        "push_time": "now",
        "live": true,
        "messages": [
            {
                "language": "en",
                "title": "Hello!",
                "body": "How's it going?"
            }
        ]
    }
    

    REQUIRED
    Check out the list of available parameters to create your first push campaign with the API.

    Responses

    Success

    If the POST to the API endpoint is successfull you will receive an HTTP 201 confirmation and a token containing an MD5 hash of the successful campaign creation:

    {"campaign_token":"a0082dc6860938a26280bd3ba927303b"}
    

    Once you get your token, you can use it to update your campaign or check the stats with the API.

    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.

    Failure

    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)
    • 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)