group_members/v3
RESTful style
Administration of Group Members / Distribution Lists
Host URL: https://api.tellustalk.com/
Endpoint: /number/group_members/v3/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/group_members/v3/id_box.e1dp4c?user_id=john.smith&cursor=etgyhjklmn>; rel="next"; title*=UTF-8'uk'next_page_with_more_records (Related Links)
X-Name-Base64: Base64-encoded display name of group
---------------------------------------------------------------------------------------------------------------------------------------------------------------------
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.
Unless query has invalid format, DELETE returns HTTP response code 200 (OK) and a counter in.the Response header.
As HTTP DELETE is not supported by HTML5 forms, there are two ways, delete can be faked, either using HTTP GET or POST.
HTTP Method
GET
DELETE
POST
Description
GET only: 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 present in the URL query string.
If we only specify one status (active or blocked), then all the records with the provided status are deleted from the distribution list.
To delete specific members, send one or more address fields with values.
The values must be normalized to the exact format used in DB address field (and of course URL-encoded)
Examples:
DELETE: /number/group_members/v3/id_GROUPID?address=email%3Auser@mycompany.se
DELETE-by-GET: /number/group_members/v3/id_GROUPID?method=delete&address=sms%3A%2B46704000000
If we want to delete many specific members, we cannot use GET method to fake delete due to url max length limit.
Tunnel DELETE through POST by setting X-HTTP-Method-Override: DELETE in the request header.
The HTTP body contains a single item "address" which is a list of items to be deleted.
Examples:
Request Header
Content-Type: application/json
Content-Type: application/xml
Request Body
{"address": ["sms:+46704000000", "email:abc@mycompany.se"]}
<root>
<address>
<item>sms:+46704000000</item>
<item>email:abc@mycompany.se</item>
</address>
</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)
NOTE on addressing:
The group_members application uses a normalized format for address field.
To delete a group member, the exact format used in DB must be sent.
While it works to add or update a member like
POST {"address": "0704000001"}
The stored value, returned by GET will be
GET {"address": "sms:+46704000001", "status": "active"}
If you try to delete by sending
DELETE ... ?address=0704000001
- the application may respond with HTTP 200 (OK), but nothing happens