Kotidigi-id related support operations

This chapter describes how to register a device for a person and get a corresponding Kotidigi-id as a response.

Operations

In the following, identifier is the value that identifies person and identifierSystem means the system that determines in what coding system it is applicable. Note that we use separate coding systems for the sandbox and the production Kotidigi environments, e.g. for sandbox we have the uri: https://sandbox.kotidigi.fi/identifier/person

If error happens, the result body has the following json structure:

{
  "errorCode": "...",
  "message": "..."
}

List of error codes (code, meaning, HTTP code):

• unsupported-device : Given device is not supported : 400
• person-not-found : Person not found using given identifier : 404
• unsupported-identifier-system : Identifier system not supported for this operation : 400
• internal-server-error : Unexpected error : 500

Register device for a person

The identifier/identifierSystem may be Hetu or Kotidigi-id.

POST https://sandbox.kotidigi.fi/api/ecosystem-support/register-device
Authorization: Bearer {facade_auth_token}
Content-Type: application/json
{
   "identifier": "010101-123N",
   "identifierSystem": "urn:oid:1.2.246.21",
   "device": "Vivago"
}

Successful request yields something a Kotidigi-id with relevant coding system:

{
    "identifier": "123e4567-e89b-12d3-a456-426614174000",
    "identifierSystem": "https://{environment.}kotidigi.fi/identifier/person"
}

Get Kotidigi-id

Given hetu, get corresponding Kotidigi-id with relevant coding system — or if not found, 404 HTTP status code.

POST https://sandbox.kotidigi.fi/api/ecosystem-support/get-kotidigi-id
Authorization: Bearer {access_token}
Content-Type: application/json
{
    "identifier": "010101-123N",
    "identifierSystem": "urn:oid:1.2.246.21",
}

Successful request yields something like this:

{
    "identifier": "123e4567-e89b-12d3-a456-426614174000",
    "identifierSystem": "https://{environment.}kotidigi.fi/identifier/person"
}

De-register device for a person

POST https://sandbox.kotidigi.fi/api/ecosystem-support/deregister-device
Authorization: Bearer {access_token}
Content-Type: application/json
{
    "identifier": "123e4567-e89b-12d3-a456-426614174000",
    "identifierSystem": "https://{environment.}kotidigi.fi/identifier/person",
    "device": "Vivago"
}

Successful request yields empty result (HTTP status 200):

{
}