Contact Tracing Log and Summary APIs

Knowledge Base > Products > Software > Loop Cloud > Contact Tracing Log and Summary APIs

Authentication and Access Tokens

Overview

Currently, all API Requests require the usage of a token to provide access to Loop Cloud v2’s API Endpoints. Each generated token will only provide access for up to 1 hour and will only provide access to the organization data associated with that specific user. Below is an overview of the token generation and method of how to use this token.

Token Generation
API Request Overview

 

Endpoint

https://api.us.loop.bluecats.com/oauth/token

Method

POST

Content-type

application/x-www-form-urlencoded

Body

 
username=XXXXX
&password=YYYYY
&grant_type=password
 
Example Response Body

{

    “access_token”: “abc123”,

    “token_type”: “Bearer”,

    “expires_in”: 3600

}

 

Key

Format

Usage

access_token

string

Temporary Access Token which can be used in Loop Cloud API Requests

token_type

string

Information of token type, i.e. Bearer

expires_in

int (seconds)

Number of seconds remaining until token expires
Target Organization and Group

Each API Request requires the the specification of the target Organization Id and Group Id that is being accessed. Both the target Organization Id and Group Id can be accessed in the profile menu as shown below:

Token Usage

Below is an example of a user with access to a sample BlueCats organization requesting logs using a valid temporary token for a target date range.

Endpoint https://api.us.loop.bluecats.com/reports/logs/tagcontacts

Method

GET

Headers

 
{'authorization': 'Bearer {access_token}','bc-loop-orgid': 'bc000000-a1a1-b2b2-c3c3-d4d4e5e5f6'
}

Parameters

 
{'groupId': "bc000000-a0a0-b1b1-c2c2-d3d3e4e4f5",'from': '2020-01-01','to': '2021-01-01','limit': 10
}

Contact Tracing Logs API

Overview

Tag Contacts are generated when two tags enter within one of two ranges In Contact or Nearby. A Tag Contact log is a record summarising the time the tags spent in range of each other. To query the data, the user requires an active Bearer Token, organization id and group id, which can be obtained by the methods presented in the Token Generation API section above.

Tag Contact Log – By Organization/Group
API Request Overview

 

Endpoint https://api.us.loop.bluecats.com/reports/logs/tagcontacts

Method

GET

Pagination Type

Next token

Description

Iterate through available logs by ordered by date (either log event timestamp – timestamp or log create/processed timestamp – createdAt

Headers

 
{'authorization': 'Bearer {access_token}','bc-loop-orgid': '{target_org_id}'
}

Example Query

 
https://api.us.loop.bluecats.com/reports/logs/tagcontacts
?groupId=bc000000-0000-0000-0000-000000000002
&from=2020-02-14
&timestampField=createdAt
&sortByTimestampAscending=true
&next=xxxx
Request Parameters

Key

Attributes

Description

groupId

Required
uuid

Filter by Organization Group

from

Optional
default null
datetime ISO 8601 string

Starting timestamp to return events from

to

Optional
default null
datetime ISO 8601 string

when ‘to’ is specified then the results will be ascending, otherwise they will be descending.

limit

Optional
default 100
max 500
Int

Maximum number of results to return

next

Optional
default null
string

Continuation token to paginate through results. When this value is populated in the response, it can be passed to subsequent requests to retrieve additional events.

proximity

Optional
default null
string (Enumeration)

Nearby|Contact

duplicates

Optional
default false
bool

When true the result set will include both duplicate and non-duplicate results. A ‘duplicate’ record is a paired event recorded by the other tag in the tag-to-tag contact.

invalidEvents

Optional
default false
bool

When true the results will include the timeSync issues

sortByTimestampAscending

Optional
default false
bool

 

timestampField

Optional
default ‘timestamp’
Enum: timestamp OR createdAt

Log event timestamp – timestamp or log create/processed timestamp – createdAt

minimumDurationSeconds

Optional
Default: N/A
Format: Int

Minimum contact duration to include for individual logs

objectStereotype

Required when timestampField=’timestamp’. Not applicable when timestampField=’createdAt’
string

Filter results by the target object’s stereotype. Valid values are person, place anddevice

contactStereotype

Required when timestampField=’timestamp’. Not applicable when timestampField=’createdAt’
string

Filter results by the target contact object’s stereotype. Valid values are person, place anddevice
Example Response Body

 


{"next": "2020-01-01T09:00:00Z_bc000000-0000-0000-0000-000000000000_bc000000-0000-0000-0000-000000000001","limit": 1,"items": [{"id": "bc000000-0000-0000-0000-000000000000","orgId": "bc000000-0000-0000-0000-000000000001","groupId": "bc000000-0000-0000-0000-000000000002","offloadDeviceId": "bc000000-0000-0000-0000-000000000003","offloadDeviceTitle": "Edge 2 - Reader","objectId": "bc000000-0000-0000-0000-000000000004","objectTitle": "Sample User - p00000000002","objectDescription": "Sample User - p00000000002","objectStereotype": "person","objectTypeId": "bc000000-0000-0000-0000-000000000005","objectTypeTitle": "Personnel Tag","trackedDeviceId": "bc000000-0000-0000-0000-000000000006","trackedDeviceTitle": "D00000000002","contactId": "bc000000-0000-0000-0000-000000000007","contactTitle": "Sample User - p00000000001","contactDescription": "Sample User - p00000000001","contactStereotype": "person","contactTypeId": "bc000000-0000-0000-0000-000000000008","contactTypeTitle": "Personnel Tag","contactDeviceId": "bc000000-0000-0000-0000-000000000009","contactDeviceTitle": "d00000000001","createdAt": "2020-07-30T12:45:09Z","timestamp": "2020-01-01T09:00:00Z","exitTimestamp": "2020-01-01T09:00:10Z","durationSeconds": 10,"localTimezoneOffset": "+10:00","timestampConflict": false,"duplicateId": "bc000000-0000-0000-0000-000000000010","reportedByPrimary": true,"proximity": "Contact","timeout": false,"onCharge": false,"timeSyncIssue": false,"minimumDistance": 1,"boundaryDistance": 1,"startSequenceNumber": 0,"endSequenceNumber": 255,"placeId": null,"source": null,"placeTypeId": null,"placeTitle": null}]
}
Tag Contact Log – By Primary Contact
API Request Overview

 

Endpoint https://api.us.loop.bluecats.com/reports/logs/tagcontacts/{objectId}

Method

GET

Pagination Type

Next token

Description

Iterate through available logs by ordered by date (either log event timestamp – timestamp or log create/processed timestamp – createdAt

Headers

 
{'authorization': 'Bearer {access_token}','bc-loop-orgid': '{target_org_id}'
}

Example Query

 
https://api.us.loop.bluecats.com/reports/logs/tagcontacts/bc000000-0000-0000-0000-000000000006
?groupId=bc000000-0000-0000-0000-000000000002
&from=2020-02-14
&timestampField=createdAt
&sortByTimestampAscending=true
&next=xxxx
Request Parameters

Key

Attributes

Description

objectId

Path Parameter
Required
uuid

Filter by a primary contact (objectId)

groupId

Required
uuid

Filter by Group e.g. Site/Department etc.

from

Optional
default null
datetime ISO 8601 string

Starting timestamp to return events from

to

Optional
default null
datetime ISO 8601 string

when ‘to’ is specified then the results will be ascending, otherwise they will be descending.

limit

Optional
default 100
max 500
Int

Maximum number of results to return

next

Optional
default null
string

Continuation token to paginate through results. When this value is populated in the response, it can be passed to subsequent requests to retrieve additional events.

proximity

Optional
default null
string (Enumeration)

Nearby|Contact

duplicates

Optional
default false
bool

 

invalidEvents

Optional
default false
bool

When true the results will include the timeSync issues

contactId

Optional
default null
uuid

Filter by secondary contact

sortByTimestampAscending

Optional
default false
bool

 

minimumDurationSeconds

Optional
Default: N/A
Format: Int

Minimum contact duration to include for individual logs

objectStereotype

Optional
string

Filter results by the target object’s stereotype. Valid values are person, place anddevice

contactStereotype

Optional
string

Filter results by the target contact object’s stereotype. Valid values are person, place anddevice
Example Response Body

 


{"next": "2020-01-01T09:00:00Z_bc000000-0000-0000-0000-000000000000_bc000000-0000-0000-0000-000000000001","limit": 1,"items": [{"id": "bc000000-0000-0000-0000-000000000002","orgId": "bc000000-0000-0000-0000-000000000003","groupId": "bc000000-1000-0000-0000-000000000004","offloadDeviceId": "bc000000-0000-0000-0000-000000000005","offloadDeviceTitle": "Edge 2 - Reader","objectId": "bc000000-0000-0000-0000-000000000006","objectTitle": "Sample User - p00000000002","objectDescription": "Sample User - p00000000002","objectStereotype": "person","objectTypeId": "bc000000-0000-0000-0000-000000000007","objectTypeTitle": "Personnel Tag","trackedDeviceId": "bc000000-0000-0000-0000-000000000008","trackedDeviceTitle": "D00000000002","contactId": "bc000000-0000-0000-0000-000000000009","contactTitle": "Sample User - p00000000001","contactDescription": "Sample User - p00000000001","contactStereotype": "person","contactTypeId": "bc000000-0000-0000-0000-000000000010","contactTypeTitle": "Personnel Tag","contactDeviceId": "bc000000-0000-0000-0000-000000000011","contactDeviceTitle": "d00000000001","createdAt": "2020-07-30T12:45:09Z","timestamp": "2020-01-01T09:00:00Z","exitTimestamp": "2020-01-01T09:00:10Z","durationSeconds": 10,"localTimezoneOffset": "+10:00","timestampConflict": false,"duplicateId": "bc000000-0000-0000-0000-000000000012","reportedByPrimary": true,"proximity": "Contact","timeout": false,"onCharge": false,"timeSyncIssue": false,"minimumDistance": 1,"boundaryDistance": 1,"startSequenceNumber": 0,"endSequenceNumber": 255,"placeId": null,"source": null,"placeTypeId": null,"placeTitle": null}]
}

Contact Tracing Summary API

Overview

Tag Contacts are generated when two T2T tags enter within one of two ranges In Contact or Nearby. A Tag Contact Summary Log is a record summarising the time the cards spent in range of each other. To query the data, the user requires an active Bearer Token, organization id and group id, which can be obtained by the methods presented in the Token Generation API section above.

Tag Contact Summary Log – By Organization/Group
API Request Overview

 

Endpoint

/reports/summaries/tagcontacts

Method

GET

Headers

 
{'authorization': 'Bearer {access_token}','bc-loop-orgid': '{target_org_id}'
}

Pagination Type

limit/offset
request parameters

Key

Attributes

Description

groupId*

Required: True
Default: N/A
Format: UUID
Example: bc000000-0000-0000-0000-000000000000

Filter by a Group

from*

Required: True
Default: N/A
Format: datetime ISO 8601 string
Example: “2020-01-01”

Start date in local time

to*

Required: True
Default: N/A
Format: datetime ISO 8601 string
Example: “2020-01-01”

End date in local time

limit

Required: False
Default: 100
Format: Int
Limit: max 500

Maximum number of results to return

offset

Required: False
Default: 0
Format: int

Page offset. i.e. if limit = 10 and offset = 10, then returned results will start from 100th record

minimumTotalDurationSeconds

Required: False
Default: N/A
Format: Int

Minimum contact duration to include

proximity

Required: False
Default: Nearby
Format: string (Enumeration)
Example: “Nearby”

Nearby|Contact

groupbyPeriod

Required: False
Default: false
Format: bool

 

objectStereotype

Optional
string

Filter results by the target object’s stereotype. Valid values are person, place anddevice

contactStereotype

Optional
string

Filter results by the target contact object’s stereotype. Valid values are person, place anddevice
example response body

 


{"offset": 0,"limit": 1,"total": 1,"items": [{"orgId": "bc000000-0000-0000-0000-000000000000","groupId": "bc000000-0000-0000-0000-000000000001","objectId": "bc000000-0000-0000-0000-000000000002","objectTitle": "Samlpe A","objectTypeId": "bc000000-0000-0000-0000-000000000003","objectTypeTitle": "Person","localPeriodFrom": "2020-09-04","localPeriodTo": "2020-09-25","localTimezoneOffset": -5.0,"objectStereotype": "person","contactStereotype": "person","proximity": [{"proximity": "contact","totalDurationSeconds": 157518,"totalContacts": 17,"uniqueContacts": 5},{"proximity": "nearby","totalDurationSeconds": 157533,"totalContacts": 18,"uniqueContacts": 5}]}]
}
Tag Contact Summary Log – By Primary
API Request Overview

Endpoint

/reports/summaries/tagcontacts/{objectId}

Method

GET

Headers

 
{'authorization': 'Bearer {access_token}','bc-loop-orgid': 'bc000000-a1a1-b2b2-c3c3-d4d4e5e5f6'
}

Pagination Type

limit/offset
Request Parameters

Key

Attributes

Description

Id*

Path Parameter
Required
uuid

Filter by a primary contact (objectId)

groupId*

Required: True
Default: N/A
Format: UUID
Example: bc000000-0000-0000-0000-000000000000

Filter by a Group

contactId

Required: False
Default: N/A
Format: UUID
Example: bc000000-0000-0000-0000-000000000000

Filter by Secondary Contact ID

from

Required: True
Default: N/A
Format: datetime ISO 8601 string
Example: “2020-01-01T01:01:01”

Start date in local time

to

Required: True
Default: N/A
Format: datetime ISO 8601 string
Example: “2020-01-01T01:01:01”

End date in local time

limit

Required: False
Default: 100
Format: Int
Limit: max 500

Maximum number of results to return

offset

Required: False
Default: 0
Format: int

Page offset. i.e. if limit = 10 and offset = 10, then returned results will start from 100th record

minimumDurationSeconds

Required: False
Default: N/A
Format: Int

Minimum contact duration to include

proximity

Required: True
Default: Nearby
Format: string (Enumeration)
Example: “Nearby”

Nearby|Contact

groupbyPeriod

Required: False
Default: false
Format: bool

 

objectStereotype

Optional
string

Filter results by the target object’s stereotype. Valid values are person, place anddevice

contactStereotype

Optional
string

Filter results by the target contact object’s stereotype. Valid values are person, place anddevice
example response body

 

>

{"offset": 0,"limit": 1,"total": 1,"items": [{"orgId": "bc000000-0000-0000-0000-000000000000","groupId": "bc000000-0000-0000-0000-000000000001","objectId": "bc000000-0000-0000-0000-000000000002","objectTitle": "Samlpe A","objectTypeId": "bc000000-0000-0000-0000-000000000003","objectTypeTitle": "Person","localPeriodFrom": "2020-09-04","localPeriodTo": "2020-09-25","localTimezoneOffset": -5.0,"objectStereotype": "person","contactStereotype": "person","contactId": "bc000000-0000-0000-0000-000000000004","contactTitle": "Sample B","contactTypeId": "bc000000-0000-0000-0000-000000000005","contactTypeTitle": "Person","proximity": [{"proximity": "contact","totalDurationSeconds": 67,"totalContacts": 2,"uniqueContacts": 1},{"proximity": "nearby","totalDurationSeconds": 151,"totalContacts": 5,"uniqueContacts": 1}]}]
}

Navigation