# Indie Push Notification APIs

Send Indie Push notifications. Check for successfully registered Indie Push IDs. Delete Indie Push Sub IDs.

> **Required:**
>
> You must follow the [Indie Registration
> Guide](/docs/indie-push-notifications/registration) instructions before using
> the APIs listed on this page. Indie Push APIs will not work without first
> following the [Indie Registration
> Guide](/docs/indie-push-notifications/registration)

## Prerequisites

1. **Create a free Native Notify account**

   Create a free [NativeNotify.com](https://dashboard.nativenotify.com/sign-up-one)
   account to get your Native Notify App ID and App Token.

## Send Indie Push Notification API

Use this API to send custom push notifications to individual users you have successfully registered with Native Notify.

Post to this URL:

```bash
https://app.nativenotify.com/api/indie/notification
```

Use this POST body (the server stamps the inbox date itself):

```bash
{
  subId: "unique-user-id-string",
  appId: app-id-number,
  appToken: "app-token-string",
  title: "Push title string",
  message: "Push message string",
}
```

You can also send an optional pushData object with your post. Here's an example:

```bash
{
  ...,
  pushData: '{ "yourProperty": "yourPropertyValue" }'
}
```

### Response

- `201` with the text `Success!` — the push was sent.
- `201` with an explanation and **nothing sent** — the `subId` is not registered to this app (*"That subID is not registered to this app…"*), the account's free trial has ended, or sending is paused for an unpaid invoice (see [Plans & Billing](/docs/billing#what-the-api-returns-while-sending-is-paused)). Check that the body is exactly `Success!` rather than trusting the status alone.
- `400` — no `subId`, a missing `title` / `message`, an invalid rich field, or a payload over Expo's 4 KiB limit (`notification payload exceeds Expo's 4KiB limit`).
- `401` — the `appId` / `appToken` pair does not match an app.

## Get ONE Successfully Registered ID

Use this API to check if you successfully registered your unique user ID with Native Notify.

Run a GET request to this URL:

```bash
https://app.nativenotify.com/api/expo/indie/sub/${app-id}/${app-token}/${unique-user-id}
```

It answers `201` with an array: `[]` when the ID is not registered, or one entry when it is — `{ sub_id, expo_ios_token, ios_apn_token, expo_android_token, android_fcm_token }`, where each token field is an array of that subscriber's registered device tokens. Treat a non-empty array as "registered".

## Get ALL Successfully Registered IDs

Use this API to see a list of all successfully registered unique user IDs.

Run a GET request to this URL:

```bash
https://app.nativenotify.com/api/expo/indie/subs/${app-id}/${app-token}
```

This returns **every** registered subscriber of the app — one entry per unique
user ID, in the same shape as the GET ONE entry above — so you can loop the list
and send to your whole audience. The `X-Total-Count` response header carries the
same number.

Paging is opt-in. Add `take` and/or `skip` only if you want one page at a time:

```bash
https://app.nativenotify.com/api/expo/indie/subs/${app-id}/${app-token}?take=500&skip=0
```

> **If you page, page all the way to the end:**
>
> `take` is honored exactly as you send it — there is no maximum (a value below 1
> counts as 1). Pages are ordered newest registration first. Keep requesting pages
> until you have read `X-Total-Count` rows.

## Unregister a Registered ID

Use this API to delete a registered unique user ID **together with every device registered under it**.

Run a DELETE request to this URL:

```bash
https://app.nativenotify.com/api/app/indie/sub/${app-id}/${app-token}/${unique-user-id}
```

It answers `201` with `delete Indie Sub successful` (also when the ID was not registered) and cannot be undone.

> **Logging one device out? Don't use this:**
>
> One unique user ID can be registered by many devices — a user's phone and tablet, or every member of a group that shares one ID. This DELETE removes all of them. To log out **one** device, call [`unregisterIndieDevice()`](/docs/indie-push-notifications/registration) in the app, which removes only that device's tokens — or `PUT https://app.nativenotify.com/api/unregister/indie/device` with `{ appId, appToken, subID, expoToken, deviceToken }` (the device's Expo push token and native device token). It answers `201` with `Delete Indie Sub successful`, or `400` with `That subID is not registered to this app.`

## API Notes

- Replace "unique-user-id" with the unique user ID you registered with Native Notify.
- Push notifications will NOT work on an emulator/simulator. Push notifications only work on an actual device.
- Send the body as JSON with the `Content-Type: application/json` header. axios sets it for you; `fetch` and server languages such as Python must set it — without it the server cannot read your `appId` / `appToken` and answers `401`.
- The send endpoint also accepts Expo's modern message fields (`subtitle`, `badge`, `ttl`, `expiration`, `interruptionLevel`, `categoryId`, `channelId`, `collapseId`, `contentAvailable`, `mutableContent`, `sound`) — validated up front and passed through to every message delivered through Expo. See [Rich Notifications](/docs/rich-notifications).