• iOS
  • Android
  • Windows
  • Web
  • Cordova
  • Unity
  • Adobe Air
  • Dashboard
  • API
  • Guides
  • Third Party Integrations
  • FAQ
  • API > Custom Audience API

    GET - List

    The Custom Audience API enables you to create, update, delete and list custom audiences. A custom audience can contain a list of custom user IDs or advertising IDs (GAID or IDFA).

    This is useful to target segments with push notifications or In-App messages, either they are coming from your userbase or created by third-party tools.

    Custom audiences created using the API can be targeted from Batch’s dashboard or the Campaigns API.

    Request structure


    The Custom Audience API exposes a GET endpoint that allows to list custom audiences :


    Here is a valid cURL example:

    curl -H "Content-Type: application/json" -H "X-Authorization: BATCH_REST_API_KEY" -X GET "https://api.batch.com/1.0/BATCH_API_KEY/custom-audience"

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


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

    Get parameters

    Id Description
    from Integer - Optional, Default : 0
    Value used for pagination : it indicates the offset of the first custom audience to be returned. Custom audiences are ordered by creation date (from the most recent to the oldest).
    limit Integer - Optional, Default : 10, Max : 100
    Value that indicates the number of custom audiences to be returned per API call.

    Here is an example of a valid CURL CLI request, which would return 5 custom audiences, starting from the 10th audience :

    curl -H "Content-Type: application/json" -H "X-Authorization: BATCH_REST_API_KEY" -X GET 



    If the GET to the API endpoint is successful you will receive an HTTP 200 confirmation and information about your audiences.

        "custom_audiences": [
                "name": "audience2",
                "type": "custom_ids",
                "description": "The audience2 description",
                "nb_ids": 23764,
                "created": "2018-06-29T14:59:03",
                "updated": "2018-06-29T15:07:32"
                "name": "audience1",
                "type": "advertising_ids",
                "description": "The audience1 description",
                "nb_ids": 16743,
                "created": "2018-06-29T13:12:09",
                "updated": "2018-06-29T13:42:59"


    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)