NAV
curl

Introduction

Welcome to the SCTdb API!

SCTdb provides a simple and powerful REST API to integrate Contact Tracing into your application and provide a single centralized database for Canton access.

This API reference provides information on available endpoints and how to interact with it.

All request bodies should have content type application/json and be valid JSON.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

We're adding new Partners manually, please contact us at [email protected] to be added as Partner.

Current API URL

https://api.sctdb.ch/v1/

Authentication

Authentication is done via the API key which you can request via Email.

Requests are authenticated using Authorization Header. Provide your API key as a bearer token in an Authorization header.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

To authorize, send an Authorization header with a Bearer Token, like this:

curl 'https://api.sctdb.ch/v1/visits' \
        -H 'Authorization: Bearer {key}'

Data types

Phone number

Phone number will always be additionally preprocessed on a server side to make phone in an international format: - delete special characters: '(', ')', '\s', '\t'. - delete first 1 or 2 zeros - add '+' if not at the beginning.

After all, we get number in a format '^+\d{8,15}$'. If not, the request will be rejected.

Date

Should be in ISO 8601:2004 format (YYYY-MM-DD).

Datetime

Should be in ISO 8601:2004 format (YYYY-MM-DD hh:mm:ss) with a timezone. All datetime without timezone will be rejected.

Idempotent Requests

The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. This is useful when an API call is disrupted in transit and you do not receive a response. For example, if a request to create a visit does not respond due to a network connection error, you can retry the request with the same idempotency key to guarantee that no more than one visit is created.

Visits

Visit object represents a Social Presence of a Person in a specific Location at some specific time.

Create new Visit

If Location, Person or Area from request is not exist, it will be created, otherwise, non-mandatory fields will be updated. This endpoint is idempotent. If Visit with the same fields already exists, new entry will be not created. Identified by checked_in, checked_out, Person ref, Location Ref and Area Ref.

HTTP Request

POST https://api.sctdb.ch/v1/visits/

POST Parameters

Parameter Mandatory Type Description
checked_in false Datetime Check in time of the user.
checked_out false Datetime (Optional) Check out time of the user.
Person true Object Person object, that contains the personal data of the user.
Location true Object Location object, that contains the location data.
Area false Object Area object, that contains the area data.

If checked_in not set - will be set to NOW(). If checked_out not set - will be set later automatically by our algorithm.

curl https://api.sctdb.ch/v1/visits/ \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {key}' \
  -d '{
    "checked_in": "2020-10-22 15:54:05Z",
    "checked_out": "2020-10-22 16:54:15Z",
    "person": {
        "first_name": "Vadim",
        "last_name": "Kravcenko",
        "phone_number": "+4177123123",
        "address": "Hofackerstrasse 36",
        "email": "[email protected]",
        "zip_code": 8032,
        "birth_date": "1970-01-01"
    },
    "location": {
        "name": "Mindnow Bistro",
        "phone_number": "+4177123123",
        "email": "[email protected]",
        "zip_code": 8037,
        "address": "Okenstrasse 7",
        "city": "Zurich",
        "canton": "CH_ZH",
        "country: "CH"
    },
    "area": {
      "name": "Table #1"
    }
}'

The above command returns JSON structured like this:

{
    "uuid": "37e8e1b7-8d7b-4bea-9e99-cd2f89f13027",
    "checked_in": "2020-10-22T15:54:05+00:00",
    "checked_out": "2020-10-22T16:54:15+00:00",
    "person": {
        "uuid": "06e7987e-6049-4c9b-a296-cad4461c7906",
        "first_name": "Vadim",
        "last_name": "Kravcenko",
        "phone_number": "+4177123123",
        "address": "Hofackerstrasse 36",
        "zip_code": 8032
    },
    "location": {
        "uuid": "8985c145-d905-4de9-8093-d10d832dfb95",
        "name": "Mindnow Bistro",
        "address": "Okenstrasse 7",
        "city": "Zurich",
        "zip_code": 8037,
        "canton": "CH_ZH",
        "phone_number": "+4177123123",
        "email": "[email protected]"
    },
    "source": {
        "uuid": "60549fd0-5cc3-11eb-ae93-0242ac130002",
        "name": "Partner Name"
    }
}

Locations

Location represents a physical place where the Social Interactions occured. A location can be a Bar, a Restaurant, a Private-Party or a spontaneous meeting between friends. To distinguish locations from one another and also group visits from different partners to correct locations we identify the location by phone_number, address, name and city.

Create new Location

We identify the location by the combination of Phone number, Address, City and Name. These fields are mandatory and immutable after saving.

HTTP Request

POST https://api.sctdb.ch/v1/locations/

POST Parameters

Parameter Mandatory Type Description
phone_number true String Location Phone number e.g. +4177123123
address true String Location address e.g. Okenstrasse 7
zip_code true Integer Location ZIP-Code e.g. 8037
name false String Name of the location
email false String Email of the location
city false String City of the location
country false ENUM Country
canton false ENUM Canton. e.g. CH_ZH, CH_BE
curl https://api.sctdb.ch/v1/locations/ \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer 1b6570068f56603152229527255e3027590c79bd63595c0f994fb1d32ec061fdd80cc424f5dd3e31da85b4d196e391ea33be567d52608384e8d4ccce00b0b197' \
  -d '{
    "name": "Mindnow Bistro",
    "phone_number": "+41771231234",
    "email": "[email protected]",
    "zip_code": 8037,
    "address": "Okenstrasse 7",
    "city": "zurich",
    "canton": "CH_ZH",
    "country": "CH"
}'

The above command returns JSON structured like this:

{
    "uuid": "fc4fb82c-1cc8-499c-8913-e4d52782625c",
    "name": "Mindnow Bistro",
    "address": "Okenstrasse 7",
    "city": "zurich",
    "zip_code": "8037",
    "phone_number": "+41771231234",
    "email": "[email protected]"
}

Update Location

You can only update non-mandatory fields. Fields used to identify location are immutable.

HTTP Request

PATCH https://api.sctdb.ch/v1/locations/<ID>/

URL Parameters

Parameter Description
ID The UUID of the Location which we want to update

PATCH Parameters

Parameter Mandatory Type Description
email false String Email of the location
zip_code false String City of the location
canton false ENUM Canton. e.g. CH_ZH, CH_BE
country false ENUM Country
curl https://api.sctdb.ch/v1/locations/fc4fb82c-1cc8-499c-8913-e4d52782625c \
  -X PATCH \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {key}' \
  -d '{
    "email": "[email protected]",
    "zip_code": 8036,
    "canton": "CH_ZH"
}'

The above command returns JSON structured like this:

{
    "uuid": "fc4fb82c-1cc8-499c-8913-e4d52782625c",
    "name": "Mindnow Bistro",
    "address": "Okenstrasse 7",
    "city": "zurich",
    "zip_code": 8036,
    "phone_number": "+41771231234",
    "email": "[email protected]"
}

Area

This is a part of Location. For example, table in restaurant or cinema hall.

Create Area

HTTP Request

POST https://api.sctdb.ch/v1/locations/<ID>/areas/

URL Parameters

Parameter Description
ID The UUID of the Location to which Area belongs

POST Parameters

Parameter Mandatory Type Description
name true String Area name
curl https://api.sctdb.ch/v1/locations/fc4fb82c-1cc8-499c-8913-e4d52782625c/areas/ \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {key}' \
  -d '{
    "name": "Table 1"
}'

> The above command returns JSON structured like this:

```json
{
    "uuid": "07a85eee-2159-4026-a88a-01d02936687e",
    "source": {
        "uuid": "60549fd0-5cc3-11eb-ae93-0242ac130002",
        "name": "Partner Name"
    },
    "location": "fc4fb82c-1cc8-499c-8913-e4d52782625c",
    "name": "Table 1"
}

People

A Person object represents an individual who is performing the Social Interaction and who needs to be tracked. A unique Person is identified by First Name, Last Name and a Phone Number. This allows us to receive data from different providers and still identify the person successfully.

Create Person

HTTP Request

POST https://api.sctdb.ch/v1/people/

POST Parameters

Parameter Mandatory Type Description
first_name true String First Name
last_name true String Last Name
phone_number true String Phone number e.g. +4177123123
birth_date false Date Birthdate of the user e.g. 1970-01-01
phone_number false String Phone number e.g. +4177123123
address false String Location address e.g. Okenstrasse 7
zip_code false Integer ZIP-Code e.g. 8037
email false String Email
curl https://api.sctdb.ch/v1/people/ \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {key}' \
  -d '{
    "first_name": "Vadim",
    "last_name": "Kravcenko",
    "phone_number": "+4171234123",
    "address": "Hofackerstrasse 37",
    "email": "[email protected]",
    "zip_code": "8032",
    "birth_date": "1989-01-01"
}'

> The above command returns JSON structured like this:

```json
{
    "uuid": "c0688109-1aa4-45c0-882c-e007f89440dc",
    "first_name": "Vadim",
    "last_name": "Kravcenko",
    "phone_number": "+4171234123",
    "address": "Hofackerstrasse 37",
    "zip_code": "8032"
}

Update Person

You can only update a person created by your Partner ID. Deleting/Removing fields is not allowed, you can only expand missing information of a user or edit not mandatory fields.

HTTP Request

PATCH https://api.sctdb.ch/v1/people/<ID>/

URL Parameters

Parameter Description
ID The UUID of the Person who we want to update

PATCH Parameters

Parameter Mandatory Type Description
birth_date false Date Birth date of the user e.g. 1970-01-01
phone_number false String Phone number e.g. +4177123123
address false String Location address e.g. Okenstrasse 7
zip_code false Integer ZIP-Code e.g. 8037
email false String Email
curl https://api.sctdb.ch/v1/people/c0688109-1aa4-45c0-882c-e007f89440dc/ \
  -X PATCH \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {key}' \
  -d '{
    "address": "Hofackerstrasse 37",
    "email": "[email protected]",
    "zip_code": "8033",
    "birth_date": "1989-01-01"
}'

> The above command returns JSON structured like this:

```json
{
    "uuid": "c0688109-1aa4-45c0-882c-e007f89440dc",
    "first_name": "Vadim",
    "last_name": "Kravcenko",
    "phone_number": "+4171234123",
    "address": "Hofackerstrasse 37",
    "zip_code": "8033"
}

Models

Visit Model

Attribute Type Description
checked_in Datetime Time of the checkin
checked_out Datetime Time of the checkout
Person Reference Reference to the person who performed the Checkin
Location Reference Reference to the location where the checkin was performed
Area Reference Reference to the area where the checkin was performed
Source Reference Reference to the Partner who sent the Checkin

Person Model

Attribute Type Description
first_name String First Name
last_name String Last Name
phone_number String Phone number e.g. +4177123123
birth_date Date Birthdate of the user e.g. 1970-01-01
phone_number String Phone number e.g. +4177123123
address String Location address e.g. Okenstrasse 7
zip_code Integer ZIP-Code e.g. 8037
email String Email

Area Model

Attribute Type Description
name String Area name

Location Model

Attribute Type Description
phone_number String Location Phone number e.g. +4177123123
address String Location address e.g. Okenstrasse 7
zip_code Integer Location ZIP-Code e.g. 8037
name String Name of the location
email String Email of the location
city String City of the location
country false ENUM
canton false ENUM

Country

ISO_3166-1

Attribute Description
CH Switzerland
LI Liechtenstein

Cantons

ISO_3166-2 administrative units Switzerland - CH Liechtenstein - LI

Attribute Description
CH_AG Aargau
CH_AR Appenzell Ausserrhoden
CH_AI Appenzell Innerrhoden
CH_BL Basel-Landschaft
CH_BS Basel-Stadt
CH_BE Bern
CH_FR Freiburg
CH_GE Geneva
CH_GL Glarus
CH_GR Graubünden
CH_JU Jura
CH_LU Luzern
CH_NE Neuchâtel
CH_NW Nidwalden
CH_OW Obwalden
CH_SG St. Gallen
CH_SH Schaffhausen
CH_SZ Schwyz
CH_SO Solothurn
CH_TG Thurgau
CH_TI Tessin
CH_UR Uri
CH_VS Wallis
CH_VD Vaud
CH_ZG Zug
CH_ZH Zurich
LI_01 Balzers
LI_02 Eschen
LI_03 Gamprin
LI_04 Mauren
LI_05 Planken
LI_06 Ruggell
LI_07 Schaan
LI_08 Schellenberg
LI_09 Triesen
LI_10 Triesenberg
LI_11 Vaduz
NOT_SET Keine Angabe

Errors

The SCTdb API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- Your Partner Bearer Token is invalid or you don't have access
404 Not Found -- The specified API could not be found.
405 Method Not Allowed -- You tried to access a resource with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.