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 ofis_inducted
when present. (allowed values:true
,false
) - is_on_site:
boolean
=> filter by value ofis_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 ofpossibly_away
when present. (allowed values:true
,false
) - preset_filter:
string
=> if set toadmin_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 siteid
oruuid
. - team_id:
int
=> if present filter entries byteam_id
. - team_user_id:
int_or_uuid
=> if present filter entries by siteid
oruuid
. - 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 isasc
ordesc
andfield_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 tofalse
. Use create Site Visit if you need to sign in a person.
- is_signed_in:
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