This guide explains how to use Spintly’s Visitor Management APIs.These APIs allow you to create meetings and generate the QR codes for the visitors allowing them to access the doors permitted. This apis are more additional apis to the type 1 and type 2 integrations. The following apis can coexists with type1 and type 2 apis or it also can work standalone

Before you get into the apis, please get yourself familiarize with the following terms

Epoch time

The Unix epoch (or Unix time or POSIX time or Unix timestamp) is the number of seconds that have elapsed since January 1, 1970 (midnight UTC/GMT), not counting leap seconds (in ISO 8601: 1970-01-01T00:00:00Z). Literally speaking the epoch is Unix time 0 (midnight 1/1/1970), but 'epoch' is often used as a synonym for Unix time. Some systems store epoch dates as a signed 32-bit integer, which might cause problems on January 19, 2038 (known as the Year 2038 problem or Y2038). The converter on this page converts timestamps in seconds (10-digit), milliseconds (13-digit) and microseconds (16-digit) to readable dates.

For more information about epoch time, you can refer to the below site

https://www.epochconverter.com/

Qr data

In the below apis whenever you do a booking or update existing booking, you will get qr data in response. With this qr data you have to build a qr code. In programming languages there are different libraries which allows you to generate the qr code. 

If you want to test it before you start implementing in you backend, you can go to the following site https://www.the-qrcode-generator.com/, the qr data which Spintly apis return needs to be put in the text field below, also make sure the format below is in plain text. Once the above is done, on the right you will get a qr code, this qr you can then show to the Spintly  qr readers.(provided the permissions are given to the door

Dynamic Expiry Timeout

There might be a time when a qr code can be shared with multiple people. This might cause a lot of people to misuse it and get unauthorized access. To Prevent this Spintly has come with something called dynamic expiry timeout, with this once a qrcode is generated from the qr data, it will be valid for 60 seconds. After that the qr data needs to be regenerated

Spintly Apis

Below are the sequence how the apis needs to be called

Following are the apis spintly provides

1. Ouath token api
2. Get sites
3. Get Access points
4. Create a meeting
5. Update an existing meeting
6. Regenerate qr
7. Delete meeting
8. Delete visitor

1. Ouath Api

Spintly uses oauth 2.0 client credential flow for authorization purpose, here in the api the client just has to put a clientid and clientSecret to get an access token, this access token can then be used to access other apis of Spintly.

2) Get Sites

This api is responsible for getting all the sites belonging to the organisation, As you can see in the diagram,If there multiple site, spintly provides pagination support also

3) Get Access points

This api is responsible for getting all the access points(doors), that belong to a particular site, like the previous site apis, Spintly provides pagination support if there multiple sites, also Spintly will provide filter support where user can search by access point names

3) Create a meeting

This api is responsible for creating a meeting, once the meeting is created it returns qrdata, using the qr data you can generate a qrcode, As see below when creating a meeting you need to specify the startTime and endTIme, also you need specify the door where the qr should work for the user, you will also have to pass a userid(this needs to be generated at your end) which uniquely identifies the visitor. In the response you will get a meetingId, visitorId and qrdata

4) Modifying the starttime and endtime of an existing  meeting

This api is responsible for updating the starttme and endTime of an existing meeting, just like the previous api, it will return a qrdata. please update the qrcode with the new qrdata

5) Modifying the access point permissions of an existing  meeting

This api is responsible for updating the permissions of an existing meeting, In permissionsToAdd you need to provide the new door permissions which the user was not given, if you want to remove permissions you can add the access point ids in  permissionsToRemove

possible combinations which can occur

If you want to remove a door and at the same time add a new door permissions, request body will look like below

If you want to just add permissions, request body will look like below

5) Regenerating qr data

This api is used to regenerate the qr data, this is mainly used whenever dynamic expiry timeout happens(mentioned in point 4) i.e. when 60 seconds has passed. So for the same booking you need to regenerate the qr data

5) Deleting a meeting

This api deletes the meeting whose id is specified in the url

6) Deleting a visitor

This api deletes the visitor and its associated meetings, please note mention the userid in the  url