addadd-thickarrow-downaxebreadcrumb dividercameracc-compulsarychatclosecontactdata-usersdebugdevelopersdismissdocumentserrorglossaryinfolinkpublisherssearchselect-dropdownsuccesstableswarning

Developers

APIs to manage your site, query data and build new products and services.

  1. Home
  2. Developers
  3. Publisher Admin API
  4. Users & Groups API

Users & Groups API

The Users & Groups APIs provide functionality for managing user access, group permissions and group configuration.

List Users

This API is only available to Site Administrators.

GET /users/
List Users

Returns a list of users who have access to your site.

Response 200

Headers

Content-Type: application/json

Body

[
    {
        "id": 1,
        "url": "https://{domain}/services/api/v1/users/1/",
        "first_name": "Test",
        "last_name": "User",
        "country": "NZ",
        "email": "test.user@example.com",
        "is_locked": false,
        "is_site_admin": false,
        "seat_type": "none"
    }    
]

Filtering Users

Users can be filtered by the following parameters:

  • seat_type: The type of seat for the named user. Either paid or none
  • group: A group identifier that the User's should belong to. Multiple group IDs can be supplied with multiple group parameters. The list contains users who belong to all the groups queried. Special group identifiers can also be used (e.g. administrators refer to the Permissions API for more examples).
  • q: keyword or email address for search.

Examples

  • List all site administrators: /users/?group=administrators
  • Find all paid seat usersin group 100: /users/?seat_type=paid&group=100
  • Searching for a user by email address: /users/?q=test.user@koordinates.com

User Detail

GET /users/{id}/
Get User Detail

Returns detail about a specific User.

Response 200

Headers

Content-Type: application/json

Body

{
    "id": 1,
    "url": "https://{domain}/services/api/v1/users/1/",
    "first_name": "Test",
    "last_name": "User",
    "country": "NZ",
    "email": "test.user@example.com",
    "is_locked": false,
    "is_site_admin": false,
    "seat_type": "none"
}

List User Permissions

GET /users/{id}/access/
List User Permissions

Read-only list of a user's permissions. These are standard permissions that one can interact with using the Permissions API.

Example: /users/3/access/

Response 200

Headers

Content-Type: application/json

Body

[
    {
        "permission": "admin",
        "on": {
            "id": 123,
            "url": "https://test.koordinates.com/services/api/v1/groups/123/",
            "name": "Important Group",
            "country": "NZ"
        },
        "type": "group",
        "url": "https://{domain}/services/api/v1/groups/123/permissions/user.3/"
    }
]

List Groups

GET /groups/
Get Group List

Returns a list of Groups.

Response 200

Headers

Content-Type: application/json

Body

[
    {
        "id": 1,
        "url": "https://{domain}/services/api/v1/groups/1/",
        "name": "Example Group",
        "country": "NZ"
    }
]

Create a Group

POST /group/
Create Group

Creates a new Group. Note that only Site Administrators can create a new Group for a site.

Parameters

  • url_slug: string The human readable URL slug for the new Group
  • permissionsstring (required) The permissions URL for the new Group
  • name: string (required) The name for the new Group
  • data_owner: string The owner of the Group's data (site or group)
  • country: string (required) The code for the relevant county for this Group
  • access_requests_enabled: boolean Whether members of the site can request access to this Group

  • catalog_feeds_enabled: boolean Whether the Group's data appears in public data feeds

Request

Headers

Content-Type: application/json

Body

{
    "url_slug": "this-is-a-new-group",
    "permissions": null,
    "name": "New Group",
    "data_owner": "site",
    "country": "NZ",
    "access_requests_enabled": false,
    "catalog_feeds_enabled": false
}

Response 201

Headers

Content-Type: application/json

Body

{
    "id": 2,
    "url": "https://{domain}/services/api/v1/groups/2/",
    "url_html": "https://{domain}/group/this-is-a-new-group/",
    "url_slug": "this-is-a-new-group",
    "permissions": "https://{domain}/services/api/v1/groups/2/permissions/",
    "name": "New Group",
    "data_owner": "site",
    "country": "NZ",
    "access_requests_enabled": false,
    "catalog_feeds_enabled": false
}

Group Detail

GET /group/1/
Get Group Detail

Gets detailed information about a group.

Response 200

Headers

Content-Type: application/json

Body

{
    "id": 1,
    "url": "https://{domain}/services/api/v1/groups/1/",
    "url_html": "https://{domain}/group/this-is-group-1/",
    "url_slug": "this-is-group-1",
    "permissions": "https://{domain}/services/api/v1/groups/1/permissions/",
    "name": "Example Group",
    "data_owner": "site",
    "country": "NZ",
    "access_requests_enabled": false,
    "catalog_feeds_enabled": false
}