Site Visits API

With Site Visits api V4 you can:

• List Site Visits
• Create a Site Visit
• Fetch a Site Visit
• Update a Site Visit
• Bulk update a list of Site Visits
• Response fields

List site visits

Fetch a paginated list of site visits.

See the optional response fields.

Optional params:

• exclude_ids: int_or_uuid[] => if param is given only allow items not matching any of the given list of integers or uuids.
• include_ids: int_or_uuid[] => if param is given only allow items matching any item of the given list of integers or uuids.
• is_inducted: boolean => filter by value of is_inducted when present. (allowed values: true, false)
• is_on_site: boolean => filter by value of is_on_site when present. (allowed values: true, false)
• person_name: string => partial search on visitors full name
• person_team_name: string => partial search on visitors company (Org name for internal members)
• possibly_away: boolean => filter by value of possibly_away when present. (allowed values: true, false)
• preset_filter: string => if set to admin_view then it will include only results related to current team management, which will exclude entries an admin would only be able to see because he is signed in on a given site.
• site_id: int_or_uuid => if present filter entries by site id or uuid.
• team_id: int => if present filter entries by team_id.
• team_user_id: int_or_uuid => if present filter entries by site id or uuid.
• updated_after: date_time => if present only return entries updated after given date. Valid values are dates in ISO8601 format.
• orderby: membership, person_email, person_name, person_team_name, signed_in_at, updated_at made of <field_name> <direction>. Where direction is asc or desc and field_name is one of the list below:
  • membership
  • person_email
  • person_name
  • person_team_name
  • signed_in_at
  • updated_at

examples:

• ?orderby=updated_at+desc
• ?is_on_site=true&team_id=123&orderby=updated_at+asc

GET /api/v4/site_visits?site_id=ad48f258-cc80-11ed-bed6-367dda11fc13&updated_after=2022-05-24T19:30:30Z&orderby=updated_after+asc&fields=site_uuid,-created_at

200 OK

[
  {
    "id": 1015,
    "uuid": "4fc0e27a-f526-11ed-bb4f-acde48001122",
    "inducted_at": null,
    "is_signed_in": true,
    "is_inducted": null,
    "is_on_site": false,
    "possibly_away": null,
    "signed_in_at": "2023-05-18 04:47:22 +1200",
    "signed_out_at": "2023-05-18 05:47:22 +1200",
    "site_id": 1009,
    "site_uuid": "ad48f258-cc80-11ed-bed6-367dda11fc13",
    "team_user_id": 1014,
    "updated_at": "2023-05-17 14:47:22 +1200"
  },
  {
    "id": 3245,
    "uuid": "4fc0e27a-f526-11ed-bb4f-ffffeeeeaaaa",
    "inducted_at": null,
    "is_signed_in": true,
    "is_inducted": null,
    "is_on_site": true,
    "possibly_away": null,
    "signed_in_at": "2023-05-20 05:40:11 +1200",
    "signed_out_at": null,
    "site_id": 1009,
    "site_uuid": "ad48f258-cc80-11ed-bed6-367dda11fc13",
    "team_user_id": 1014,
    "updated_at": "2023-05-18 22:12:10 +1200"
  }
]

Create a site visit

Creates one site visit.

Input fields for create:

• uuid: string
• team_user_id: record<TeamUser> by id or uuid
• site_id: record<Site> by id or uuid
• signed_in_at: time
• signed_out_at: time

POST /api/v4/site_visits

{
  "site_visit":   {
    "uuid": "4fc0e27a-f526-11ed-bb4f-acde48001122",
    "site_id": "ad48f258-cc80-11ed-bed6-367dda11fc13",
    "team_user_id": "b7a3a57d-9605-457a-8e54-5326b26a5e0c",
    "signed_in_at": "2023-05-18 04:47:22 +1200"
  }
}

201 Created

{
  "id": 1015,
  "uuid": "4fc0e27a-f526-11ed-bb4f-acde48001122",
  "created_at": "2023-05-17 14:47:22 +1200",
  "inducted_at": null,
  "is_inducted": null,
  "is_on_site": true,
  "possibly_away": null,
  "signed_in_at": "2023-05-18 04:47:22 +1200",
  "signed_out_at": null,
  "site_id": 1009,
  "team_user_id": 1014,
  "updated_at": "2023-05-17 14:47:22 +1200"
}

Fetch a site visit

Get a site visit entry.

See the optional response fields.

GET /api/v4/site_visits/1015?fields=site_uuid

200 OK

{
  "id": 1015,
  "uuid": "4fc0e27a-f526-11ed-bb4f-acde48001122",
  "created_at": "2023-05-17 14:47:22 +1200",
  "inducted_at": null,
  "is_inducted": null,
  "is_on_site": true,
  "possibly_away": null,
  "signed_in_at": "2023-05-18 04:47:22 +1200",
  "signed_out_at": null,
  "site_id": 1009,
  "site_uuid": "ad48f258-cc80-11ed-bed6-367dda11fc13",
  "team_user_id": 1014,
  "updated_at": "2023-05-17 14:47:22 +1200"
}

Update a Site Visit

Updates the allowed fields on one single site visit. It only updates the fields sent.

Input fields for update:

• signed_out_at: time

PATCH /api/v4/site_visits/1015

{
  "site_visit":   {
    "signed_out_at": "2023-05-18 05:47:22 +1200"
  }
}

204 No Content

Bulk update a list of Site Visits

Update multiple Site Visits in a background process.

The response for this request is an Async Job resource with current status of the Background process. The background process status can be polled if you need to retrieve conclusion status, result and eventual error messages.

Filter fields for bulk update:

• site_id: record<Site> by id or uuid
• exclude_ids: int_or_uuid[]
• include_ids: int_or_uuid[]
• is_inducted: boolean => To Be implemented
• is_on_site: boolean
• person_name: string
• person_team_name: string
• possibly_away: boolean => To Be implemented
• team_user_id: int_or_uuid
• updated_after: date_time

Input fields for bulk update:

• description: string => value to be echoed on Async Job responses
• site_visit: hash
  • is_signed_in: boolean => only allowed to set the value to false. Use create Site Visit if you need to sign in a person.

POST /api/v4/site_visits/bulk_update?is_on_site=true&site_id=ad48f258-cc80-11ed-bed6-367dda11fc13

{
  "description": "Signing everyone out",
  "site_visit":   {
    "is_signed_in": false,
  }
}

{
  "id": 6543234,
  "completed": false,
  "description": "Signing everyone out",
  "success": null,
  "artifact_url": null,
  "result": null,
  "download_filename": null
}

Response fields

You can use the fields query parameter in any of the Site Visit API endpoints to configure what fields will be included in the response. All fields in bold are included by default but you can opt-out of them using the - prefix.

• id
• uuid
• created_at
• inducted_at
• is_inducted
• is_on_site
• is_signed_in
• person_email
• person_membership
• person_name
• person_team_name
• possibly_away
• signed_in_at
• signed_out_at
• site_id
• site_uuid
• team_user_id
• team_user_uuid
• uninducted_at
• updated_at