# Auto-push sending

Version date: 22 May 2025

***

> To authorize, you need to add the header `"Authorization: Bearer ..."` (get your API KEY in your personal account on "Personal" tab).

## Endpoints

* [Create a Auto-push Scheduler](#create-a-auto-push-scheduler)
* [Get a Auto-push Scheduler](#get-a-auto-push-scheduler)

***

## Create a Auto-push Scheduler

**POST** `https://core.push.express/api/b/v2/sched/conversion`

* **Description**: Creates a new auto-push sending. This type of sending is to send a push automatically according to the filters when receiving the events of this task. Scheduler allows tuning the group of receivers via filters. No sending happens if scheduler has no attached pushes.

### Request

```bash
curl --url "https://core.push.express/api/b/v2/sched/conversion"
    --request POST
    --header "content-type: application/json"
    --header "Authorization: Bearer ..."
    --data '
{
  "name": "Name of scheduler",

  "all_apps": false,
  "app_ids_include": [
    123,
    234
  ],
  "app_ids_exclude": [
    345
  ],
  "app_groups_include": [
    1
  ],
  "app_groups_exclude": null,

  "all_countries": false,
  "countries_include": [
    "PT",
    "GB"
  ],
  "countries_exclude": [],

  "all_languages": true,
  "languages_include": [],
  "languages_exclude": [
    "pt"
  ],

  "all_audiences": false,
  "audiences_include": [
    "myaud1_1234",
    "myaud2_1234"
  ],
  "audiences_exclude": [
    "myaud3_1234"
  ],
  "audience_groups_include": [
    11,
    22
  ],
  "audience_groups_exclude": [
    33
  ],

  "event_include": ["install","reg"],
  "event_exclude": ["dep"],
  "delay" : "5d10h30m"
}
```

### Body params:

part 1, name

* `name`, *required, string*. Name of scheduler.

part 2, filters, applications

* `all_apps`, *optional, bool*. Flag to include all applications into sending. If chosen True then `app_ids_include` and `app_groups_include` must be be omitted.
* `app_ids_include`, *optional, list of int*. List of application IDs to include into sending.
* `app_ids_exclude`, *optional, list of int*. List of application IDs to exclude from sending.
* `app_groups_include`, *optional, list of int*. List of application group IDs to include into sending. Make your application groups and manage them [here](https://app.push.express/app/group/)
* `app_groups_exclude`, *optional, list of int*. List of application group IDs to exclude from sending.

> If filters result in an empty set of applications then no scheduler is created. Corresponding `_include` and `_exclude` lists must have no common elements.

part 3, filters, countries

* `all_countries`, *optional, bool*. Flag to include devices with any country into sending. If chosen True then `countries_include` must be be omitted.
* `countries_include`, *optional, list of int*. List of countries to include into sending. Follow iso3166\_1\_alpha2 standard.
* `countries_exclude`, *optional, list of int*. List of countries to exclude from sending. Should be provided only if `all_countries` = true. Follow iso3166\_1\_alpha2 standard.

part 4, filters, languages

* `all_languages`, *optional, bool*. Flag to include devices with any language into sending. If chosen True then `languages_include` must be be omitted.
* `languages_include`, *optional, list of int*. List of languages to include into sending. Follow bcp47\_language\_tag standard.
* `languages_exclude`, *optional, list of int*. List of languages to exclude from sending. Should be provided only if `all_languages` = true. Follow bcp47\_language\_tag standard.

part 5, filters, audiences

In PushExpress audience is a tag that can be attached to devices. Some devices may have no audience.

> Create audiences or segments [here](https://app.push.express/postbacks/offers/), create audience or segment groups [here](https://app.push.express/postbacks/group/)

* `all_audiences`, *optional, bool*. Flag to include all audiences into sending.

If flag is on then only devices with any audience defined will be reached out while devices with no audience will not be reached out.

If one wants to reach out to all devices regardless of audience they should set `all_audiences` to false and omit `audiences_include` with `audience_groups_include`.

If chosen True then `audiences_include` and `audience_groups_include` must be be omitted.

* `audiences_include`, *optional, list of string*. List of audiences to include into sending.
* `audiences_exclude`, *optional, list of int*. List of audiences to exclude from sending.
* `audience_groups_include`, *optional, list of int*. List of audience group IDs to include into sending.
* `audience_groups_exclude`, *optional, list of int*. List of audience group IDs to exclude from sending.

> Corresponding `_include` and `_exclude` lists must have no common elements.

part 6, filters, events

Here you can specify both system events: install, reg, dep, and custom ones. The installation includes all devices, reg - only registered ones, dep - those who have replenished the balance at least once. Custom events can be created [here](https://docs.push.express/api/custom-events). More information about the events is [here](https://docs.push.express/quckstart/custom_events).

* `event_include`, *optional, list of string*. Filters devices which had this event in history. If field is not provided it will be set to `install` i.e. devices are to be chosen regardless of event happened.
* `event_exclude`, *optional, list of string*. Filters devices which did not have this event in history. If field not provided devices are to be chosen regardless of event that did not happen.

part 7, filters, delay

* `delay`, *optional, string*. The time after the event that the push will be sent. The 2d5h20m format. This means sending a push message two days, five hours, and twenty minutes after the event.

### Response:

* 201: New auto-push sending in future created

```json
{"id":12345}
```

* `id`, *int*. ID of newly created auto-push sending.

> No sending happens if scheduler has no attached pushes.

### Next step

To create push, refer to the [Push Creation API](https://docs.push.express/pushes#create-a-push).

To attach push to the scheduler, refer to the [Push Attachment API](https://docs.push.express/pushes#bind-pushes-to-a-scheduler).

***

## Get a Auto-push Scheduler

**GET** `https://core.push.express/api/b/v2/sched/conversion/:sched_id`

* **Description**: Retrieves details of a specific scheduler by its ID.

### Request

```bash
curl --url "https://core.push.express/api/b/v2/sched/conversion/:sched_id"
    --request GET
    --header "Authorization: Bearer ..."
```

***

### Response

* 200

```json
{
  "id": 6841,
  "name": "автопуш рег",
  "app_ids_include": [
    33337,
    35593,
    35897,
    37613,
    37809,
    39026,
    40501
  ],
  "app_ids_exclude": null,
  "app_groups_include": [],
  "app_groups_exclude": [],
  "all_apps": false,
  "all_countries": false,
  "all_languages": false,
  "all_audiences": true,
  "countries_include": null,
  "countries_exclude": null,
  "languages_include": null,
  "languages_exclude": null,
  "event_include": "reg",
  "event_exclude": "",
  "audiences_include": null,
  "audiences_exclude": null,
  "audience_groups_include": [],
  "audience_groups_exclude": [],
  "external_ids": null,
  "delay": "1m",
  "archived": false
}
```

***

## Error handling

All HTTP response codes 2xx SHOULD be considered as success. Requested action was executed successfully.

All HTTP response codes above 400 MUST be considered as error. Requested action failed. Retries policy should be hold according to HTTP specification.

Common API errors:

* 400 - request error. Request has invalid data. Check you request (url, headers, payload)
* 401 is returned when provided API token is invalid. Check your authentification data.
* 403 is returned when access to resource for current user is denied.
* 404 is returned when resource doesn't exist. Check your request data.

  Example: **PUT** `https://core.push.express/api/b/v2/sched/:sched_type/:sched_id/pushes` returns 404 when provided `sched_id` doesn't exist
* All HTTP response codes 5xx - other errors from proxy servers, load balancers, etc. There may or may not have some explanation in response body. These errors always require retries.

**API errors** have `content-type: application/json` header and json response body

Example: `{"error": "validation error: ...", "req_id":"<string>"}`

Response parameters:

* `req_id` *string* is a request ID. It is used by support for problem solving, please, provide it to support if problem emerged.
* `error` object, describing errors.

**Non-API errors** like 502, 504, etc., may or may not include a description.