# Device API

## registerDevice

`POST` `https://api.pushwoosh.com/json/1.3/registerDevice`

Called internally from the SDK. Registers device for the application.

##### Request headers

| Name          | Required | Value         | Description                                                |
|---------------|----------|---------------|------------------------------------------------------------|
| Authorization | Yes      | Token `XXXX`  | [API Device Token](/developer/api-reference/api-access-token/#device-api-token) to access Device API. Replace `XXXX` with your actual Device API token. |


##### Request body

| Name                                           | Type    | Description                                                                                         |
| ---------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------- |
| application\*  | string  | [Pushwoosh application code](/developer/api-reference/api-identifiers/#application-code)                                                                      |
| push\_token                                    | string  | [Push token](/developer/api-reference/api-identifiers/#push-token) for the device.                                                                          |
| language                                       | string  | Language locale of the device. Must be a lowercase two-letter code according to ISO-639-1 standard. |
| hwid\*         | string  | Unique string to identify the device (IDFV on iOS, randomly generated value on Android). [Learn more](/developer/api-reference/api-identifiers/#hardware-id)         |
| timezone                                       | integer | Timezone offset in seconds for the device.                                                          |
| device\_type\* | integer | [Device type](/developer/api-reference/api-identifiers/#device-type). See possible values below.                                                             |
| email                                          | string  | Email address to register (use for email users instead of HWID and push token).                     |
| tags                                           | object  | Tag values to assign to the device registered.                                                      |

<Tabs>
<TabItem label="200">
```json
{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}
```
</TabItem>
</Tabs>

```json title="Example"
{
  "request": {
    "application": "XXXXX-XXXXX",        // required. Pushwoosh application code
    "push_token": "dec301908b9ba8XXXXX57a58e40f96f5XXXXX2068674f5XXXXa25cdc250a2a41", // optional.
    "hwid": "1CA6XXXXX-8DAC-XXXXX-XXXXX-B756288B6D3C",                                   // required. Hardware device ID
    "idfa": "AEBE52E7-0XXXXX-455A-XXXXX-E57283966239",                                   // optional.
    "timezone": 3600,                    // optional. Offset in seconds
    "device_type": 1,                    // required. See the possible values below. For emails, 
                                         //           use the "emails" params as described below.
    "email": "email_address@domain.com", // use instead of "hwid" and "push_token" to register
                                         //           the email address for your email project
    "language": "en",                    // optional. ISO 639-1|639-2 language code
    "userId": "Alex",                    // optional.
    "tags": {                            // optional. Tag values to set for the device registered 
      "StringTag": "string value",
      "IntegerTag": 42,
      "ListTag": ["string1", "string2"], // sets the list of values for Tags of List type
      "DateTag": "2024-10-02 22:11",     // note the time should be in UTC
      "BooleanTag": true                 // valid values are: true, false
    },

    // system tags, optionals
    "app_version": "1.2.3", 
    "device_model": "Samsung SM-G355H",
    "os_version": "2.3",

    // optional encryption keys for chrome/firefox
    "public_key": "BNmDO4BTKEMJqaqprTf7t/HBXXXXX/orcXXXXX/scS5CFP6XXXXXHI1/GgRQD8c4kTxTEEF0quvIUiLQqoBY0/Qo=",
    "auth_token": "RlRmCXXXXX/s7XXXXXjKFzoQ==",
 
    // optional FCM keys for Chrome (for XMPP)
    "fcm_token": "BNmDO4BTKEMJXXXXXprTf7t/XXXXXBQ/orXXXXXc/scS5CFP6zhQGIHI1/GgRQD8c4kTxTEEF0quvIUiLQqoBY0/Qo=",
    "fcm_push_set": "RlXXXXXGM/s7XXXXXjKFzoQ=="
  }
}
```

Possible device types:

* 1 – iOS
* 3 – Android
* 7 – Mac OS X
* 8 – Windows
* 9 – Amazon
* 10 – Safari
* 11 – Chrome
* 12 – Firefox
* 13 – Internet Explorer
* 14 – Email
* 16 – Baidu Android
* 17 – Huawei
* 18 – SMS
* 20 – Web
* 21 – WhatsApp
* 22 – Line
* 23 – Kakao Talk
* 24 – Telegram
* 25 – Apple Wallet
* 26 – Google Wallet
* 27 – Viber

### Registering email devices 
To **register a email subscriber** for your app, send the `"email": "email_address@domain.com"` param in your `/registerDevice` or [`/registerEmail`](/developer/api-reference/email-api#registeremail) request as follows:

##### Request example 
```json
{
  "request":{
    "application": "XXXXX-XXXXX",        // required. Pushwoosh application code
    "email": "email_address@domain.com", // required. Email address to register for your email project
    "language": "en",                    // optional. ISO 639-1|639-2 language code
    "userId": "Alex",                    // optional.
    "tags": {                            // optional. Tag values to set for the device registered 
      "StringTag": "string value",
      "IntegerTag": 42,
      "ListTag": ["string1", "string2"], // sets the list of values for Tags of List type
      "DateTag": "2024-10-02 22:11",     // note the time should be in UTC
      "BooleanTag": true                 // valid values are: true, false
    }
  }
}
```

### Registering WhatsApp devices
To register a WhatsApp device for your app, follow these guidelines:

- **hwid**: Ensure this field includes the whatsapp: prefix followed by the phone number in E.164 format (e.g., whatsapp:+0000000000). The phone number must be valid, which Pushwoosh will verify.

- **Push token**: A push token is not required, as hwid will automatically function as the push token.

- **device_type**: Set this field to 21 to specify WhatsApp as the platform.

##### Request example
```json
{ 
  "request": {
    "application": "XXXXX-XXXXX",        // required. Pushwoosh application code
    "hwid": "whatsapp:+0000000000",      // required. WhatsApp prefix and valid phone number
    "timezone": 3600,                    // optional. Time offset in seconds
    "device_type": 21,                   // required. WhatsApp device type is 21
    "language": "en",                    // optional. ISO 639-1|639-2 language code
    "userId": "Alex",                    // optional. User identifier
    "tags": {                            // optional. Tag values for custom segmentation
      "StringTag": "string value",
      "IntegerTag": 42,
      "ListTag": ["string1", "string2"],
      "DateTag": "2024-10-02 22:11",     // UTC format
      "BooleanTag": true  
    },
    "app_version": "1.2.3",              // optional. Application version
    "device_model": "Samsung SM-G355H",  // optional. Device model
    "os_version": "2.3"                  // optional. Operating system version
  }
}
```

### Registering SMS devices
To register an SMS device for your app, follow these guidelines:

- **hwid**: Ensure this field includes the phone number in E.164 format (e.g., +0000000000). The phone number must be valid, which Pushwoosh will verify.

- **Push token**: A push token is not required, as hwid will automatically function as the push token.

- **device_type**: Set this required field to 18 to designate SMS as the platform.

##### Request example
```json 
{  
   "request": {
      "application": "XXXXX-XXXXX",           // required. Pushwoosh application code
      "hwid": "+0000000000",                  // required. Valid phone number in E.164 format
      "timezone": 3600,                       // optional. Time offset in seconds
      "device_type": 18,                      // required. SMS device type is 18
      "language": "en",                       // optional. ISO 639-1|639-2 language code
      "userId": "Alex",                       // optional. User identifier
      "tags": {                               // optional. Tag values for custom segmentation
           "StringTag": "string value",
           "IntegerTag": 42,
           "ListTag": ["string1", "string2"],
           "DateTag": "2024-10-02 22:11",     // UTC format
           "BooleanTag": true  
      },
      "app_version": "1.2.3",                 // optional. Application version
      "device_model": "Samsung SM-G355H",     // optional. Device model
      "os_version": "2.3"                     // optional. Operating system version
   }
}
```

**Status codes**:

| HTTP Status code | status\_code | Description                                        |
| ---------------- | ------------ | -------------------------------------------------- |
| 200              | 200          | Device successfully registered                     |
| 200              | 210          | Argument error. See status\_message for more info. |
| 400              | N/A          | Malformed request string                           |
| 500              | 500          | Internal error                                     |



## unregisterDevice

`POST` `https://api.pushwoosh.com/json/1.3/unregisterDevice`

Removes the device's push token. The unregistered device is still counted in Total Devices and can be reached with In-Apps. Called internally from the SDK.

##### Request headers

| Name          | Required | Value         | Description                                                |
|---------------|----------|---------------|------------------------------------------------------------|
| Authorization | Yes      | Token `XXXX`  | [API Device Token](/developer/api-reference/api-access-token/#device-api-token) to access Device API. Replace `XXXX` with your actual Device API token. |

##### Request body

| Name                                          | Type   | Description                                         |
| --------------------------------------------- | ------ | --------------------------------------------------- |
| application\* | string | [Pushwoosh application code](/developer/api-reference/api-identifiers/#application-code)                        |
| hwid\*        | string | [Hardware device ID](/developer/api-reference/api-identifiers/#hardware-id) used in /registerDevice request.   |

<Tabs>
<TabItem label="200">
```json
{
    "status_code": 200,
    "status_message": "OK",
    "response": null
}
```
</TabItem>
</Tabs>

```json title="Example"
{
  "request": {
    "application": "XXXXX-XXXXX",              // required. Pushwoosh application code
    "hwid": "8f65b16XXXXXe7a6beceXXXXX530fb2"  // required. Hardware device ID used in /registerDevice API 
  }
}
```

<Aside type="note">
For emails call [`/deleteEmail`](/developer/api-reference/email-api/#deleteemail).
</Aside>

**Status codes**:

| HTTP Status code | status\_code | Description                                        |
| ---------------- | ------------ | -------------------------------------------------- |
| 200              | 200          | Device successfully unsubscribed                   |
| 200              | 210          | Argument error. See status\_message for more info. |
| 400              | N/A          | Malformed request string                           |
| 500              | 500          | Internal error                                     |



## deleteDevice

`POST` `https://api.pushwoosh.com/api/v2/device-api/deleteDevice`

Deletes a device and all its associated data identified by the specified [HWID](/developer/api-reference/api-identifiers/#hardware-id) within the application. Unlike [`/unregisterDevice`](/developer/api-reference/device-api/#unregisterdevice), which only removes the push token and keeps the device record, `/deleteDevice` fully removes the device. The request is processed asynchronously, and the endpoint returns `200 OK` as soon as the delete request has been accepted for processing.

#### Request headers

| Name          | Required | Value            | Description                                                |
|---------------|----------|------------------|------------------------------------------------------------|
| Authorization | Yes      | Token `XXXX`     | [API Device Token](/developer/api-reference/api-access-token/#device-api-token) to access Device API. Replace `XXXX` with your actual Device API token. |
| Content-Type  | Yes      | application/json |                                                            |

#### Request body

| Name        | Required | Type   | Description                                                                                                 |
| ----------- | -------- | ------ | ----------------------------------------------------------------------------------------------------------- |
| application | Yes      | string | [Pushwoosh application code](/developer/api-reference/api-identifiers/#application-code)                    |
| hwid        | Yes      | string | [Hardware device ID](/developer/api-reference/api-identifiers/#hardware-id) of the device to delete.        |


#### Request example

```json
{
  "application": "XXXXX-XXXXX",                 // required. Pushwoosh application code
  "hwid": "8f65b16df378e7a6bece9614e1530fb2"    // required. Hardware device ID of the device to delete
}
```

#### Response example

<Tabs>
<TabItem label="200">
```json
{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}
```
</TabItem>
</Tabs>

##### Status codes

| HTTP Status code | status\_code | Description                                        |
| ---------------- | ------------ | -------------------------------------------------- |
| 200              | 200          | Delete request accepted                            |
| 200              | 210          | Argument error. See status\_message for more info. |
| 400              | N/A          | Malformed request string                           |
| 401              | N/A          | Missing or invalid Authorization token             |
| 500              | 500          | Internal error                                     |



## setTags

`POST` `https://api.pushwoosh.com/json/1.3/setTags`

Sets tags values for the device. Called from the SDK.

##### Request headers

| Name          | Required | Value         | Description                                                |
|---------------|----------|---------------|------------------------------------------------------------|
| Authorization | Yes      | Token `XXXX`  | [API Device Token](/developer/api-reference/api-access-token/#device-api-token) to access Device API. Replace `XXXX` with your actual Device API token. |

##### Request body

| Name                                          | Type   | Description                                                  |
| --------------------------------------------- | ------ | ------------------------------------------------------------ |
| application\* | string | [Pushwoosh application code](/developer/api-reference/api-identifiers/#application-code)                                 |
| hwid\*        | string | [Hardware device ID](/developer/api-reference/api-identifiers/#hardware-id) used in /registerDevice request.          |
| tags\*        | object | JSON object of tags to set, send "null" to remove the value. |

<Tabs>
<TabItem label="200">
```json
{
   "status_code": 200,
   "status_message": "OK",
   "response": null
}
```
</TabItem>
</Tabs>

<Aside type="note">
The method is called from the SDK. It is possible to call it remotely from your backend, however you need to maintain an up-to-date database of hwid’s on the backend side.
</Aside>

```json title="Example"
{
  "request":{
    "application": "XXXXX-XXXXX",               // required. Pushwoosh application code
    "hwid": "8f65b16XXXXXe7a6becXXXXXe1530fb2", // required. Hardware device ID used in /registerDevice API
    "tags": {                                   // required.
      "StringTag": "string value",
      "IntegerTag": 42,
      "ListTag": ["string1", "string2"],        // sets the list of values for Tags of List type
      "DateTag": "2024-10-02 22:11",            // note the time is in UTC
      "BooleanTag": true                        // valid values are - true, false
    }  
  }
}
```

### Increment Integer tag values

To **increment** a value of the Integer Tag, use the `operation` parameter with the "increment" value as follows:

```json
{
  "request":{
    "application": "12345-67890",                   // required. Pushwoosh application code
    "hwid": "21AB7628-XXXX-XXXX-CCC0-PO287CS24CA4", // required. hardware device ID used in /registerDevice API
    "tags": {                                       // required.
      "Level": {                                    // Tag name
        "operation": "increment",                   // overwrites the integer tag in increments of the following value 
        "value": 1                                  // increment for the tag value
      }  
    }  
  }
}
```

### Decrement Integer tag values

To **decrement**, use the negative numbers as the value for the "increment" operation (-1, -2, -3,-n):

```json
{
  "request":{
    "application": "12345-67890",                   // required. Pushwoosh application code
    "hwid": "21AB7628-XXXX-XXXX-CCC0-PO287CS24CA4", // required. Hardware device ID used in /registerDevice API
    "tags": {                                       // required
      "Level": {                                    // Tag name
        "operation": "increment",                   // overwrites the integer tag in decrement of the following value 
        "value": -1                                 // decrement for the tag value
      }  
    }  
  }
}
```

### Append List tag values

To **extend the List Tag with new values**, use the `operation` parameter with the "append" value as follows:

```json title="Example"
{
  "request": {
    "hwid": "3d124a79XXXXf189XXXX7dfd9XXXXafd", // required. Hardware device ID used in /registerDevice API
    "application": "6XXXX-XXXX3",               // required. Pushwoosh application code
    "tags": {                                   // required.
      "ListTag": {                              // Tag name
        "operation": "append",                  // appends following values to the Tag's list of values
        "value": [                              // values to append
          "tag2",
          "tag3"
        ]
      }
    }
  }
}
```

### Remove List tag values

To remove some values from the List Tag, use the "remove" operation as follows:

```json
{
  "request":{
    "application": "12345-67890",                   // required. Pushwoosh application code
    "hwid": "21AB7628-XXXX-XXXX-CCC0-PO287CS24CA4", // required. Hardware device ID used in /registerDevice API
    "tags": {                                       // required.
      "In-App Product": {                           // Tag name
        "operation": "remove",                      // removes the following values from the list tag
        "value": "outwear_02"                       // value or values to remove
      }
    }  
  }
}
```

### Set tags by UserID

To set tags for all devices associated to a particular [User ID](/developer/api-reference/api-identifiers/#user-id), use the "userId" parameter instead of "hwid".

<Aside type="caution">
Make sure the tag you're setting values for is [user-specific](/developer/guides/audience-and-segmentation/tags/#tag-scope-general-vs-user-specific).
</Aside>

```json title="Example"
{
  "request":{
    "application": "AAAAA-BBBBB", // Pushwoosh app code
    "userId": "some_user",        // user ID you'd like to set tags for 
    "tags": {                     // tags and values to set
      "Language": "es"
    }  
  }
}
```

<Aside type="note">
For emails call [`/setEmailTags`](/developer/api-reference/email-api/#setemailtags).
</Aside>

**Status codes:**

| HTTP Status code | status\_code | Description                                        |
| ---------------- | ------------ | -------------------------------------------------- |
| 200              | 200          | Tags have been successfully set                    |
| 200              | 210          | Argument error. See status\_message for more info. |
| 400              | N/A          | Malformed request string                           |
| 500              | 500          | Internal error                                     |


## getTags

`POST` `https://api.pushwoosh.com/json/1.3/getTags`

Retrieves a list of tags with corresponding values for the specific device.

##### Request headers

| Name          | Required | Value         | Description                                                |
|---------------|----------|---------------|------------------------------------------------------------|
| Authorization | Yes      | Token `XXXX`  | [API Device Token](/developer/api-reference/api-access-token/#device-api-token) to access Device API. Replace `XXXX` with your actual Device API token. |

##### Request body

| Name                                          | Type   | Description                                                                                         |
| --------------------------------------------- | ------ | --------------------------------------------------------------------------------------------------- |
| application\* | string | [Pushwoosh application code](/developer/api-reference/api-identifiers/#application-code)                                                                         |
| userId                                        | string | [User ID](/developer/api-reference/api-identifiers/#user-id) to be used instead of "hwid". If used together with a "hwid", the "hwid" prevails.  |
| hwid                                          | string | [Hardware device ID](/developer/api-reference/api-identifiers/#hardware-id) used in `/registerDevice` request.                                                 |

<Tabs>
<TabItem label="200">
```json
{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "result": {
      "Language": "fr"
    }
  }
}
```
</TabItem>
</Tabs>

```json title="Example"
{
  "request":{
    "application": "XXXXX-XXXXX",   // required. Pushwoosh application code
    "hwid": "HWID",                 // optional. Hardware device ID used in /registerDevice API
    "userId": "USER_ID"             // optional. Can be used instead of "hwid" to retrieve tags for a specific user
  }
}
```

## setBadge

`POST` `https://api.pushwoosh.com/json/1.3/setBadge`

Sends current badge value for a device to Pushwoosh. Called internally from the SDK.

##### Request headers

| Name          | Required | Value         | Description                                                |
|---------------|----------|---------------|------------------------------------------------------------|
| Authorization | Yes      | Token `XXXX`  | [API Device Token](/developer/api-reference/api-access-token/#device-api-token) to access Device API. Replace `XXXX` with your actual Device API token. |

##### Request body

| Name                                          | Type    | Description                                         |
| --------------------------------------------- | ------- | --------------------------------------------------- |
| application\* | string  | [Pushwoosh application code](/developer/api-reference/api-identifiers/#application-code)                         |
| hwid\*        | string  | [Hardware device ID](/developer/api-reference/api-identifiers/#hardware-id) used in /registerDevice request. |
| badge\*       | integer | Current badge on the application.                   |

<Tabs>
<TabItem label="200">
```json
{
  "status_code": 200,
  "status_message": "OK"
}
```
</TabItem>
</Tabs>

```json title="Example"
{
  "request":{
    "application": "XXXXX-XXXXX",               // required. Pushwoosh application code
    "hwid": "8f65b16dXXXXe7a6XXXX9614XXXX0fb2", // required. Hardware device ID used in /registerDevice API
    "badge": 4                                  // required. Current badge on the application
  }
}
```

Called from the SDK internally. Sends current badge value for a device to Pushwoosh. This happens internally when app changes badge value on iOS device. Allows auto-incrementing badges to work properly.

<Aside type="caution">
This method **IS NOT** used to update the badge value on the device. Instead please use [`/createMessage`](/developer/api-reference/messages-api/#createmessage) request with the `"ios_badges"` parameter.
</Aside>



## applicationOpen

`POST` `https://api.pushwoosh.com/json/1.3/applicationOpen`

Registers an app open event. Called internally from the SDK.

##### Request headers

| Name          | Required | Value         | Description                                                |
|---------------|----------|---------------|------------------------------------------------------------|
| Authorization | Yes      | Token `XXXX`  | [API Device Token](/developer/api-reference/api-access-token/#device-api-token) to access Device API. Replace `XXXX` with your actual Device API token. |

##### Request body

| Name                                          | Type   | Description                                         |
| --------------------------------------------- | ------ | --------------------------------------------------- |
| application\* | string | [Pushwoosh application code](/developer/api-reference/api-identifiers/#application-code)                        |
| hwid\*        | string | [Hardware device ID](/developer/api-reference/api-identifiers/#hardware-id) used in `/registerDevice` request. |

<Tabs>
<TabItem label="200">
```json
{
  "status_code": 200,
  "status_message": "OK"
}
```
</TabItem>
</Tabs>

```json title="Example"
{
  "request": {
    "application": "XXXXX-XXXXX",              // required. Pushwoosh application code
    "hwid": "8f65b16dXXXXe7a6XXXX9614eXXXXfb2" // required. Hardware device ID used in /registerDevice API    
  }
}
```



## pushStat

`POST` `https://api.pushwoosh.com/json/1.3/pushStat`

Registers a push open event. Called internally from the SDK.

##### Request headers

| Name          | Required | Value         | Description                                                |
|---------------|----------|---------------|------------------------------------------------------------|
| Authorization | Yes      | Token `XXXX`  | [API Device Token](/developer/api-reference/api-access-token/#device-api-token) to access Device API. Replace `XXXX` with your actual Device API token. |
##### Request body

| Name                                          | Type   | Description                                                                 |
| --------------------------------------------- | ------ | --------------------------------------------------------------------------- |
| application\* | string | [Pushwoosh application code](/developer/api-reference/api-identifiers/#application-code)                                                |
| hwid\*        | string | [Hardware device ID](/developer/api-reference/api-identifiers/#hardware-id) used in /registerDevice request.                         |
| userId                                        | string | [User ID](/developer/api-reference/api-identifiers/#user-id) to associate with the push open event.                          |
| hash                                          | string | Hash tag received in push notification ("p" parameter of the push payload). |

<Tabs>
<TabItem label="200">
```json
{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}
```
</TabItem>
</Tabs>

```json title="Example"
{
  "request": {
    "application": "XXXXX-XXXXX",               // required. Pushwoosh application code
    "hwid": "8f65b16dfXXXX7a6beXXXX14e1530fb2", // required. Hardware device ID used in /registerDevice API 
    "userId": "USER012345",                     // optional. The user id to associate with the push open event 
    "hash": "HASH_TAG"                          // optional. Hash tag received in push notification
                                                //           ("p" parameter in the push payload)
  }
}
```


## messageDeliveryEvent

`POST` `https://api.pushwoosh.com/json/1.3/messageDeliveryEvent`

Registers push delivery event for the device. Called internally from the SDK.

##### Request headers

| Name          | Required | Value         | Description                                                |
|---------------|----------|---------------|------------------------------------------------------------|
| Authorization | Yes      | Token `XXXX`  | [API Device Token](/developer/api-reference/api-access-token/#device-api-token) to access Device API. Replace `XXXX` with your actual Device API token. |

##### Request body

| Name                                          | Type   | Description                                                                 |
| --------------------------------------------- | ------ | --------------------------------------------------------------------------- |
| application\* | string | [Pushwoosh application code](/developer/api-reference/api-identifiers/#application-code)                                                |
| hwid\*        | string | [Hardware device ID](/developer/api-reference/api-identifiers/#hardware-id) used in `/registerDevice` request.                         |
| hash                                          | string | Hash tag received in push notification ("p" parameter of the push payload). |

<Tabs>
<TabItem label="200">
```json
{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}
```
</TabItem>
</Tabs>

```json title="Example"
 {
  "request": {
    "application": "XXXXX-XXXXX",               // required. Pushwoosh application code
    "hwid": "8f65b16dfXXXX7a6bece9XXXX1530fb2", // required. Hardware device ID used in /registerDevice API
    "hash": "HASH_TAG"                          // optional. Hash tag received in push notification
                                                //           ("p" parameter in the push payload)
  }
}
```