Groups

Introduction

Groups allow you to apply shared rules to multiple holders.

The group object

{
  "id": "fad4f1b0-c5d5-48fd-ae26-3e271aa9ace0",
  "name": "Test Group",
  "partition": "619cceb0-ac58-4b15-a8ec-32efcb0476ba"
}

Property	Type	Description
id	String	The group ID.
name	String	The group name.
partition	string	The partition ID.

Basic Endpoints

Create a group

Request

POST https://systems.pdk.io/{{system_id}}/groups HTTP/1.1
Authorization: Bearer {{system_token}}
Content-Type: application/json

{
  "name": "Test Group"
}

Parameter	Location	Type	Required	Description
system_id	Path	String	Yes	The system ID.
system_token	Header	String	Yes	A valid system token.
name	Body	String	Yes	The group name. This must be unique within a system. The maximum length is 70 characters.
partition	Body	String	No	The partition ID.

Response

The response contains the ID of the newly created group object.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "fad4f1b0-c5d5-48fd-ae26-3e271aa9ace0"
}

Retrieve a group

Request

GET https://systems.pdk.io/{{system_id}}/groups/{{group_id}} HTTP/1.1
Authorization: Bearer {{system_token}}

Parameter	Location	Type	Required	Description
system_id	Path	String	Yes	The system ID.
group_id	Path	String	Yes	The group ID.
system_token	Header	String	Yes	A valid system token.

Response

The response contains a group object.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "fad4f1b0-c5d5-48fd-ae26-3e271aa9ace0",
  "name": "Test Group",
  "partition": "619cceb0-ac58-4b15-a8ec-32efcb0476ba"
}

Update a group

Request

PUT https://systems.pdk.io/{{system_id}}/groups/{{group_id}} HTTP/1.1
Authorization: Bearer {{system_token}}
Content-Type: application/json

{
  "name": "Test Group",
  "partition": "619cceb0-ac58-4b15-a8ec-32efcb0476ba"
}

Parameter	Location	Type	Required	Description
system_id	Path	String	Yes	The system ID.
group_id	Path	String	Yes	The group ID.
system_token	Header	String	Yes	A valid system token.
name	Body	String	Yes	The group name. This must be unique within a system. The maximum length is 70 characters.
partition	Body	String	Yes	The partition ID.

Response

HTTP/1.1 204 No Content

Delete a group

Request

DELETE https://systems.pdk.io/{{system_id}}/groups/{{group_id}} HTTP/1.1
Authorization: Bearer {{system_token}}

Parameter	Location	Type	Required	Description
system_id	Path	String	Yes	The system ID.
group_id	Path	String	Yes	The group ID.
system_token	Header	String	Yes	A valid system token.

Response

HTTP/1.1 204 No Content

List all groups

Request

GET https://systems.pdk.io/{{system_id}}/groups HTTP/1.1
Authorization: Bearer {{system_token}}

Parameter	Location	Type	Required	Description
system_id	Path	String	Yes	The system ID.
include	Query	String	No	A comma-delimited list of additional properties to include in the response. Available properties include holders, partition, and rules.
page	Query	Integer	No	The zero-based page number used for pagination. The default value is 0.
per_page	Query	Integer	No	The number of items per page used for pagination. The default value is 10 and the maximum value is 100.
system_token	Header	String	Yes	A valid system token.

Response

The response contains an array of group objects.

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": "fad4f1b0-c5d5-48fd-ae26-3e271aa9ace0",
    "name": "Test Group",
    "partition": "619cceb0-ac58-4b15-a8ec-32efcb0476ba"
  }
]

List a holder's groups

Request

GET https://systems.pdk.io/{{system_id}}/holders/{{holder_id}}/groups HTTP/1.1
Authorization: Bearer {{system_token}}

Parameter	Location	Type	Required	Description
system_id	Path	String	Yes	The system ID.
holder_id	Path	String	Yes	The holder ID.
page	Query	Integer	No	The zero-based page number used for pagination. The default value is 0.
per_page	Query	Integer	No	The number of items per page used for pagination. The default value is 10 and the maximum value is 100.
system_token	Header	String	Yes	A valid system token.

Response

The response contains an array of group objects.

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": "fad4f1b0-c5d5-48fd-ae26-3e271aa9ace0",
    "name": "Test Group",
    "partition": "619cceb0-ac58-4b15-a8ec-32efcb0476ba"
  }
]

Add a holder to a group

Request

PUT https://systems.pdk.io/{{system_id}}/holders/{{holder_id}}/groups/{{group_id}} HTTP/1.1
Authorization: Bearer {{system_token}}

Parameter	Location	Type	Required	Description
system_id	Path	String	Yes	The system ID.
holder_id	Path	String	Yes	The holder ID.
group_id	Path	String	Yes	The group ID.
system_token	Header	String	Yes	A valid system token.

Response

HTTP/1.1 204 No Content

Remove a holder from a group

Request

DELETE https://systems.pdk.io/{{system_id}}/holders/{{holder_id}}/groups/{{group_id}} HTTP/1.1
Authorization: Bearer {{system_token}}

Parameter	Location	Type	Required	Description
system_id	Path	String	Yes	The system ID.
holder_id	Path	String	Yes	The holder ID.
group_id	Path	String	Yes	The group ID.
system_token	Header	String	Yes	A valid system token.

Response

HTTP/1.1 204 No Content

Update a group's holders

This endpoint overwrites all holders assigned to a group. When adding or removing individual holders, you can add a holder to a group or remove a holder from a group instead.

Request

PUT https://systems.pdk.io/{{system_id}}/groups/{{group_id}}/holders HTTP/1.1
Authorization: Bearer {{system_token}}
Content-Type: application/json

{
  "holders": [
    "145424ca-4dad-4877-b428-9eeb656a1dce",
    "636042c0-073b-496a-b6c5-c506474ba379",
    "7e8e015a-4013-4c32-88f3-f6ac2eba4b2f"
  ]
}

Parameter	Location	Type	Required	Description
system_id	Path	String	Yes	The system ID.
group_id	Path	String	Yes	The group ID.
system_token	Header	String	Yes	A valid system token.
holders	Body	String[]	Yes	An array of holder IDs.

Response

HTTP/1.1 204 No Content

Update a holder's groups

This endpoint overwrites all groups assigned to a holder. When adding or removing individual groups, you can add a holder to a group or remove a holder from a group instead.

Request

PUT https://systems.pdk.io/{{system_id}}/holders/{{holder_id}}/groups HTTP/1.1
Authorization: Bearer {{system_token}}
Content-Type: application/json

{
  "groups": [
    "3ca9137a-da36-41dd-8f56-a7c8de62822e",
    "ebacca80-3c1f-412d-b994-d5992fce2907",
    "7ab601d7-ec8d-49eb-945c-4114d3130241"
  ]
}

Parameter	Location	Type	Required	Description
system_id	Path	String	Yes	The system ID.
holder_id	Path	String	Yes	The holder ID.
system_token	Header	String	Yes	A valid system token.
groups	Body	String[]	Yes	An array of group IDs.

Response

HTTP/1.1 204 No Content