--- title: Subscriber Management API slug: voice-apis/fBsv-subscriber-management-api docTags: createdAt: 2025-10-03T03:49:35.387Z --- ### Introduction This document defines the exotel platform APIs adding, updating, viewing and deleting the subscribers for VoIP Calling. Subscriber is the entity who uses the app with voip calling feature. Subscriber provisioning in exotel can happen in two ways, - Pre-provisioning  The customer pre-configures the client accounts even before the app is installed by the client. - Dynamic provisioning A client account is created after the app is installed by the user and signs-up with the application backend. All the APIs listed in this document are privileged APIs that need API Key and API Token for authentication. API key\:token are generated on sign-up with exotel platform. Please contact *hello\@exotel.in* ***Base URL*** In all the APIs below, replace \ with the following based on the stamp. Stamp info can be found in your Exotel dashboard under the API settings page. - MUM Stamp -  *https\://chaotix.mum1.exotel.in* - SGP Stamp -   *https\://chaotix.apac-sg.exotel.in* ### Subscriber Response Object The subscriber object returned in the APIs is described below | **Parameter** | **Data Type** | **Description** | | ---------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | subscriber\_name | String  | Subscriber name provided while creating the subscriber (Must be unique for a particular tenant)

Maximum supported subscriber name length is 16 bytes and can contain numeric characters. Whitespace characters are not allowed.
e.g. 123456, 9889899999 etc | | status | Enum (active/ inactive) | Whether the subscriber is active or not  | | custom\_field | String | Field to store custom metadata for the subscriber | | date\_created | DateTime | Time at which the subscriber was created | | date\_updated | DateTime | Time at which the subscriber was updated | ### Create Subscriber Token  Access to the exotel platform by ExotelVoiceClient is authenticated using a bearer token - *subsriber\_token*. Clients must obtain this token from their application backend which in turn should fetch it from the exotel platform using the HTTPS endpoint listed here. **Method:**` POST` **Request URL: **`https:///v2/accounts//subscriber-token` **Authorization Type: **`Basic authentication using API key:token` **Request Body Parameters:** | **Parameter** | **Data Type** | **Description** | | ---------------- | ------------- | -------------------------------- | | platform | String | Parameter (Android / iOS) | | device\_id | String | Device id (AndroidID / iOS UDID) | | subscriber\_name | String | Unique subscriber identifier | **Response Type:** `JSON` **Response Code:**  `200 Success` `400 Bad Request, Malformed Parameters` `401 Unauthorized` **Response Body Parameters**: | Parameter | Data Type | Description | | ----------------- | --------- | ------------------------------------------ | | subscriber\_token | String | Token to access exotel platform | | subscriber\_name | String | Subscriber name used for token generation  | **Note** - The Time-to-Live (TTL) for token expiry is as follows: Refresh token expiry: 24 hours Access token expiry: 30 minutes Sample Request ```javascript https:///v2/accounts/exotel13m2/subscriber-token { "platform": "android", "device_id": "2fc4b5912826ad1", "subscriber_name": “archit” } ``` Sample Response ```json { "request_id": "2f97c5e98e1d4c188c483cbfe8092869", "method": "POST", "http_code": 200, “response”: { "code": 200, "error_data": null, "status": "success", “data”: { "subscriber_name": “archit”, "subscriber_token": {  "refresh_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJleG90ZWwiLCJzdWIiOiJBcmNoaXQiLCJpYXQiOjE1NzY2NDc5OTksImV4cCI6MTU3Njc0Nzk5OSwiY2xpZW50X2lkIjoiNUUwNTg2NUUifQ.Hc3umVfFlKIPiJ8R9kcP9o9hE9he51le08rO22u7eqs", "access_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJleG90ZWwiLCJzdWIiOiJBcmNoaXQiLCJpYXQiOjE1NzY2NDc5OTksImV4cCI6MTU3Njc0Nzk5OSwic2NvcGUiOiJ2b2ljZSIsImNsaWVudF9pZCI6IjVFMDU4NjVFIn0.uQd_aHGBIT4XqTPfl-567dmjQrKlmLtPag0KpGB2QMA" } }, } } ``` ### Create Subscribers  API is used for both single or bulk subscriber account creation in exotel platform. **Method: **`POST` **Request Url: **`https:///v2/accounts//subscribers` **Authorization Type: **`Basic authentication using API key:token ` **Request Body Parameters**: | **Parameter** | **Data Type** | **Requirement** | **Description** | | ---------------- | ------------- | --------------- | ------------------------------------------------- | | subscriber\_name | String | Mandatory | Unique Username for the Subscriber | | custom\_field | String | Optional | Field to store custom metadata for the Subscriber | Please note that POST is a bulk operation and the request is actually an array of the above. The maximum number of subscribers which can be created in a single request is 10. **Response Type:** `JSON` **Response Body Parameters: **Returns multipart response for request. Refer *Subscriber Response Object* Sample Request  ```javascript https:///v2/accounts//subscribers {   "subscribers": [     {       "subscriber_name": "bob",       "custom_field": "support"     },     {       "subscriber_name": "nidhi"     },     {       "subscriber_name": "archit"     }   ] } ``` Sample Response ```json { "request_id": "04386e350256448dae83c6db0f749a21", "method": "POST", "http_code": 207, "metadata": { "failed": 0, "success": 3 }, "response": [ { "code": 200, "error_data": null, "status": "success", "data": { "date_created": "2019-11-19T23:14:17+05:30", "date_updated": "2019-11-19T23:14:17+05:30", "subscriber_name": "bob", "status": "active", "custom_field": "support” } }, { "code": 200, "error_data": null, "status": "success", "data": { "date_created": "2019-11-19T23:14:17+05:30", "date_updated": "2019-11-19T23:14:17+05:30", "subscriber_name": "nidhi", "status": "active", "custom_field": null } }, { "code": 200, "error_data": null, "status": "success", "data": { "date_created": "2019-11-19T23:14:18+05:30", "date_updated": "2019-11-19T23:14:18+05:30", "subscriber_name": "archit", "status": "active", "custom_field": null } } ], } ``` ### Update a Subscriber API is used to update the subscriber account parameters after it has been created. Subscriber can be marked inactive for temporary suspension. **Method: **`PUT` **Request Url: **`https:///v2/accounts//subscribers/` **Authorization Type: **Basic authentication using API key\:token  **Request Body Parameters**: | **Parameter** | **Data Type** | **Requirement** | **Description** | | ------------- | ------------- | --------------- | ----------------------------------------------------------------------------------- | | custom\_field | String | Optional | Field to store custom metadata for the subscriber | | status | Enum  | Mandatory | Indicates whether the subscriber is active or not
enum \{“active”, “inactive”} | **Response Type:** JSON **Response Body Parameters: **Refer *Subscriber Response Object* Sample Request ```javascript https:///v2/accounts//subscribers/archit {   "status": "inactive", } ``` Sample Response ```json { "request_id": "8019271c8d98422db509c2801e63435f", "method": "PUT", "http_code": 200, "response": { "code": 200, "error_data": null, "status": "success", "data": { "date_created": "2019-11-19T23:14:18+05:30", "date_updated": "2019-11-20T11:13:38+05:30", "subscriber_name": "archit", "status": "inactive", "custom_field": null } } } ``` ### Get Subscriber API returns subscriber details. **Method: **`GET` **Request Url: **`https:///v2/accounts//subscribers/` **Authorization Type:**`Basic authentication using API key:token`  **Request Body Parameters: **None **Response Type:** `JSON` **Response Body Parameters: **On success returns *Subscriber Response Object* Sample Request ```javascript https:///v2/accounts//subscribers/archit ``` Sample Response ```json { "request_id": "287c227674af40b38531a1c247262deb", "method": "GET", "http_code": 200, "response": { "code": 200, "error_data": null, "status": "success", "data": { "date_created": "2019-11-19T23:14:18+05:30", "date_updated": "2019-11-20T11:13:38+05:30", "subscriber_name": "archit", "status": "inactive", "custom_field": null } } } ``` ### List Subscribers API returns a paginated list of subscribers. **Method: **`GET` **Request Url: **`https:///v2/accounts//subscribers>?status=abc&page_size=xyz&offset=xyz` **Authorization Type: **`Basic authentication using API key:token`  **Request Body Parameters: ** | **Query Parameter** | **Data Type** | **Requirement** | **Description** | | ------------------- | ------------- | --------------- | -------------------------------------------------------- | | status | Enum  | Optional | Status for the subscriber | | page\_size | uint64 | Optional | Page size for response. Default and maximum value is 100 | | offset | uint64 | Optional | Offset from which to get the records. Defaults to 0 | **Response Type:** `JSON` **Response Body Parameters: **On success returns paginated list of *Subscriber Response Object* Sample Request ```javascript https:///v2/accounts//subscribers?page=2&offset=3 ``` Sample Response ```json { "request_id": "b5f0c6780ec443d08947ba2015a06a04", "method": "GET", "http_code": 200, "metadata": { "prev_page_uri": "/v2/accounts//subscribers?offset=6&page_size=3", "next_page_uri": "/v2/accounts//subscribers?offset=12&page_size=3", "first_page_uri": "/v2/accounts//subscribers?offset=0&page_size=3" }, "response": [   { "code": 200, "error_data": null, "status": "success", "data": { "date_created": "2019-12-30T17:12:00+05:30", "date_updated": "2019-12-30T17:12:00+05:30", "subscriber_name": "shyam", "status": "active", "custom_field": null } },   { "code": 200, "error_data": null, "status": "success", "data": { "date_created": "2019-12-30T17:09:41+05:30", "date_updated": "2019-12-30T17:09:41+05:30", "subscriber_name": "kiran", "status": "active", "custom_field": "test" } },   { "code": 200, "error_data": null, "status": "success", "data": { "date_created": "2019-12-30T13:35:07+05:30", "date_updated": "2019-12-30T13:35:07+05:30", "subscriber_name": "mandeep", "status": "active", "custom_field": null } } ], } ``` ### Delete Subscriber API deletes a subscriber permanently. **Method: **`DELETE` **Request Url: **`https:///v2/accounts//subscribers/` **Authorization Type: **`Basic authentication using API key:token ` **Request Body Parameters: **None **Response Type:** `JSON` **Response Body Parameters: **On success, HTTP response 204 is returned with no response body. In case of failure 404 is returned Sample Request ```javascript https:///v2/accounts//subscribers/shyam ``` Sample Response (a) Success: `No body` (b) Failure: ```json {     "request_id": "af0087d5331f479599d2c987efe9f664",     "method": "DELETE",     "http_code": 404,     "response": {         "code": 404,         "error_data": {             "code": 1000,             "description": "Subscriber not found",             "message": "Not Found"         },         "status": "failure",         "data": null     } } ```