Get group information

This GET operation retrieves group information based on the group id or by using query parameters (?) to look for a group by ownerId or memberId. If searching by memberId, you receive a list of all groups of which the member is a part. If successful, you receive an HTTP response code of 200 and a JSON response containing the group’s information.

If you do not provide an id in the URL, you get a list of all groups on the SQS instance.
See HTTP response codes for other response codes.

GET /sqs/api/groups/<id>

HEADER INFO

authorisation: HTTP Basic Auth

tenant: <tenantName>

content-type: application/JSON

accept: application/JSON

By default, accept is XML. You must explicitly set accept in your header to application/JSON to receive a JSON response.

permissions: SQS_GROUP_READ_PERMISSION


URL parameters

Parameter Description

id

The auto-assigned identifier that was given to the group upon creation.

Query parameters

To use a query parameter, add a question mark after the endpoint and then the key-value pair:

Example: sqs/api/groups?ownerId=<ownerId>

These query parameters are optional.
Parameter Description

ownerId

The unique identifier passed in the JSON payload when creating the group. This is typically the subscriber’s MSISDN.

memberId

The unique identifier passed in the JSON payload when creating the member of the group. This is typically the subscriber’s MSISDN.

JSON response

The JSON response samples below show getting a group by id and getting all groups.

See group data type descriptions for more details for the fields in the JSON payload.
get group by id
{
  "id" : "AE45F1",
  "ownerId" :  "123123",
  "name" : "Family",
  "created" : "2019-02-01 09:59:32",
  "updated" : "2019-02-01 09:59:32"
}
get all groups
{
    "_embedded": {
        "groups": [
            {
                "created": "2019-10-07T11:22:46.000+0000",
                "updated": "2019-10-07T11:22:46.000+0000",
                "id": "RoPn7CqJ4ZwbIBHbTsxj",
                "ownerId": "0876827150",
                "name": "family",
                "_links": {
                    "self": {
                        "href": "http://localhost:4300/sqs/api/groups/RoPn7CqJ4ZwbIBHbTsxj"
                    }
                }
            },
            {
                "created": "2019-10-11T01:02:21.000+0000",
                "updated": "2019-10-11T01:02:21.000+0000",
                "id": "gQQ1b3wI6eBvB0pHAaAr",
                "ownerId": "06200012435",
                "name": "Family1",
                "_links": {
                    "self": {
                        "href": "http://localhost:4300/sqs/api/groups/gQQ1b3wI6eBvB0pHAaAr"
                    }
                }
            },
            {
                "created": "2019-10-11T15:10:58.000+0000",
                "updated": "2019-10-11T15:10:58.000+0000",
                "id": "pHChof0FSUj8hsutZkur",
                "ownerId": "155899",
                "name": "FamilyGuy",
                "_links": {
                    "self": {
                        "href": "http://localhost:4300/sqs/api/groups/pHChof0FSUj8hsutZkur"
                    }
                }
            },
            {
                "created": "2019-10-11T15:12:34.000+0000",
                "updated": "2019-10-11T15:12:34.000+0000",
                "id": "h4QjAdZSmvHfCfMl0j06",
                "ownerId": "155965",
                "name": "Crickety",
                "_links": {
                    "self": {
                        "href": "http://localhost:4300/sqs/api/groups/h4QjAdZSmvHfCfMl0j06"
                    }
                }
            },
            {
                "created": "2019-10-12T01:08:24.000+0000",
                "updated": "2019-10-12T01:08:24.000+0000",
                "id": "i6hsdRjosCys8GuHBD2s",
                "ownerId": "06200012435",
                "name": "Family2",
                "_links": {
                    "self": {
                        "href": "http://localhost:4300/sqs/api/groups/i6hsdRjosCys8GuHBD2s"
                    }
                }
            },
            {
                "created": "2019-10-13T01:13:15.000+0000",
                "updated": "2019-10-13T01:13:15.000+0000",
                "id": "5hhjJKQFqtOgOJNFhyZW",
                "ownerId": "06200012435",
                "name": "Family3",
                "_links": {
                    "self": {
                        "href": "http://localhost:4300/sqs/api/groups/5hhjJKQFqtOgOJNFhyZW"
                    }
                }
            },
            {
                "created": "2019-10-14T08:03:18.000+0000",
                "updated": "2019-10-14T08:03:18.000+0000",
                "id": "XEHpqIDRVqeVnnFPDeSQ",
                "ownerId": "155888",
                "name": "JoeBloggs",
                "_links": {
                    "self": {
                        "href": "http://localhost:4300/sqs/api/groups/XEHpqIDRVqeVnnFPDeSQ"
                    }
                }
            },
            {
                "created": "2019-10-14T08:03:30.000+0000",
                "updated": "2019-10-14T08:03:30.000+0000",
                "id": "j9rXK7jGeWfKMGn6MV8u",
                "ownerId": "42",
                "name": "JoeBloggsSon",
                "_links": {
                    "self": {
                        "href": "http://localhost:4300/sqs/api/groups/j9rXK7jGeWfKMGn6MV8u"
                    }
                }
            },
        ]
    },
    "_links": {
        "self": {
            "href": "http://localhost:4300/sqs/api/groups?page=0&size=100"
        }
    },
    "page": {
        "size": 100,
        "totalElements": 12,
        "totalPages": 1,
        "number": 0
    }
}

SQS groups data type descriptions

Field Type Description

id

string

The auto-assigned ID given to the group upon creation.

ownerId

string

The ID given to the owner of the group (the creator). This is typicaly the MSISDN of the subscriber who created the group.

The subscriber’s MSISDN in international format.

name

string

The name of the group. This is currently auto-assigned upon group creation.

created

string

The date and time at which the group was created.

This is in ISO 8601 standard format.

updated

string

The date and time at which the group was updated.

This is in ISO 8601 standard format.

HTTP response codes

Code Description

200

success!

207

Multistatus response

Check out HTTP statuses for more details.
This is not applicable to all operations.

400

malformed request

401

unauthorised; bad username or password

403

forbidden; user does not have appropriate privileges

404

group not found

409

conflict with target resource

This often occurs if the item already exists, such as a plan, group, or name.
This is not applicable to all operations.

412

failed validation; this typically means that a property was not set or a value is out of range.

example
HTTP 412
{
  "errors" : [
        {
          "field" : "name",
          "description" : "name is mandatory"
        }
    ]
}

422

failed processing (after passing validation).

example
HTTP 422
{
    "message": "Subscriber max plan count exceeded",
    "errorCode": 1
}
Example 1. SQS response codes

  • 0 = no error

  • 1 = undefined general error

  • 2 = group owner/name pair is not unique

  • 3 = group owner cannot be a member

  • 4 = total member quota exceeds 100%

  • 5 = group does not exist

  • 6 = maximum group size exceeded

  • 7 = the donor does not exist

  • 8 = the shareable plan does not exist

  • 9 = the shareable plan is not a recurring plan

  • 10 = charging group owner unsupported

  • 11 = the recurring donation for this plan already exists

  • 12 = the recipient does not exist

  • 13 = the donor plan max recipient limit was exceeded

  • 14 = subscriber not found

500

internal error

503

request rejected due to overload