List groups

get https://{hostname}/papi/v1/groups

You need information about the prevailing group to access most PAPI interfaces. This operation provides a read-only list of groups, which may contain properties. This operation provides a flat list of groups, along with parentGroupId information to structure them as a hierarchy. Each group also lists any available contracts that enable property features, but not which group contains a given property. Use the Identity and Access Management API to assign properties to groups, and modify the group hierarchy.

Recipes

List groups

Open Recipe

Responses

Response body

object

accountId

string

Identifies the prevailing account under which you requested the data. See ID prefixes for details on how to omit the ID's act_ prefix.

accountName

string

A descriptive name for the account.

groups

object

The set of requested groups, available within an items array.

items

array of objects

Encapsulates information about the group that contains a property. Relevant response objects appear within the outer envelope's groups.items array.

items

object

contractIds

array of strings

required

length ≥ 1

A set of string identifiers for contracts whose products can be applied to properties within a group.

contractIds*

groupId

string

required

Identifies each group. See ID prefixes for details on how to omit the ID's grp_ prefix.

groupName

string

required

A descriptive label for the group.

parentGroupId

string

Identifies another group as a parent, defining the relative location of the group within the group hierarchy. If omitted, it's the root-level group at the top of the hierarchy.

Headers

object

X-RateLimit-Limit

integer

Maximum sustainable number of request allowed each minute per account. This rate limit protects PAPI resources from being exhausted by single users. Once you exceed the limit, you receive the 429 error. If you call PAPI using multiple API clients within the same account, the rate limit applies globally to all API clients.

This API also provides a burst limit that specifies how many requests you can make in excess of the imposed rate limit. The one-time burst limit is 1000 requests. Once you consume all available resources, the burst capacity increases steadily by 100 requests every minute, until it reaches its initial maximum limit of 1000.

X-RateLimit-Remaining

integer

Remaining number of requests allowed each minute per account. See Rate and resource limiting for details.

Language

URL


xxxxxxxxxx
1
curl --request GET \
2
     --url https://hostname/papi/v1/groups \
3
     --header 'PAPI-Use-Prefixes: true' \
4
     --header 'accept: application/json'


xxxxxxxxxx
31
}
1
{
2
  "accountId": "act_A-CCT3456",
3
  "accountName": "Internet Company",
4
  "groups": {
5
    "items": [
6
      {
7
        "contractIds": [
8
          "ctr_C-0N7RAC71"
9
        ],
10
        "groupId": "grp_32145",
11
        "groupName": "Example.com-1-1TJZH5"
12
      },
13
      {
14
        "contractIds": [
15
          "ctr_K-0N7RAK7"
16
        ],
17
        "groupId": "grp_32145",
18
        "groupName": "Test",
19
        "parentGroupId": "grp_15225"
20
      },
21
      {
22
        "contractIds": [
23
          "ctr_K-0N7RAK71"
24
        ],
25
        "groupId": "grp_12345",

200The response lists available groups.

400Bad request.

401Unauthorized.

403Forbidden.

404Not found.

405Method not allowed.

406Not acceptable.

429Too many requests.

500Internal server error.