Subscriber Management API

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 \<base url> 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 alphanumeric characters whitespace characters are not allowed e g alexbourton, alexbourton, alexbourton, alex123bourt45on 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 //\<base url>/v2/accounts/\<account sid>/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 https //\<base url>/v2/accounts/exotel13m2/subscriber token { "platform" "android", "device id" "2fc4b5912826ad1", "subscriber name" “archit” } sample response { "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 //\<base url>/v2/accounts/\<account sid>/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 https //\<base url>/v2/accounts/exotelip2ipcalling1/subscribers { "subscribers" \[ { "subscriber name" "bob", "custom field" "support" }, { "subscriber name" "nidhi" }, { "subscriber name" "archit" } ] } sample response { "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 //\<base url>/v2/accounts/\<account sid>/subscribers/\<subscriber name> 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 https //\<base url>/v2/accounts/exotelip2ipcalling1/subscribers/archit { "status" "inactive", } sample response { "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 //\<base url>/v2/accounts/\<account sid>/subscribers/\<subscriber name> 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 https //\<base url>/v2/accounts/exotelip2ipcalling1/subscribers/archit sample response { "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 //\<base url>/v2/accounts/\<account sid>/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 https //\<base url>/v2/accounts/exotelip2ipcalling1/subscribers?page=2\&offset=3 sample response { "request id" "b5f0c6780ec443d08947ba2015a06a04", "method" "get", "http code" 200, "metadata" { "prev page uri" "/v2/accounts/exotelip2ipcalling1/subscribers?offset=6\&page size=3", "next page uri" "/v2/accounts/exotelip2ipcalling1/subscribers?offset=12\&page size=3", "first page uri" "/v2/accounts/exotelip2ipcalling1/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 //\<base url>/v2/accounts/\<account sid>/subscribers/\<subscriber name> 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 https //\<base url> /v2/accounts/exotelip2ipcalling1/subscribers/shyam sample response (a) success no body (b) failure { "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 } }