xgroup_members/v1
RESTful style
Administration of Group Members / Distribution Lists
Host URL: https://api.tellustalk.com/
Endpoint: /number/xgroup_members/v1/id_{groupId}
Methods supported: GET, POST, DELETE
Common Headers in all methods:
--------------------------------------------------------------------------------------------------------------------------------------------------------------------
Request Headers:
Accept: application/json (recommended) or application/xml or text/html
Content-Type: application/json (recommended) or application/xml
Response Headers:
Content-Type: application/json or application/xml
Link: </number/xgroup_members/v1/id_box.e1dp4c?user_id=john.smith&cursor=etgyhjklmn>; rel="next"; title*=UTF-8'uk'next_page_with_more_records (Related Links)
---------------------------------------------------------------------------------------------------------------------------------------------------------------------
Member:
Each group member consists of 'address', 'name' and 'status' properties.
GET Method:
To retrieve a list of members (items). In the “happy” (or non-error case), GET returns a representation in XML or JSON, an HTTP response code of 200 (OK) and
some counters in.the Response header.
Request Parameters:
Common request parameters, used as search filters (similar to SQL 'WHERE' clause), and their description are given below:
Response Headers: (Besides response header fields given above, in case of GET method, the following fields are returned)
X-Total-Count: 18 (total number of member records = active +blocked)
X-Active-Count: 10 (total number of active members)
X-Blocked-Count: 8 (total number of blocked members)
X-Unsubscribed-Count: 1 (total number of unsubscribed members)
Response Data:
A list of members (items) with named values, where each member consists of 'address', 'name' and 'status' properties.
Examples:
Request Header
Accept: application/json
Accept: application/xml
Retrieved Results
[{"address": "sms:+46704000000", "name": "", "status": "active"},
{"address": "email:abc@tellustalk.com", "name": "abc", "status": "blocked"}]
<root>
<item>
<address>sms:+46704000000</address>
<name />
<status>active</status>
</item>
<item>
<address>email:abc@tellustalk.com</address>
<name>abc</name>
<status>blocked</status>
</item>
</root>
POST Method:
To create and update group members. In case of success, POST returns an HTTP response code of 200 (OK) and some counters in.the Response header.
Request Data:
A list of members (items) with named values, where each member consists of 'address', 'name' and 'status' properties.
Examples:
Request Header
Content-Type: application/json
Content-Type: application/xml
Request Body
[{"address": "sms:+46704000000", "name": "", "status": "active"},
{"address": "email:abc@tellustalk.com", "name": "abc", "status": "blocked"}]
<root>
<item>
<address>sms:+46704000000</address>
<name />
<status>active</status>
</item>
<item>
<address>email:abc@tellustalk.com</address>
<name>abc</name>
<status>blocked</status>
</item>
</root>
Request Body Parameters:
Each group member consists of 'address', 'name' and 'status' properties.
POST data scenarios:
Scenario A: (Invalid Address or request)
Nothing will be added or updated and the member record will be returned as response data.
Scenario B: (Insert new member -> address does not exist in the group)
The member is saved (Member added).
Scenario C: (Update member -> address is already there in the group)
Case 1: If no "status" and "name" are provided, nothing will be updated (Member already exists).
Case 2: If "name" provided is different from the existing "name", the friendly name of the member will be updated (Member updated).
Case 3: If provided status is "active" and the existing status is "blocked", it is activate request (Member updated).
Case 4: If provided status is "blocked" and the existing status is "active", it is blocked request (Member updated).
Response Headers: (Besides response header fields given above, in case of POST method, the following fields are returned)
X-Total-Count: 18 (total number of valid members attempted)
X-Added-Count: 8 (number of new members created)
X-Updated-Count: 2 (number of members updated)
X-AlreadyExist-Count: 8 (number of members already exist)
Response Data:
A list of invalid members (items) with named values, where each member consists of 'address', 'name' and 'status' properties.
DELETE Method:
This method is used to delete group members. In case of success, DELETE returns an HTTP response code of 200 (OK) and a counter in.the Response header.
As HTTP DELETE is not supported by HTML5, there are two ways, delete can be faked, either using HTTP GET or POST.
Fake Delete using
GET
POST
Description
In order to delete group members, method=delete should be provided as a field=value pair in URL query string.
In order to delete all members, status=active and status=blocked should be there in the URL query string.
If we only specify one of the status (active or blocked), then all the records with the provided status are deleted from the distribution list.
We can also delete specific members by providing one or more address fields with values.
If we want to delete specific members and they are many, we cannot use GET method to fake delete. We can tunnel DELETE through POST by setting X-HTTP-Method-Override: DELETE in the request header. The HTTP body contains a list of items (with mandatory address property), which need to be deleted.
Examples:
Request Header
Content-Type: application/json
Content-Type: application/xml
Request Body
[{"address": "sms:+46704000000"}, {"address": "email:abc@tellustalk.com"}]
<root>
<item>
<address>sms:+46704000000</address>
</item>
<item>
<address>email:abc@tellustalk.com</address>
</item>
</root>
Request Headers: (Besides request header fields given above, in case of data posted in the body (using POST to fake DELETE), the following field need to be provided)
X-HTTP-Method-Override: DELETE
Response Headers: (Besides response header fields given above, the following fields are returned)
X-Total-Count: 2 (number of members deleted)