Center REST API

The SPORTident Center REST API provides a simple and efficient interface to interact with SPORTident Center.

Access the Center API at https://center-origin.sportident.com. SPORTident Center itself is available at https://center.sportident.com.

Getting started

Example: API version

Use the versions endpoint as the starting point with the Center API. You can also simply paste the endpoint URL into a webbrowser to get the response.

HTTP verbs

Verb	Usage
`GET`	Used to retrieve a resource.
`POST`	Used to create a new resource. This includes requests for starting a process, for submitting a web form, and other types of requests that are generally not idempotent.
`PUT`	Used to create a new resource or replace an existing resource. Some requests allow partial updates. PUT requests are idempotent.
`DELETE`	Used to delete an existing resource.

HTTP status codes

Status code	Usage
`200 OK`	The request has completed successfully.
`201 Created`	A new resource has been created successfully. The resource’s URI is available from the response’s `Location` header.
`202 Accepted`	The request has been accepted for processing, but processing is not yet completed. The response includes the ID of the asynchronous task in the `X-Async-Task-Id` header for checking the progress of the task. The task is not guaranteed to complete successfully.
`204 No Content`	An update to an existing resource has been applied successfully. The response does not include any payload.
`400 Bad Request`	The request was malformed or contains invalid data. The response body includes further information on the error.
`401 Unauthorized`	An invalid access token was provided in the request. The response body includes further information on the error.
`402 Payment Required`	The action could not be completed because it requires a valid subscription or payment.
`403 Access Denied`	Access to the requested resource has been denied. The response body includes further information on the error.
`404 Not Found`	The requested resource does not exist.
`405 Method Not Allowed`	The request method is not allowed for this API endpoint.
`406 Not Acceptable`	The requested resource is generating content that is not acceptable according to the `Accept` header sent in the request.
`410 Gone`	The requested resource no longer exists.
`415 Unsupported Media Type`	The media type of the request is not supported.

HTTP compression

SPORTident Center supports HTTP compression on upload (POST method) and download (for all methods, but only for content-type “application/json”, “text/xml” and “text/csv”).

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 may set the header Accept-Encoding: gzip. The response may or may not be compressed, which is indicated by whether the Content-Encoding: gzip header is set in the response or not. Very small payloads are not compressed.

Retrieve punches

Resource URL

GET /api/rest/v1/punches

Description

Retrieve punches (timing records). These punches are typically uploaded to Center from LTE Modems or the Mobile Reader App. Punches can be retrieved in json and csv format. Up to 1000 punches are returned with one request.

We strongly recommend to always use the parameters after and afterId.

The typical use case for retrieving live punches looks like this:

Request punches with the filter set to modem, user or eventId, or a combination of those. Set after to your event zero time (e.g. 00:00:00 of the event date) and afterId to 0.
Process the response, keep note of the latest id
Request punches with the same parameters again, only with afterId now set to the latest id from the last response — you will only receive new punches since your last request
Repeat, with afterId always being set to the latest id you previously received

Please also refer to example 1 and example 2 below for an illustration of what this typical use case can look like.

We use milliseconds since the Epoch (1970-01-01 00:00:00) as the time format. As an example, with Bash you can convert time formats as follows:

# Convert from ms since epoch to a human readable format
$ DATETIME_IN_MS_SINCE_EPOCH="1739890563835"
$ date -d @$(echo "${DATETIME_IN_MS_SINCE_EPOCH} / 1000" | bc) +"%Y-%m-%dT%H:%M:%SZ"
2025-02-18T15:56:03Z

# Convert from a human readable format to ms since epoch
$ DATETIME_HUMAN_READABLE="2025-02-01T00:00:00Z"
$ date -d "${DATETIME_HUMAN_READABLE}" +%s%3N
1738368000000

And here’s the same example with Powershell:

# Convert from ms since epoch to a human readable format
$ $datetimeInMsSinceEpoch = 1739890563835
$ $epoch = [datetime]'1970-01-01T00:00:00Z'
$ $epoch.AddMilliseconds($datetimeInMsSinceEpoch).ToString("yyyy-MM-ddTHH:mm:ssZ")
2025-02-18T15:56:03Z

# Convert from a human readable format to ms since epoch
$ $datetimeHumanReadable = Get-Date "2025-02-01T00:00:00Z"
$ $epoch = [datetime]'1970-01-01T00:00:00Z'
$ ($datetimeHumanReadable - $epoch).TotalMilliseconds
1738368000000

Query parameters

Parameter	Description
`modem`	List of modem serial numbers (strings), separated by comma
`eventId`	One single event. Event id.
`user`	A single user. Username. (Refers to the modem user, not the modem owner.)
`afterId` (optional)	Get all punches after (`>`) this id
`after` (optional)	Return punches after (`>=`) this punch time (local time) in milliseconds since the Epoch (1970-01-01 00:00:00)

Only one of the three parameters modem, eventId, and user needs to be provided. All other parameters are optional.

Request headers

Name	Description
`Accept`	Requested format: `application/json` (default, if header is omitted) or `text/csv`

Response headers

Name	Description
`X-Total-Count`	Total number of matching punches

Response format

Field	Description
`id`	Punch id. Unsigned integer and always greater than zero.
`card`	Card number. String.
`time`	Punch time (local time) in milliseconds since the Epoch (1970-01-01 00:00:00).
`code`	Control code. Unsigned integer.
`type`	Punch type. String. Supported values: “Unknown”, “Control”, “Start”, “Finish”, “Check”, “Clear”. Additional values might be added in the future.
`modem`	Modem number. String.
`receptionTimeUtc`	Time when Center received the punch. UTC time, in milliseconds since the Epoch (1970-01-01 00:00:00).

Examples

Example 1

Curl request

$ curl 'https://center-origin.sportident.com/api/rest/v1/punches?modem=9000061,9000062&after=1739833200000&afterId=0' \
  -i -X GET -H 'Accept: text/csv'

HTTP request

GET /api/rest/v1/punches?modem=9000061,9000062&after=1739833200000&afterId=0 HTTP/2
Host: center-origin.sportident.com
Accept: text/csv

HTTP response

HTTP/2 200
content-type: text/csv;charset=UTF-8
x-total-count: 52

id,card,time,code,type,modem,receptionTimeUtc
5985523,8632419,1739890563835,66,Unknown,9000061,1739886956000
5985524,8632419,1739890592902,67,Unknown,9000062,1739886980000
5985525,8632416,1739890611000,1,Unknown,9000061,1739887006000
5985526,8632416,1739880900027,2,Unknown,9000061,1739887006000
5985527,8632416,1739890613671,66,Unknown,9000061,1739887015000
5985528,8632416,1739890633558,67,Unknown,9000062,1739887021000
5986145,8527495,1740585637289,31,Control,9000062,1740582035000
5986156,8527495,1740586132187,31,Control,9000061,1740582530000
5986157,16777215,1740589993531,33,Control,9000061,1740582835000
5986158,16777215,1740589998960,33,Control,9000061,1740582841000
5986159,16777215,1740590026863,33,Control,9000061,1740582869000
5986160,16777215,1740590037386,33,Control,9000061,1740582879000
5986161,16777215,1740590044304,33,Control,9000061,1740582886000
5986162,16777215,1740590048953,33,Control,9000061,1740582892000
5986163,16777215,1740590058835,33,Control,9000061,1740582900000
5986164,16777215,1740590065527,33,Control,9000061,1740582907000
5986165,16777215,1740590071902,33,Control,9000061,1740582913000
5986166,16777215,1740590083226,33,Control,9000061,1740582926000
5986167,16777215,1740590098324,33,Control,9000061,1740582940000
5986168,16777215,1740590109171,33,Control,9000061,1740582952000
5986169,16777215,1740590128562,33,Control,9000061,1740582993000
5986170,16777215,1740590134164,33,Control,9000061,1740582993000
5986171,16777215,1740590144687,33,Control,9000061,1740582993000
5986665,63371,1740829374980,3,Unknown,9000061,1740825774000
5986666,63371,1740829398101,31,Unknown,9000061,1740825800000
5986667,63371,1740829400769,109,Unknown,9000061,1740825802000
5986668,63371,1740829431527,4,Unknown,9000061,1740825828000
5986669,57905,1740829627605,3,Unknown,9000061,1740826027000
5986670,1407566,1740829632429,3,Unknown,9000061,1740826032000
5986671,8635492,1740829665402,3,Unknown,9000061,1740826064000
5986672,224502,1740830061218,3,Unknown,9000061,1740826461000
5986673,8635492,1740830145386,31,Control,9000061,1740826546000
5986674,57905,1740830260812,31,Unknown,9000061,1740826663000
5986675,1407566,1740830319574,31,Unknown,9000061,1740826722000
5986676,8635492,1740830332410,109,Control,9000061,1740826734000
5986677,57905,1740830358355,109,Unknown,9000061,1740826760000
5986678,251791,1740830595359,3,Unknown,9000061,1740826995000
5986679,8635492,1740830616937,100,Control,9000061,1740827016000
5986680,8635492,1740830657722,4,Finish,9000061,1740827054000
5986681,224502,1740830706257,31,Unknown,9000061,1740827108000
5986682,224502,1740831213984,109,Unknown,9000061,1740827616000
5986683,251791,1740831272250,31,Unknown,9000061,1740827674000
5986684,57905,1740831301976,4,Unknown,9000061,1740827698000
5986685,253066,1740831655847,3,Unknown,9000061,1740828055000
5986686,224502,1740832081558,4,Unknown,9000061,1740828477000
5986687,1407566,1740832112136,109,Unknown,9000061,1740828514000
5986688,251791,1740832573351,109,Unknown,9000061,1740828976000
5986689,253066,1740832599542,31,Unknown,9000061,1740829001000
5986690,253066,1740832821960,109,Unknown,9000061,1740829224000
5986691,1407566,1740833032843,4,Unknown,9000061,1740829429000
5986692,253066,1740833146835,4,Unknown,9000061,1740829543000
5986693,251791,1740833244988,4,Unknown,9000061,1740829641000

Example 2

Curl request

$ curl 'https://center-origin.sportident.com/api/rest/v1/punches?modem=9000061,9000062&after=1739833200000&afterId=5986693' \
  -i -X GET -H 'Accept: text/csv'

HTTP request

GET /api/rest/v1/punches?modem=9000061,9000062&after=1739833200000&afterId=5986693 HTTP/2
Host: center-origin.sportident.com
Accept: text/csv

HTTP response

HTTP/2 200
content-type: text/csv;charset=UTF-8
x-total-count: 0

id,card,time,code,type,modem,receptionTimeUtc

Example 3

Curl request

$ curl 'https://center-origin.sportident.com/api/rest/v1/punches?user=burkhard&after=1738364400000&afterId=0' \
  -i -X GET -H 'Accept: text/csv'

HTTP request

GET /api/rest/v1/punches?user=burkhard&after=1738364400000&afterId=0 HTTP/2
Host: center-origin.sportident.com
Accept: text/csv

HTTP response

HTTP/2 200
content-type: text/csv;charset=UTF-8
x-total-count: 6

id,card,time,code,type,modem,receptionTimeUtc
5985523,8632419,1739890563835,66,Unknown,9000061,1739886956000
5985524,8632419,1739890592902,67,Unknown,9000062,1739886980000
5985525,8632416,1739890611000,1,Unknown,9000061,1739887006000
5985526,8632416,1739880900027,2,Unknown,9000061,1739887006000
5985527,8632416,1739890613671,66,Unknown,9000061,1739887015000
5985528,8632416,1739890633558,67,Unknown,9000062,1739887021000

Example 4

Curl request

$ curl 'https://center-origin.sportident.com/api/rest/v1/punches?eventId=15078&modem=9000041&afterId=0' \
  -i -X GET -H 'Accept: application/json'

HTTP request

GET /api/rest/v1/punches?eventId=15078&modem=9000041&afterId=0 HTTP/2
Host: center-origin.sportident.com
Accept: application/json

HTTP response

HTTP/2 200
content-type: application/json;charset=UTF-8
x-total-count: 4

[{"id":5955277,"card":2091631,"time":1732056641453,"code":31,"type":"Unknown","modem":"9000041","receptionTimeUtc":1732049416000},{"id":5955278,"card":8770570,"time":1732097328835,"code":51,"type":"Unknown","modem":"9000041","receptionTimeUtc":1732093731000},{"id":5955279,"card":8770570,"time":1732097483386,"code":51,"type":"Unknown","modem":"9000041","receptionTimeUtc":1732093885000},{"id":5955280,"card":2228404,"time":1732101135195,"code":31,"type":"Unknown","modem":"9000041","receptionTimeUtc":1732093910000}]

Versions

Resource URL

GET /api/rest/v1/public/versions

Description

Get the internal and public version of the Center API.

Request headers

Name	Description
`Accept`	Requested format: `application/json` (default, if header is omitted)

Response format

Field	Description
`internalApiVersion`	Internal API version.
`publicApiVersion`	Public API version. For breaking changes, the major version will increase.

Examples

Example 1

Curl request

$ curl 'https://center-origin.sportident.com/api/rest/v1/public/versions' \
  -i -X GET -H 'Accept: application/json'

HTTP request

GET /api/rest/v1/public/versions HTTP/2
Host: center-origin.sportident.com
Accept: application/json

HTTP response

HTTP/2 200
content-type: application/json;charset=UTF-8

{"internalApiVersion":"12.5.0+40fb32c09.20250214170519","publicApiVersion":"0.1.0"}