Groups¶

Warning

The following endpoints are only accessible if the organisation using the API is Enterprise-enabled. Expect a 403 error (Forbidden) otherwise.

This API allows listing, retrieving, creating, updating and deleting groups. Groups are identified by their UUID.

Note: The entity referred to as Group in this documentation is known as Branch in the web application and its supporting documentation.

List Groups¶

GET /group/¶

List all groups in the organisation.

Sample request:

GET /group/?pageSize=3 HTTP/1.1
Host: api.fieldaware.net
Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
Content-Type: application/json
Accept: application/json

Query Parameters:

sortedBy – can be ordered by name
name – a filtering value for name
archived – a filtering value for archived groups

Sample response:

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


{
    "count": 11,
    "items": [
        {
            "uuid": "4a1de64d6b184abfb5692d2443dfa4d2",
            "name": "Headquarters",
            "link": {
                "url": "https://api.fieldaware.net/group/4a1de64d6b184abfb5692d2443dfa4d2",
                "rel": "detail"
            },
            "archived": false
        },
        {
            "uuid": "d278b2a84b9a479e912c007bf205f647",
            "name": "Florida Branch",
            "link": {
                "url": "https://api.fieldaware.net/group/d278b2a84b9a479e912c007bf205f647",
                "rel": "detail"
            },
            "archived": false
        },
        {
            "uuid": "87eb22efd9334268b97ad7d8e0d9b736",
            "name": "SouthWest Office",
            "link": {
                "url": "https://api.fieldaware.net/group/87eb22efd9334268b97ad7d8e0d9b736",
                "rel": "detail"
            },
            "archived": true
        }
    ],
    "page": 0,
    "pageSize": 3,
    "sortedBy": []
}

Get Group¶

The group representation includes a list of all users with access to the group.

The level of access granted to the users to specific group data (jobs and users in particular) varies:

Base: the user is based (belongs) to the group. As a result, the user has full access to the group’s specific data.
Full access: the user, who is not based in this group, has complete access to the group’s data.
View only: the user, who is not based in this group, has read only access to the group specific data.

GET /group/(group_ref)¶

Retrieve a given group.

Sample request:

GET /group/4a1de64d6b184abfb5692d2443dfa4d2 HTTP/1.1
Host: api.fieldaware.net
Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
Content-Type: application/json
Accept: application/json

Sample response:

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

{
    "uuid": "4a1de64d6b184abfb5692d2443dfa4d2",
    "name": "Florida Branch",
    "colour": "#00B0FF",
    "location": {
        "streetName": "1600 Euclid Avenue",
        "locality": "South Beach",
        "region": "FL",
        "country": "USA",
        "postcode": "55110"
    },
    "phone": "1-800-1234",
    "archived": false,
    "users: [
        {
            "access": "base",
            "uuid": "9f3e7b2251034d0da4c03a7f3a3429d7"
        },
        {
            "access": "view_only",
            "uuid": "489b23cd49cb4e158e8379575b271e92"
        },
        {
            "access": "full_access",
            "uuid": "30dbe80c1fb044248010aa9d13c22f29"
        }
    ]
}

Create Group¶

POST /group/¶

Create a new group.

Sample minimal request: see below for json field values

POST /group/ HTTP/1.1
Host: api.fieldaware.net
Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
Content-Type: application/json
Accept: application/json

{
    "name": "Test branch",
    "location": {
       "streetName": "123 Fake Street",
       "locality": "Ghost Town"
    }
}

Sample full request:

POST /user/ HTTP/1.1
Host: api.fieldaware.net
Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
Content-Type: application/json
Accept: application/json

{
    "name": "North Carolina Branch",
    "colour": "#00B0FF",
    "phone": "1-800-1234",
    "location": {
        "streetName": "900 Metropolitan Avenue",
        "locality": "Charlotte",
        "region": "NC",
        "country": "USA",
        "postcode": "55110"
    }
}

Request JSON Object:

name (string) – Name given to the group (required)
location – Address where the group is located (required).
colour (string) – Hex color code to be used throughout the system to identify elements belonging to the group. The set of valid values is the following: #C000FF, #64DD17, #00B0FF, #FFC107, #FD29FC, #13E2A7, #FF3D00, #7C4DFF, #28E5FD, #02AF96, #F7348C, #488DFC

Sample response:

HTTP/1.1 201 CREATED
Content-Type: application/json
Location: https://api.fieldaware.net/group/6e72acbf8c9048d88626cf87e4009ea5

{
    "uuid": "6e72acbf8c9048d88626cf87e4009ea5",
    "name": "Florida Branch",
    "colour": "#00B0FF",
    "phone": "1-800-1234",
    "location": {
        "country": "USA",
        "region": "FL",
        "postcode": "55110",
        "streetName": "1600 Euclid Avenue",
        "locality": "South Beach"
    }
    "users": [],
    "link": {
        "url": "https://apiqa1.fieldaware.net/group/6e72acbf8c9048d88626cf87e4009ea5",
        "rel": "detail"
    },
    "archived": false
}

Update Group¶

PUT /group/(group_ref)¶

Update a given group.

JSON request body: Same as Create Group, but with all properties being optional.

Archive/Unarchived Group¶

PUT /group/(group_ref)/archive¶: Mark a group as archived.

PUT /group/(group_ref)/unarchive¶: Mark a group as not archived.

Neither of these methods require a body in the request.

Delete Group¶

DELETE /group/(group_ref)¶: Delete a given group.