This website has been mostly translated automatically from the original version. We apologize for any translation errors.

APIs

The Kibitz backend system consists of several services, each providing independent JSON-RPC APIs:

  • An Appointments API that stores encrypted contact data, publishes hashes, and accepts visit data.
  • A storage API that (optionally) stores encrypted user and provider settings.

The following sections describe the methods offered by the APIs.

Appointments API

The Appointments API provides the essential functionality for appointment scheduling.

getStats()

Returns various public statistics related to the system.

Parameter

getStats

  • id
    enum < queues, tokens >

    ID of the statistics to return.

  • type
    enum < minute, hour, day, quarterHour, week, month >

    Time window type of the statistics to return.

  • name
    optional regex (^[\w\d\-]{0,50}$)

    Optional name of the statistics to return.

  • metric
    optional regex (^[\w\d\-]{0,50}$)

    Optional sub-metric to return.

  • filter
    optional map<string>any

    Optional additional filter criteria to apply.

  • from
    optional time (rfc3339)

    Earliest date for which to return statistics. Only applicable if 'n' is not set.

  • to
    optional time (rfc3339)

    Latest date for which to return statistics. Only applicable if 'n' is not set.

  • n
    optional integer (1 ⇹ 500)

    Maximum number of statistics values to return.

Return type

list map<string>any ᐉ statsValue

Related forms

statsValue

  • name
    string

    Name of the statistics value.

  • from
    time (rfc3339)

    Beginning of the time window of the statistics value.

  • to
    time (rfc3339)

    End of the time window of the statistics value.

  • data
    optional map<string>any

    Data associate with the statistics value.

  • value
    integer

    The statistics value itself.

getKeys()

Returns various required public keys. Please note that you should have an independent verification mechanism for these keys and not blindly trust the ones provided by this API.

Parameter

getKeys

This form has no fields.

Return type

map<string>any ᐉ keys

Related forms

keys

  • providerData
    bytes (base64 • 64 ⇹ 128)

    Public provider data key.

  • rootKey
    bytes (base64 • 64 ⇹ 128)

    Public root key.

  • tokenKey
    bytes (base64 • 64 ⇹ 128)

    Public token key.

getAppointmentsByZipCode()

Returns available appointments for a given zip code area.

Parameter

getAppointmentsByZipCode

  • radius
    optional (50) integer (5 ⇹ 80)

    The radius around the given zip code for which to show appointments.

  • zipCode
    string (5 ⇹ 5)

    The zip code to use as the user location.

  • from
    time (rfc3339)

    The earliest date of appointments to return.

  • to
    time (rfc3339)

    The latest date of appointments to return.

  • aggregate
    optional bool

    Whether to return aggregate data instead of actual appointments.

Return type

list map<string>any ᐉ providerAppointments

Related forms

appointmentData

  • timestamp
    time (rfc3339)

    A timestamp.

  • duration
    integer (5 ⇹ 300)

    Duration of the appointment.

  • properties
    map<string>any ᐉ appointmentProperties

    Properties of the appointment.

  • publicKey
    bytes (base64 • 64 ⇹ 128)

    An ECDSA or ECDH public key.

  • id
    bytes (base64 • 32 ⇹ 32)

    An ID.

  • slotData
    list map<string>any ᐉ slot

    Appointment slots.

appointmentProperties

  • vaccine
    enum < biontech, moderna, astrazeneca, johnson-johnson >

    The vaccine type used.

booking

  • id
    bytes (base64 • 32 ⇹ 32)

    An ID.

  • publicKey
    bytes (base64 • 64 ⇹ 128)

    An ECDSA or ECDH public key.

  • token
    bytes (base64 • 32 ⇹ 32)

    The token used for this booking.

  • encryptedData
    map<string>any ᐉ ecdhEncryptedData

    Encrypted data for the provider.

ecdhEncryptedData

  • iv
    bytes (base64 • 10 ⇹ 20)

    IV value associated with the encrypted data.

  • data
    bytes (base64 • 1 ⇹ 200000)

    The encrypted data.

  • publicKey
    bytes (base64 • 64 ⇹ 128)

    An ECDSA or ECDH public key.

providerAppointments

providerData

  • name
    string

    Name of the provider.

  • street
    string

    Street address of the provider.

  • city
    string

    City of the provider.

  • zipCode
    string

    Zip code of the provider.

signedAppointment

  • data
    string JSON map<string>any ᐉ appointmentData

    A JSON data field.

  • signature
    bytes (base64 • 64 ⇹ 128)

    An ECDSA signature.

  • publicKey
    bytes (base64 • 64 ⇹ 128)

    An ECDSA or ECDH public key.

  • updatedAt
    optional time (rfc3339)

    Time the appointment has last been updated.

  • bookedSlots
    optional list map<string>any ᐉ slot

    Booked slots associated with the appointment (visible to users).

  • bookings
    optional list map<string>any ᐉ booking

    Bookings associated with the appointment (only visible to providers).

signedProviderData

  • data
    string JSON map<string>any ᐉ providerData

    A JSON data field.

  • signature
    bytes (base64 • 64 ⇹ 128)

    An ECDSA signature.

  • publicKey
    bytes (base64 • 64 ⇹ 128)

    An ECDSA or ECDH public key.

  • id
    optional bytes (base64 • 32 ⇹ 32)

    An ID.

slot

  • id
    bytes (base64 • 32 ⇹ 32)

    An ID.

getAppointment()

Returns details about a specific appointment.

Parameter

getAppointment

  • id
    bytes (base64 • 32 ⇹ 32)

    An ID.

  • providerID
    bytes (base64 • 32 ⇹ 32)

    A provider ID.

Return type

map<string>any ᐉ signedAppointment

getToken()

Returns a signed token that allows users to book appointments.

Parameter

getToken

  • hash
    bytes (base64 • 32 ⇹ 32)

    The user-generated hash to store with the token.

  • code
    optional bytes (hex • 16 ⇹ 32)

    The optional signup code to use.

  • publicKey
    bytes (base64 • 64 ⇹ 128)

    An ECDSA or ECDH public key.

Return type

map<string>any ᐉ signedTokenData

Related forms

priorityToken

  • n
    integer (0 ⇹ - )

    [no translation for language en and key api.appointments.forms.priorityToken.fields.n]

signedTokenData

  • data
    string JSON map<string>any ᐉ tokenData

    A JSON data field.

  • signature
    bytes (base64 • 64 ⇹ 128)

    An ECDSA signature.

  • publicKey
    bytes (base64 • 64 ⇹ 128)

    An ECDSA or ECDH public key.

tokenData

  • hash
    bytes (base64 • 32 ⇹ 32)

    The user-generated hash belonging to the token.

  • token
    bytes (base64 • 32 ⇹ 32)

    The server-generated token.

  • publicKey
    bytes (base64 • 64 ⇹ 128)

    An ECDSA or ECDH public key.

  • data
    optional string JSON map<string>any ᐉ priorityToken

    Optional data associated with the token.

addMediatorPublicKeys()

Adds the public key data and associated information of a mediator to the system.

Parameter

addMediatorPublicKeys

  • data
    string JSON map<string>any ᐉ addMediatorPublicKeysData

    A JSON data field.

  • signature
    bytes (base64 • 64 ⇹ 128)

    An ECDSA signature.

  • publicKey
    bytes (base64 • 64 ⇹ 128)

    An ECDSA or ECDH public key.

Return type

enum < ok >

Related forms

addMediatorPublicKeysData

  • signedKeyData
    map<string>any ᐉ mediatorSignedKeyData

    Signed mediator key data.

  • timestamp
    time (rfc3339)

    A timestamp.

mediatorKeyData

  • signing
    bytes (base64 • 64 ⇹ 128)

    Public signing key of the mediator.

  • encryption
    bytes (base64 • 64 ⇹ 128)

    Public encryption key of the mediator.

mediatorSignedKeyData

  • data
    string JSON map<string>any ᐉ mediatorKeyData

    A JSON data field.

  • signature
    bytes (base64 • 64 ⇹ 128)

    An ECDSA signature.

  • publicKey
    bytes (base64 • 64 ⇹ 128)

    An ECDSA or ECDH public key.

addCodes()

Adds signup codes to the system.

Parameter

addCodes

  • data
    string JSON map<string>any ᐉ codesData

    A JSON data field.

  • signature
    bytes (base64 • 64 ⇹ 128)

    An ECDSA signature.

  • publicKey
    bytes (base64 • 64 ⇹ 128)

    An ECDSA or ECDH public key.

Return type

enum < ok >

Related forms

codesData

  • timestamp
    time (rfc3339)

    A timestamp.

  • actor
    string enum < provider, user >

    The actor for which to store signup codes.

  • codes
    list bytes (hex • 16 ⇹ 32)

    The signup codes to store.

uploadDistances()

Uploads distance information to the system.

Parameter

uploadDistances

  • data
    string JSON map<string>any ᐉ distancesData

    A JSON data field.

  • signature
    bytes (base64 • 64 ⇹ 128)

    An ECDSA signature.

  • publicKey
    bytes (base64 • 64 ⇹ 128)

    An ECDSA or ECDH public key.

Return type

enum < ok >

Related forms

distance

  • from
    string

    The origin.

  • to
    string

    The destination.

  • distance
    IsFloat

    The distance between origin and destination.

distancesData

  • timestamp
    time (rfc3339)

    A timestamp.

  • type
    enum < zipCode, zipArea >

    The type of distance information to store.

  • distances
    list map<string>any ᐉ distance

    The distances to store.

resetDB()

Resets the database. This endpoint is only active for test deployments.

Parameter

resetDB

  • data
    string JSON map<string>any ᐉ resetDBData

    A JSON data field.

  • signature
    bytes (base64 • 64 ⇹ 128)

    An ECDSA signature.

  • publicKey
    bytes (base64 • 64 ⇹ 128)

    An ECDSA or ECDH public key.

Return type

enum < ok >

Related forms

resetDBData

  • timestamp
    time (rfc3339)

    A timestamp.

confirmProvider()

Confirms a provider by adding its public key data and associated information to the system.

Parameter

confirmProvider

  • data
    string JSON map<string>any ᐉ confirmProviderData

    A JSON data field.

  • signature
    bytes (base64 • 64 ⇹ 128)

    An ECDSA signature.

  • publicKey
    bytes (base64 • 64 ⇹ 128)

    An ECDSA or ECDH public key.

Return type

enum < ok >

Related forms

confirmProviderData

  • timestamp
    time (rfc3339)

    A timestamp.

  • confirmedProviderData
    map<string>any ᐉ confirmedProviderData

    Confirmed provider data for review by the provider.

  • publicProviderData
    optional map<string>any ᐉ signedProviderData

    Publicly visible provider data.

  • signedKeyData
    map<string>any ᐉ providerSignedKeyData

    Publicly visible signed key data.

confirmedProviderData

  • data
    string JSON map<string>any ᐉ ecdhEncryptedData

    A JSON data field.

  • signature
    bytes (base64 • 64 ⇹ 128)

    An ECDSA signature.

  • publicKey
    bytes (base64 • 64 ⇹ 128)

    An ECDSA or ECDH public key.

providerKeyData

  • signing
    bytes (base64 • 64 ⇹ 128)

    Public signing key of the provider.

  • encryption
    bytes (base64 • 64 ⇹ 128)

    Public encryption key of the provider.

  • queueData
    map<string>any ᐉ providerQueueData

    Public information of the provider.

providerQueueData

  • zipCode
    string (5 ⇹ 5)

    Zip code of the provider.

  • accessible
    optional bool

    Whether the provider location is accessible.

providerSignedKeyData

  • data
    string JSON map<string>any ᐉ providerKeyData

    A JSON data field.

  • signature
    bytes (base64 • 64 ⇹ 128)

    An ECDSA signature.

  • publicKey
    bytes (base64 • 64 ⇹ 128)

    An ECDSA or ECDH public key.

getPendingProviderData()

Returns a list of provider data waiting for confirmation.

Parameter

getPendingProviderData

  • data
    string JSON map<string>any ᐉ getPendingProviderDataData

    A JSON data field.

  • signature
    bytes (base64 • 64 ⇹ 128)

    An ECDSA signature.

  • publicKey
    bytes (base64 • 64 ⇹ 128)

    An ECDSA or ECDH public key.

Return type

list map<string>any ᐉ rawProviderData

Related forms

getPendingProviderDataData

  • timestamp
    time (rfc3339)

    A timestamp.

  • limit
    optional (1000) integer (1 ⇹ 10000)

    Number of entries to return at most.

rawProviderData

  • encryptedData
    map<string>any ᐉ ecdhEncryptedData

    Encrypted data submitted by the provider.

getVerifiedProviderData()

Returns a list of confirmed provider data.

Parameter

getVerifiedProviderData

  • data
    string JSON map<string>any ᐉ getVerifiedProviderDataData

    A JSON data field.

  • signature
    bytes (base64 • 64 ⇹ 128)

    An ECDSA signature.

  • publicKey
    bytes (base64 • 64 ⇹ 128)

    An ECDSA or ECDH public key.

Return type

list map<string>any ᐉ rawProviderData

Related forms

getVerifiedProviderDataData

  • timestamp
    time (rfc3339)

    A timestamp.

  • limit
    optional (1000) integer (1 ⇹ 10000)

    Number of entries to return at most.

getProviderAppointments()

Returns a list of appointments for the given provider.

Parameter

getProviderAppointments

  • data
    string JSON map<string>any ᐉ getProviderAppointmentsData

    A JSON data field.

  • signature
    bytes (base64 • 64 ⇹ 128)

    An ECDSA signature.

  • publicKey
    bytes (base64 • 64 ⇹ 128)

    An ECDSA or ECDH public key.

Return type

list map<string>any ᐉ signedAppointment

Related forms

getProviderAppointmentsData

  • timestamp
    time (rfc3339)

    A timestamp.

  • from
    time (rfc3339)

    The earliest date of appointments to return.

  • to
    time (rfc3339)

    The latest date of appointments to return.

  • updatedSince
    optional time (rfc3339)

    The minimum 'updatedAt' value of appointments to return.

publishAppointments()

Publishes new or modified appointments to the system.

Parameter

publishAppointments

  • data
    string JSON map<string>any ᐉ publishAppointmentsData

    A JSON data field.

  • signature
    bytes (base64 • 64 ⇹ 128)

    An ECDSA signature.

  • publicKey
    bytes (base64 • 64 ⇹ 128)

    An ECDSA or ECDH public key.

Return type

enum < ok >

Related forms

publishAppointmentsData

  • timestamp
    time (rfc3339)

    A timestamp.

  • appointments
    list map<string>any ᐉ signedAppointment

    The appointments to publish.

storeProviderData()

Stores provider data for verification.

Parameter

storeProviderData

  • data
    string JSON map<string>any ᐉ storeProviderDataData

    A JSON data field.

  • signature
    bytes (base64 • 64 ⇹ 128)

    An ECDSA signature.

  • publicKey
    bytes (base64 • 64 ⇹ 128)

    An ECDSA or ECDH public key.

Return type

enum < ok >

Related forms

storeProviderDataData

  • timestamp
    time (rfc3339)

    A timestamp.

  • code
    optional bytes (hex • 16 ⇹ 32)

    Optional signup code.

  • encryptedData
    map<string>any ᐉ ecdhEncryptedData

    Encrypted data for mediators to review.

checkProviderData()

Checks the verification status of provider data.

Parameter

checkProviderData

  • data
    string JSON map<string>any ᐉ checkProviderDataData

    A JSON data field.

  • signature
    bytes (base64 • 64 ⇹ 128)

    An ECDSA signature.

  • publicKey
    bytes (base64 • 64 ⇹ 128)

    An ECDSA or ECDH public key.

Return type

map<string>any ᐉ confirmedProviderData

Related forms

checkProviderDataData

  • timestamp
    time (rfc3339)

    A timestamp.

bookAppointment()

Books an appointment.

Parameter

bookAppointment

  • data
    string JSON map<string>any ᐉ bookAppointmentData

    A JSON data field.

  • signature
    bytes (base64 • 64 ⇹ 128)

    An ECDSA signature.

  • publicKey
    bytes (base64 • 64 ⇹ 128)

    An ECDSA or ECDH public key.

Return type

map<string>any ᐉ booking

Related forms

bookAppointmentData

  • providerID
    bytes (base64 • 32 ⇹ 32)

    A provider ID.

  • id
    bytes (base64 • 32 ⇹ 32)

    An ID.

  • timestamp
    time (rfc3339)

    A timestamp.

  • signedTokenData
    map<string>any ᐉ signedTokenData

    Signed token data of the user.

  • encryptedData
    map<string>any ᐉ ecdhEncryptedData

    Encrypted data for the provider.

cancelAppointment()

Cancels a booking.

Parameter

cancelAppointment

  • data
    string JSON map<string>any ᐉ cancelAppointmentData

    A JSON data field.

  • signature
    bytes (base64 • 64 ⇹ 128)

    An ECDSA signature.

  • publicKey
    bytes (base64 • 64 ⇹ 128)

    An ECDSA or ECDH public key.

Return type

enum < ok >

Related forms

cancelAppointmentData

  • id
    bytes (base64 • 32 ⇹ 32)

    An ID.

  • providerID
    bytes (base64 • 32 ⇹ 32)

    A provider ID.

  • timestamp
    time (rfc3339)

    A timestamp.

  • signedTokenData
    map<string>any ᐉ signedTokenData

    Signed token data of the user.

Storage API

The Storage API stores encrypted settings for users and providers of immunization appointments. It is separate from the Appointments API for organizational reasons, so it can be run independently (although it is also possible to run both APIs together).

storeSettings()

Stores encrypted settings.

Parameter

storeSettings

  • id
    bytes (base64 • 32 ⇹ 32)

    ID under which to store settings.

  • data
    IsAnything

    Settings to store under the given ID.

Return type

enum < ok >

getSettings()

Retrieves encrypted settings.

Parameter

getSettings

  • id
    bytes (base64 • 32 ⇹ 32)

    ID for which to retrieve settings.

Return type

deleteSettings()

Deletes encrypted settings.

Parameter

deleteSettings

  • id
    bytes (base64 • 32 ⇹ 32)

    ID for which to delete settings.

Return type

enum < ok >

resetDB()

Resets the database. Only enabled for test deployments.

Parameter

resetDB

  • data
    string JSON map<string>any ᐉ resetDBData

    A JSON data field.

  • signature
    bytes (base64 • 64 ⇹ 128)

    An ECDSA signature.

  • publicKey
    bytes (base64 • 64 ⇹ 128)

    An ECDSA or ECDH public key.

Return type

enum < ok >

Related forms

resetDBData

  • timestamp
    time (rfc3339)

    A timestamp.