Device Registration API

The Device Registration API provides server-side interfaces for registering device tokens and obtaining registration IDs in AppPush.

Get registration_id Using a Token

This API allows a server to register AppPush users with FCM Tokens or APNs Device Tokens and obtain the registration_id generated by EngageLab. After obtaining a registration_id, you can use it for targeted user pushes and device-related APIs such as tags and aliases.

Usage Limits

• Each request can register 1–500 Tokens.
• A request can contain Tokens for only one platform: either a batch of FCM Tokens or a batch of APNs Device Tokens. FCM and APNs Tokens cannot be mixed in the same request.
• Repeated requests with the same application, platform, and Token are idempotent. No duplicate user is created, and the existing registration_id is returned.
• Results are returned in the same order as the Tokens in the request.

Endpoint

              
              POST /v4/devices/token/registration_id

            

The complete request URL consists of the Base URL for the application's data center and the path above. For data center addresses and authentication, see REST API Overview.

Request Headers

              
              Content-Type: application/json
Accept: application/json
Authorization: Basic base64_auth_string

            

Request Parameters

Token Format Requirements

• FCM Token: Must be a non-empty string of no more than 400 characters. Only printable ASCII characters (0x21–0x7E) are allowed. Spaces, line breaks, and leading or trailing whitespace are not allowed.
• APNs Device Token: Must be a non-empty hexadecimal string with an even number of characters and no more than 400 characters. Only 0-9, a-f, and A-F are allowed. Spaces, angle brackets, and other separators are not allowed.

This API validates only the Token format and cannot confirm whether a Token is currently valid. Token validity is determined by the actual FCM or APNs push result.

Android (FCM) Request Example

              
              curl -X POST 'https://pushapi-sgp.engagelab.com/v4/devices/token/registration_id' \
  -u 'appKey:masterSecret' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "platform": "android",
    "tokens": [
      "fcm_token_1",
      "fcm_token_2"
    ]
  }'

            

iOS (APNs) Request Example

              
              curl -X POST 'https://pushapi-sgp.engagelab.com/v4/devices/token/registration_id' \
  -u 'appKey:masterSecret' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "platform": "ios",
    "tokens": [
      "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
    ],
    "apns_production": true
  }'

            

Response Parameters

Individual result codes:

Successful Response Example

For the first registration, is_new is true:

              
              {
  "results": [
    {
      "token": "fcm_token_1",
      "registration_id": "13065ffa4e1a6cc91c3",
      "is_new": true,
      "code": 0
    },
    {
      "token": "fcm_token_2",
      "registration_id": "13065ffa4e1a6cc91c4",
      "is_new": true,
      "code": 0
    }
  ]
}

            

When a previously registered Token is submitted again, the same registration_id is returned and is_new is false:

              
              {
  "results": [
    {
      "token": "fcm_token_1",
      "registration_id": "13065ffa4e1a6cc91c3",
      "is_new": false,
      "code": 0
    }
  ]
}

            

Individual Token Failure Example

If a Token in a batch has an invalid format or fails to register, that item returns an error in code and message, while the other Tokens can still be processed normally. In the following example, the empty Token fails format validation:

              
              {
  "results": [
    {
      "token": "fcm_token_1",
      "registration_id": "13065ffa4e1a6cc91c3",
      "is_new": false,
      "code": 0
    },
    {
      "token": "",
      "is_new": false,
      "code": 21003,
      "message": "invalid fcm token format"
    }
  ]
}

            

Request Failure Example

If the request parameters as a whole are invalid, the API returns HTTP 400. For example, an iOS request that omits apns_production returns:

              
              {
  "error": {
    "code": 21003,
    "message": "apns_production is required for ios"
  }
}

            

Common request errors include:

• platform is not android or ios;
• tokens is empty or contains more than 500 entries;
• an Android request includes apns_production;
• an iOS request omits apns_production.

API Responses

HTTP Status Codes

See HTTP Status Code.

Error Codes

The following table lists request-level error codes. In a batch request, an error for an individual Token is returned in results[].code and results[].message and does not affect the processing of other Tokens.