Unavailable Time¶

Warning

The following endpoints are accessible only if the Unavailable Time feature is enabled for the organisation using the API. Expect a 403 error (Forbidden) otherwise.

This API allows listing and retrieving Unavailable Time Types and Unavailable Times for a specific user. Unavailable Time Types and Unavailable Times are identified by their UUID. Unavailable Time Types can be created/updated/deleted only by WebApp users, as they are read-only on the API.

List Unavailable Time Types¶

GET /unavailability/types¶

List all Unavailable Time Types.

Sample request:

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

Query Parameters:

sortedBy – Available sorting criteria: name
archived – Optional boolean denoting if an archived Unavailable Time Type must be retrieved
name – Optional string to return only Unavailable Time Types whose name contains this value

Sample response:

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


{
    "count": 5,
    "items": [
        {
            "uuid": "e4883fb60a9f478a857baca030da935d",
            "name": "PTO",
            "description": "Use to book personal time off",
            "archived": false,
            "paid": false,
            "link": {
              "rel": "detail",
              "url": "https://api.fieldaware.net/unavailability/types/e4883fb60a9f478a857baca030da935d"
            }
        },
        {
            "uuid": "8b2e54a163bd40618e2d80cf7870c09b",
            "name": "Training",
            "description": "Use for company training",
            "archived": false,
            "paid": false,
            "link": {
              "rel": "detail",
              "url": "https://api.fieldaware.net/unavailability/types/8b2e54a163bd40618e2d80cf7870c09b"
            }
        }
    ],
    "page": 0,
    "pageSize": 2,
    "sortedBy": [
        "name"
    ]
}

Status Codes:

200 OK – resources retrieved successfully
422 Unprocessable Entity – validation error

Get Unavailable Time Type¶

GET /unavailability/types/(type_ref)¶

Retrieve a given Unavailable Time Type.

Sample request:

GET /unavailability/types/8b2e54a163bd40618e2d80cf7870c09b 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": "8b2e54a163bd40618e2d80cf7870c09b",
    "name": "PTO",
    "description": "Use to book personal time off",
    "archived": false,
    "paid": false
}

Status Codes:

200 OK – resource retrieved successfully
404 Not Found – resource not found

List Unavailable Times¶

GET /user/(user_ref)/unavailability¶

List all Unavailable Times for a specific user, optionally restricted to a given time window.

The <start date> and <end date> parameters must be given in ISO 8601 format, and need to be URL-encoded where appropriate.

Sample request:

GET /user/4a1de64d6b184abfb5692d2443dfa4d2/unavailability?pageSize=2 HTTP/1.1
Host: api.fieldaware.net
Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
Content-Type: application/json
Accept: application/json

Query Parameters:

sortedBy – Available sorting criteria: start, uuid
start – Optional filtering value for start date
end – Optional filtering value for end date

Sample response:

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


{
    "count": 5,
    "items": [
        {
            "uuid": "6f4214df45a34ab3a1664920e8505292",
            "start": "2019-03-20T00:00:00+00:00",
            "end": "2019-03-20T23:59:59+00:00",
            "details": "Personal time off",
            "type": {
                "uuid": "8b2e54a163bd40618e2d80cf7870c09b"
            },
            "link": {
              "rel": "detail",
              "url": "https://api.fieldaware.net/user/4a1de64d6b184abfb5692d2443dfa4d2/unavailability/6f4214df45a34ab3a1664920e8505292"
            }
        },
        {
            "uuid": "dc42f6fadc794665b2953f932e4c102e",
            "start": "2019-03-23T00:00:00+00:00",
            "end": "2019-03-23T23:59:59+00:00",
            "details": "Personal time off",
            "type": {
                "uuid": "8b2e54a163bd40618e2d80cf7870c09b"
            },
            "link": {
              "rel": "detail",
              "url": "https://api.fieldaware.net/user/4a1de64d6b184abfb5692d2443dfa4d2/unavailability/dc42f6fadc794665b2953f932e4c102e"
            }
        }
    ],
    "page": 0,
    "pageSize": 2,
    "sortedBy": [
        "start",
        "uuid"
    ]
}

Status Codes:

200 OK – resources retrieved successfully
422 Unprocessable Entity – validation error

Get Unavailable Time¶

GET /user/(user_ref)/unavailability/(unavailable_time_ref)¶

Retrieve a given Unavailable Time for a specific user.

Sample request:

GET /user/4a1de64d6b184abfb5692d2443dfa4d2/unavailability/6f4214df45a34ab3a1664920e8505292 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": "6f4214df45a34ab3a1664920e8505292",
    "start": "2019-03-20T00:00:00+00:00",
    "end": "2019-03-20T23:59:59+00:00",
    "details": "Personal time off",
    "type": {
        "uuid": "8b2e54a163bd40618e2d80cf7870c09b"
    }
}

Status Codes:

200 OK – resource retrieved successfully
404 Not Found – resource not found

Create Unavailable Time¶

POST /user/(user_ref)/unavailability¶

Create a new Unavailable Time for a specific user.

The following restrictions apply:

You can’t have overlapping Unavailable Times for the same user.
You can’t create an Unavailable Time specifying a type that’s been archived.
If your organisation is Enterprise-enabled, you can’t create an Unavailable Time for users in other branches you don’t have full access to.

Sample request:

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

{
   "start": "2019-04-14T10:00:00+01:00",
   "end": "2019-04-14T12:00:00+01:00",
   "details": "Personal time off",
   "type": {
      "uuid": "8b2e54a163bd40618e2d80cf7870c09b"
   }
}

Request JSON Object:

start (string) – ISO-formatted starting datetime (required)
end (string) – ISO-formatted end datetime (required)
details (string) – Description of the new Unavailable Time (optional)
type.uuid (string) – Unique identifier (UUID) of the Unavailable Time Type (required)

Sample response:

HTTP/1.1 201 CREATED

{
   "start": "2019-04-14T09:00:00+00:00",
   "link": {
      "url": "https://api.fieldaware.net/user/4a1de64d6b184abfb5692d2443dfa4d2/unavailability/379cdd559bee4eaea01edbde9ebc15e7",
      "rel": "detail"
   },
   "uuid": "379cdd559bee4eaea01edbde9ebc15e7",
   "end": "2019-04-14T11:00:00+00:00",
   "type": {
      "uuid": "8b2e54a163bd40618e2d80cf7870c09b"
   },
   "details": "Personal time off"
}

Status Codes:

201 Created – created successfully
422 Unprocessable Entity – validation error

Update Unavailable Time¶

PUT /user/(user_ref)/unavailability/(unavailable_time_ref)¶

Update an existing Unavailable Time for a specific user.

All fields are optional, and only the specified fields will be updated.

The following restrictions apply:

You can’t have overlapping Unavailable Times for the same user.
You can’t update an Unavailable Time to a type that’s been archived, but you can update an instance of Unavailable Time that already has an archived type.
If your organisation is Enterprise-enabled, you can’t update an Unavailable Time for users in other branches you don’t have full access to.

Sample request:

PUT /user/4a1de64d6b184abfb5692d2443dfa4d2/unavailability/379cdd559bee4eaea01edbde9ebc15e7 HTTP/1.1
Host: api.fieldaware.net
Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
Content-Type: application/json
Accept: application/json

{
   "start": "2019-04-15T10:00:00+01:00",
   "end": "2019-04-15T12:00:00+01:00",
   "details": "Other personal time off",
   "type": {
      "uuid": "8b2e54a163bd40618e2d80cf7870c09b"
   }
}

Request JSON Object:

start (string) – ISO-formatted starting datetime (optional)
end (string) – ISO-formatted end datetime (optional)
details (string) – Description of the new Unavailable Time (optional)
type.uuid (string) – Unique identifier (UUID) of the Unavailable Time Type (optional)

Status Codes:

204 No Content – resource updated successfully
422 Unprocessable Entity – validation error
404 Not Found – resource not found

Delete Unavailable Time¶

DELETE /user/(user_ref)/unavailability/(unavailable_time_ref)¶

Delete an existing Unavailable Time for a specific user.

The following restriction applies:

You can’t delete an Unavailable Time for users in other branches you don’t have full access to.

Sample request:

DELETE /user/4a1de64d6b184abfb5692d2443dfa4d2/unavailability/379cdd559bee4eaea01edbde9ebc15e7 HTTP/1.1
Host: api.fieldaware.net
Authorization: Token 9dcae3660ec84eac94bb506e09a9af40
Content-Type: application/json
Accept: application/json

Status Codes:

204 No Content – resource deleted successfully
404 Not Found – resource not found