---
title: "Register a push device"
method: POST
path: "/service_agents/push_devices"
tags: ["Service Agent"]
---

# Register a push device

`POST /service_agents/push_devices`

## Request

- Base URL: `https://api.voipbin.net/v1.0`
- URL: `https://api.voipbin.net/v1.0/service_agents/push_devices`
- Auth: none declared
- TypeScript: <https://skmtc.dev/voipbin/apis/voipbin-api/docs/service_agents/push_devices/post.ts> (a function with typed inputs; its response is checked against the schema)

Registers the push device of the calling agent, or refreshes it when the same token is already
registered. The call is idempotent: both a new and a refreshed device return 200. The device
always belongs to the authenticated agent; the owner is never taken from the request. A token
that was registered by another agent is moved to the calling agent.

The push token is a credential and is never returned in any response.

Returns 400 when the platform is not supported, or when the token is empty or longer than 512 bytes.

## Request body

- object
  - `platform` 'android', required: The platform of the push device. Only `android` is supported.
  - `token` string, required: The push token issued to the app by the platform's push service. 1 to 512 bytes.

## Response `200`

The registered device.

- PushManagerDevice: A push device of the calling agent: one installed app that can receive notifications. The push token is never returned.
  - `id` string, uuid: The device ID returned from POST /service_agents/push_devices.
  - `customer_id` string, uuid: The customer ID of the owner agent, returned from GET /service_agents/me.
  - `agent_id` string, uuid: The owner agent ID, returned from GET /service_agents/me.
  - `platform` 'android': The platform of the push device. Only `android` is supported.
  - `tm_create` string, date-time: When the device was first registered.
  - `tm_update` string, date-time: When the device was last registered or refreshed.

## Other responses

- `400`: Invalid request (INVALID_ARGUMENT).
- `401`: Authentication required (UNAUTHENTICATED).
- `403`: Insufficient permission (PERMISSION_DENIED).
- `500`: Internal error (INTERNAL).

## Changes

- **2026-11-09** `dc2b59b1d86c`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/voipbin/apis/voipbin-api/changes/service_agents/push_devices/post.md)

---

[API](https://skmtc.dev/voipbin/apis/voipbin-api.md) - [All operations](https://skmtc.dev/voipbin/apis/voipbin-api/llms.txt) - [OpenAPI document](https://skmtc.dev/voipbin/apis/voipbin-api/revisions/ae049dcc6c89?raw)