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 (by clicking edit on the event of interest). The punches can be returned as JSON or CSV formatted data, as specified by the Accept header.

Filtering of the punches is possible with the query parameters 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), setting before and after if required (e.g. to the current day), 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

afterId

(Optional) Get all punches after this id.

before

(Optional) Get all punches before this punch time given as the number of milliseconds since 1970-01-01 00:00:00

after

(Optional) Get all punches after this punch time given as the number of milliseconds since 1970-01-01 00:00:00

projection

(Optional) Return punches in the specified punch format. Currently only "simple" is supported which is the default as well.

limit

(Optional) Return a maximum number of [limit] punches. Default is 10,000. Largest possible value is 10,000 as well.

Request headers
Name Description

apikey

API key to authenticate the user

Accept

Return punches in the specified format. Acceptable values are "application/json" and "text/csv".

Content-Type

application/json;charset=UTF-8

Response headers
Name Description

X-Count

Returned number of punches, Total number of selected punches

Examples
Curl request to get punches as JSON
$ curl 'https://center.sportident.com/api/rest/v1/public/events/254/punches?afterId=607&projection=simple&limit=5' -i -X GET \
    -H 'apikey: a12a84cb-cd0f-3468-64bc-d10a154c0f59' \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json;charset=UTF-8'
Retrieve punches as JSON with parameter afterId

Request:

GET /api/rest/v1/public/events/254/punches?afterId=607&projection=simple&limit=5 HTTP/1.1
apikey: a12a84cb-cd0f-3468-64bc-d10a154c0f59
Accept: application/json
Host: center.sportident.com
Content-Type: application/json;charset=UTF-8

Response:

HTTP/1.1 200 OK
Pragma: no-cache
X-Count: 5,95
X-Frame-Options: DENY
Content-Length: 517
Date: Mon, 08 Apr 2019 19:27:09 GMT
Transfer-Encoding: chunked
Content-Encoding: gzip
X-XSS-Protection: 1; mode=block
Expires: 0
vary: accept-encoding
X-Content-Type-Options: nosniff
Content-Type: application/json;charset=UTF-8
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Set-Cookie: JSESSIONID=A065776FA80A0E4D90B9E487C7A3159B; Path=/; HttpOnly

[ {
  "id" : 608,
  "card" : 8888893,
  "time" : 1554758803457,
  "code" : 49,
  "mode" : "BcControl"
}, {
  "id" : 609,
  "card" : 8888894,
  "time" : 1554758804460,
  "code" : 50,
  "mode" : "BcControl"
}, {
  "id" : 610,
  "card" : 8888895,
  "time" : 1554758805464,
  "code" : 51,
  "mode" : "BcControl"
}, {
  "id" : 611,
  "card" : 8888896,
  "time" : 1554758806468,
  "code" : 52,
  "mode" : "BcControl"
}, {
  "id" : 612,
  "card" : 8888897,
  "time" : 1554758807472,
  "code" : 53,
  "mode" : "BcControl"
} ]
Retrieve punches as JSON with parameters before and after

Request:

GET /api/rest/v1/public/events/254/punches?after=1554758803457&before=1554758894820&projection=simple&limit=5 HTTP/1.1
apikey: a12a84cb-cd0f-3468-64bc-d10a154c0f59
Accept: application/json
Host: center.sportident.com
Content-Type: application/json;charset=UTF-8

Response:

HTTP/1.1 200 OK
Pragma: no-cache
X-Frame-Options: DENY
Content-Length: 517
Date: Mon, 08 Apr 2019 19:27:09 GMT
Transfer-Encoding: chunked
Content-Encoding: gzip
X-XSS-Protection: 1; mode=block
Expires: 0
vary: accept-encoding
X-Content-Type-Options: nosniff
Set-Cookie: JSESSIONID=D2658645C3A0D06E769674C87EC656B1; Path=/; HttpOnly
Content-Type: application/json;charset=UTF-8
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
X-Count: 5,90

[ {
  "id" : 609,
  "card" : 8888894,
  "time" : 1554758804460,
  "code" : 50,
  "mode" : "BcControl"
}, {
  "id" : 610,
  "card" : 8888895,
  "time" : 1554758805464,
  "code" : 51,
  "mode" : "BcControl"
}, {
  "id" : 611,
  "card" : 8888896,
  "time" : 1554758806468,
  "code" : 52,
  "mode" : "BcControl"
}, {
  "id" : 612,
  "card" : 8888897,
  "time" : 1554758807472,
  "code" : 53,
  "mode" : "BcControl"
}, {
  "id" : 613,
  "card" : 8888898,
  "time" : 1554758808476,
  "code" : 54,
  "mode" : "BcControl"
} ]
JSON access denied response
HTTP/1.1 403 Forbidden
Pragma: no-cache
X-Frame-Options: DENY
Date: Mon, 08 Apr 2019 19:28:30 GMT
Content-Length: 346
Transfer-Encoding: chunked
Content-Encoding: gzip
X-XSS-Protection: 1; mode=block
Set-Cookie: JSESSIONID=5A4718386788B9117A3E1987938AD76A; Path=/; HttpOnly
Expires: 0
vary: accept-encoding
X-Content-Type-Options: nosniff
Content-Type: application/json;charset=UTF-8
Cache-Control: no-cache, no-store, max-age=0, must-revalidate

{
  "errors" : [ {
    "entity" : "AccessDeniedException",
    "cause" : "AccessDeniedException",
    "message" : "User 'firstNametestuser2 lastN",
    "detailMessage" : "User 'firstNametestuser2 lastNametestuser2' is not authorised to access event '426'",
    "url" : "https://center.sportident.com/api/rest/v1/public/events/426/punches"
  } ]
}
Retrieve punches as CSV

Request:

GET /api/rest/v1/public/events/254/punches?projection=simple&limit=5 HTTP/1.1
apikey: a12a84cb-cd0f-3468-64bc-d10a154c0f59
Host: center.sportident.com
Accept: text/csv

Response:

HTTP/1.1 200 OK
Pragma: no-cache
X-XSS-Protection: 1; mode=block
Expires: 0
X-Frame-Options: DENY
Content-Length: 218
X-Content-Type-Options: nosniff
Set-Cookie: JSESSIONID=D67064798161D406AD2BA5B38E4F21C2; Path=/; HttpOnly
Date: Mon, 08 Apr 2019 19:27:09 GMT
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
X-Count: 5,100
Content-Type: text/csv;charset=UTF-8

ID,CODE,CARD,TIME,MODE
603,44,8888888,1554758798437,BcControl
604,45,8888889,1554758799441,BcControl
605,46,8888890,1554758800445,BcControl
606,47,8888891,1554758801449,BcControl
607,48,8888892,1554758802453,BcControl