Overview
The SPORTident Center REST API provides a minimal, simple and efficient interface to interact with SPORTident Center.
The API is currently in Beta, which means that it could still change in an incompatible way after we receive feedback and opinions from early adaptors. We will inform all current users, should the API change.
Using the API
Authentication
All requests to the API need to be authorised. The user authenticates with his or her API key via the HTTP header "apikey". The API key is available via the Center admin panel user settings.
Http Compression (GZIP)
We support HTTP compression on upload (POST method) and download (all methods,
but for content type application/json, text/xml and text/csv only, i.e. for the
REST and SOAP API). To upload gzip-compressed data to the server, the client
needs to set the header Content-Encoding: gzip
. To request a gzip-compressed
response, the client needs to set the header Accept-Encoding: gzip
. The
response may or may not be compressed (very small payloads are not gzipped),
which is indicated by whether the Content-Encoding: gzip
header is set in the
response, or not.
Resources
Events
Retrieve punches for an event
Resource URL
GET /api/rest/v1/public/events/{eventId}/punches
Description
Retrieve punches for an event. The event id is available via the Center admin
panel events page.
The punches can be retrieved as JSON or CSV formatted data, specified by the
Accept
header.
Filtering of the punches is possible with the query parameter afterId
as
listed below.
Typically, to retrieve punches "live" for a running event, you would poll the
REST API in a loop (e.g. every ten seconds), starting with afterId=0
(punch
ids are always greater than zero) and then increasing afterId to the so far
largest returned punch id in each iteration (the returned punches are ordered
ascending by punch id).
Simple punch format
Field | Description |
---|---|
id |
Uniquely identifies this punch |
card |
SPORTident card number (SIID) |
time |
Punch time (local time) in milliseconds since the Epoch (1970-01-01 00:00:00) |
code |
Control code |
mode |
Punch mode (e.g. Control, Start, Finish, BcControl, etc) |
Query parameters
Parameter | Description |
---|---|
|
(Optional) Get all punches after this id. |
|
(Optional) Return a maximum number of [limit] punches. Default is 50000. Largest possible value is 50000 as well. |
|
(Optional) Return punches in the specified punch format. Currently only "simple" is supported which is the default as well. |
Request headers
Name | Description |
---|---|
|
API key to authenticate the user |
|
Return punches in the specified format. Acceptable values are "application/json" and "text/csv". |
|
application/json;charset=UTF-8 |
Response headers
Name | Description |
---|---|
|
Returned number of punches, Total number of selected punches |
Examples
Curl request to get punches as JSON
$ curl 'https://center-origin.sportident.com/api/rest/v1/public/events/6/punches?afterId=7&projection=simple&limit=5' -i -X GET \
-H 'Accept: application/json' \
-H 'apikey: 9eda315c-4309-071f-c408-73652f25a807' \
-H 'Content-Type: application/json;charset=UTF-8'
Retrieve punches as JSON with parameter afterId
Request:
GET /api/rest/v1/public/events/6/punches?afterId=7&projection=simple&limit=5 HTTP/1.1
Accept: application/json
apikey: 9eda315c-4309-071f-c408-73652f25a807
Content-Type: application/json;charset=UTF-8
Host: center-origin.sportident.com
Response:
HTTP/1.1 200 OK
Vary: accept-encoding,origin,access-control-request-headers,access-control-request-method,accept-encoding
Set-Cookie: SESSION=ZmI3ZDE4ZDctZmVlMy00MGQ5LThhM2UtMjcwMzk3NmU2YTZi; Path=/; HttpOnly; SameSite=Lax
X-Frame-Options: DENY
X-Count: 5,95
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Content-Encoding: gzip
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Thu, 14 Jan 2021 20:11:39 GMT
Keep-Alive: timeout=60
Connection: keep-alive
Content-Length: 510
[ {
"id" : 8,
"card" : 8888893,
"time" : 1610658673808,
"code" : 49,
"mode" : "BcControl"
}, {
"id" : 9,
"card" : 8888894,
"time" : 1610658674812,
"code" : 50,
"mode" : "BcControl"
}, {
"id" : 10,
"card" : 8888895,
"time" : 1610658675816,
"code" : 51,
"mode" : "BcControl"
}, {
"id" : 11,
"card" : 8888896,
"time" : 1610658676820,
"code" : 52,
"mode" : "BcControl"
}, {
"id" : 12,
"card" : 8888897,
"time" : 1610658677824,
"code" : 53,
"mode" : "BcControl"
} ]
JSON access denied response
HTTP/1.1 403 Forbidden
Vary: accept-encoding,origin,access-control-request-headers,access-control-request-method,accept-encoding
Set-Cookie: SESSION=N2RlZDM2YzctOGZjNS00MjU0LWE0ZWMtZjI5OWM4OWNiZjhj; Path=/; HttpOnly; SameSite=Lax
X-Frame-Options: DENY
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Content-Encoding: gzip
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Thu, 14 Jan 2021 20:19:47 GMT
Keep-Alive: timeout=60
Connection: keep-alive
Content-Length: 406
{
"errors" : [ {
"entity" : "AccessDeniedException",
"cause" : "AccessDeniedException",
"message" : "User 'firstNametestuser2 lastNametestuser2' is not authorised to access event '130'",
"detailMessage" : "User 'firstNametestuser2 lastNametestuser2' is not authorised to access event '130'",
"url" : "https://center-origin.sportident.com/api/rest/v1/public/events/130/punches"
} ]
}
Retrieve punches as CSV
Request:
GET /api/rest/v1/public/events/6/punches?projection=simple&limit=5 HTTP/1.1
Accept: text/csv
apikey: 9eda315c-4309-071f-c408-73652f25a807
Host: center-origin.sportident.com
Response:
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
X-Count: 5,100
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Set-Cookie: SESSION=YWYxODU3YmQtZmI0My00ZDc5LTgzZWUtNTVlZGFiNjFkMDg5; Path=/; HttpOnly; SameSite=Lax
Content-Type: text/csv;charset=UTF-8
Content-Length: 208
Date: Thu, 14 Jan 2021 20:11:39 GMT
Keep-Alive: timeout=60
Connection: keep-alive
ID,CODE,CARD,TIME,MODE
3,44,8888888,1610658668789,BcControl
4,45,8888889,1610658669792,BcControl
5,46,8888890,1610658670796,BcControl
6,47,8888891,1610658671800,BcControl
7,48,8888892,1610658672804,BcControl