apiary.apib

FORMAT: 1
HOST: https://api.ehealth.gov.ua

# PIS TRUSTED API

**Version: 9.5.2 v.2**

This is a **Trusted PIS-related sign-in and sign-up part** of API documentation for Ukrainian Health Services government institution back-end, that should provide:

* Patient sign-in
* Patient sign-in by confidant person
* Patient sign-up
* Patient sign-up by confidant person
* Patient data management

> In order to get specification for PIS-related consumers part of API documentation please proceed [here](https://ehealthpisapi.docs.apiary.io/#)

# Group Public. Patient Information System

The table below reflects actual API endpoints for all the eHealth environments
Env     | Host
--------|-----
DEMO     | https://auth-demo.ehealth.gov.ua
PREPROD  | https://auth-preprod.ehealth.gov.ua
PROD     | https://auth.ehealth.gov.ua 

**Notes:**
- Every sign-in and sign-up method described here must be used only by Clients with `TRUSTED_PIS` client type.
- When `access_token` expires, Client must renew it using `refresh_token` with [Use Refresh Token for Access Token extension](#reference/public.-patient-information-system/sign-in/use-refresh-token-for-access-token-extension) method.

**API-key:**
- For identifiers of PIS clients (as a broker) we use term api-key. PIS must **mandatory** send api-key when called any eHealth API.
- api-key is a `pis_client_secret` - Patient Information System secret key issued upon integration request.
- api-key is dispatched in Request HEADER as a `API-key` attribute. 
- If PIS don't send api-key in Request HEADER, API return 401 error wih message "API-KEY header required".

## Sign-in [/api/sign-in]

### Get nonce [POST /oauth/nonce]

This endpoint allows to get nonce (one time JWT) for active client of the system.

Field `client_secret` is mandatory for client type = TRUSTED_PIS.

+ Request (application/json)

    + Attributes (object)
        + `client_id`: `30074b6e-fbab-4dc1-9d37-88c21dab1847` (string, required) - Client identifier in the system.
        + `client_secret`: `c2778f3064753ea70de870a53795f5c9` (string, required) - Required only for clients with `TRUSTED_PIS` client type.

+ Response 200 (application/json)
    + Attributes (`Response_OK`)
        + data (object)
           + token: 'eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJtaXRocmlsLWxvZ2luIiwiZXhwIjoxNTIzNDM5MjAxLCJpYXQiOjE1MjM0MzgzMDEsImlzcyI6IkVIZWFsdGgiLCJqdGkiOiJlZmUxZjA4ZS1kNGI0LTRjZWYtYTAyYy03OGVhNGExZGRhMjUiLCJuYmYiOjE1MjM0MzgzMDAsIm5vbmNlIjoxMjMsInN1YiI6MTIzLCJ0eXAiOiJhY2Nlc3MifQ.UZ6S92h3nAG-GKY_XUE1Rc6uR_BuqR8ufUJfMhhKtNmt7DkkQlU49qPXjL0LFddVz1E2DXi2a-BQ0FG-DHsTHA' (string, required)

### Patient sign-in [POST /api/pis/sign-in]

This endpoint is used to authenticate, approve scopes and sign-in user using one endpoint. If user does not exist - search for active patient and create user.

This endpoint must be used only by trusted PIS clients.

Signed content must contain signed nonce that was generated for trusted PIS.

+ Request (application/json)

    + Headers

            api-key: uXhEczJ56adsfh3Ri9SUkc4en

    + Attributes (object)
        + token (object, required)
            + `grant_type`: pis_auth (string, fixed, required) - Auth Grant Type. Currently only `pis_auth` is supported.
            + `client_id`: `4fc161ad-5e3d-4c5e-9a9e-189e2ddffe56` (string, required) - Patient information system ID. Used to identify the context of the PIS.
            + `client_secret`: `UXhEczJacXh3Ri9SUkc4enhHTVVpQ119` (string, required) - Patient information system secret key issued upon integration request. Used to identify application developer.
            + `signed_content`: `eyJqd3QiOiJleUpoYkdjaU9pSklVelV4TWlJc0luUjVjQ0k2SWtwWFZDSjkuZXlKaGRXUWlPaUowY25WemRHVmtMV05zYVdWdWRDSXNJbVY0Y0NJNk1UWTRNak14TnprME9Dd2lhV0YwSWpveE5qZ3lNekUwTXpRNExDSnBjM01pT2lKRlNHVmhiSFJvSWl3aWFuUnBJam9pWWpZMk1USTROVGN0TlRCaVlTMDBZV0V6TFdFNE56QXRPR0U1T0dZNU1tTmpNalUwSWl3aWJtSm1Jam94TmpneU16RTBNelEzTENKdWIyNWpaU0k2SW1RMU5XUmxOMkkxTFRZeFlURXROREZsWWkxaE9Ua3hMV1ZsWm1VNVptRmlZbU00WlNJc0luTjFZaUk2SW1RMU5XUmxOMkkxTFRZeFlURXROREZsWWkxaE9Ua3hMV1ZsWm1VNVptRmlZbU00WlNJc0luUjVjQ0k2SW1GalkyVnpjeUo5LkhXTzZlbmxyUE5hYlNIM0xfaWtJU3ZaSjFadnpEV3VkaUNNTEJadkFpcksxQW5SeE5ERW5BY0JKUWVxM2pLdWJsSHBpWUFmNktOZXY5a3daeTJLMXp3In0=` (string, required)
            + `signed_content_encoding`: base64 (string, required)
            + `scope`: `declaration_request:read declaration_request:terminate declaration:read person:read app:read authentication_factor:read profile:read` (string, required) - List of scopes that is required in application business logic, separated by space.

+ Response 201 (application/json)
    + Attributes (`Response_OK`)
        + meta (Response__Meta)
            + code: 201 (number)
        + data (`Access_Token`)

### Confidant patient sign-in [POST /api/pis/confidant/sign-in]

This endpoint is used to authenticate, approve scopes and sign-in as a confidant patient. 

> **Note:** It could be done only if there is a registered relation between actor (authenticated patient) and related patient

If user does not exist - search for active patient and create user.

This endpoint must be used only by trusted PIS clients.

Signed content must contain patient data to search and identify patient and validate relation

Look at [**Dummy Confidant patient sign-in**](#reference/public.-dummy-methods/sign-in/dummy-confidant-patient-sign-in) for more details

+ Request (application/json)

    + Headers
            
            api-key: uXhEczJ56adsfh3Ri9SUkc4en

    + Attributes (object)
        + `signed_content`: `ewogICAgImZpcnN0X25hbWUiOiAi0J/QtdGC0YDQviIsCiAgICAibGFzdF9uYW1lIjogItCG0LLQsNC90L7QsiIsCiAgICAic2Vjb25kX25hbWUiOiAi0JzQuNC60L7Qu9Cw0LnQvtCy0LjRhyIsCiAgICAiYmlydGhfZGF0ZSI6ICIxOTkxLTA4LTE5IiwKICAgICJiaXJ0aF9jb3VudHJ5IjogItCj0LrRgNCw0ZfQvdCwIiwKICAgICJiaXJ0aF9zZXR0bGVtZW50IjogItCS0ZbQvdC90LjRhtGPIiwKICAgICJnZW5kZXIiOiAiTUFMRSIsCiAgICAiZW1haWwiOiAiZW1haWxAZXhhbXBsZS5jb20iLAogICAgInRheF9pZCI6ICIzMTI2NTA5ODE2IiwKICAgICJzZWNyZXQiOiAic2VjcmV0IiwKICAgICJkb2N1bWVudHMiOiBbCiAgICAgIHsKICAgICAgICAidHlwZSI6ICJQQVNTUE9SVCIsCiAgICAgICAgIm51bWJlciI6ICIxMjA1MTgiLAogICAgICAgICJpc3N1ZWRfYnkiOiAi0KDQvtC60LjRgtC90Y/QvdGB0YzQutC40Lwg0KDQkiDQk9CjINCc0JLQoSDQmtC40ZfQstGB0YzQutC+0Zcg0L7QsdC70LDRgdGC0ZYiLAogICAgICAgICJpc3N1ZWRfYXQiOiAiMjAxNy0wMi0yOCIKICAgICAgfQogICAgXSwKICAgICJhZGRyZXNzZXMiOiBbCiAgICAgIHsKICAgICAgICAidHlwZSI6ICJSRVNJREVOQ0UiLAogICAgICAgICJjb3VudHJ5IjogIlVBIiwKICAgICAgICAiYXJlYSI6ICLQltC40YLQvtC80LjRgNGB0YzQutCwIiwKICAgICAgICAicmVnaW9uIjogItCR0LXRgNC00LjRh9GW0LLRgdGM0LrQuNC5IiwKICAgICAgICAic2V0dGxlbWVudCI6ICLQmtC40ZfQsiIsCiAgICAgICAgInNldHRsZW1lbnRfdHlwZSI6ICJDSVRZIiwKICAgICAgICAic2V0dGxlbWVudF9pZCI6ICI0MzQzMjQzMiIsCiAgICAgICAgInN0cmVldF90eXBlIjogIlNUUkVFVCIsCiAgICAgICAgInN0cmVldCI6ICLQstGD0LsuINCd0ZbQttC40L3RgdGM0LrQsCIsCiAgICAgICAgImJ1aWxkaW5nIjogIjE1IiwKICAgICAgICAiYXBhcnRtZW50IjogIjIzIiwKICAgICAgICAiemlwIjogIjAyMDkwIgogICAgICB9CiAgICBdLAogICAgInBob25lcyI6IFsKICAgICAgewogICAgICAgICJ0eXBlIjogIk1PQklMRSIsCiAgICAgICAgIm51bWJlciI6ICIrMzgwNTAzNDEwODcwIgogICAgICB9CiAgICBdLAogICAgImF1dGhlbnRpY2F0aW9uX21ldGhvZHMiOiBbCiAgICAgIHsKICAgICAgICAidHlwZSI6ICJPVFAiLAogICAgICAgICJwaG9uZV9udW1iZXIiOiAiKzM4MDUwODg4NzcwMCIKICAgICAgfQogICAgXSwKICAgICJwcmVmZXJyZWRfd2F5X2NvbW11bmljYXRpb24iOiAiZW1haWwiLAogICAgImVtZXJnZW5jeV9jb250YWN0IjogewogICAgICAiZmlyc3RfbmFtZSI6ICLQn9C10YLRgNC+IiwKICAgICAgImxhc3RfbmFtZSI6ICLQhtCy0LDQvdC+0LIiLAogICAgICAic2Vjb25kX25hbWUiOiAi0JzQuNC60L7Qu9Cw0LnQvtCy0LjRhyIsCiAgICAgICJwaG9uZXMiOiBbCiAgICAgICAgewogICAgICAgICAgInR5cGUiOiAiTU9CSUxFIiwKICAgICAgICAgICJudW1iZXIiOiAiKzM4MDUwMzQxMDg3MCIKICAgICAgICB9CiAgICAgIF0KICAgIH0sCiAgICAicHJvY2Vzc19kaXNjbG9zdXJlX2RhdGFfY29uc2VudCI6IHRydWUKICB9Cn0=` (string, required)
        + `signed_content_encoding`: base64 (string, required)
        + token (object, required)
            + `grant_type`: pis_auth (string, fixed, required) - Auth Grant Type. Currently only `pis_auth` is supported.
            + `client_id`: `4fc161ad-5e3d-4c5e-9a9e-189e2ddffe56` (string, required) - Patient information system ID. Used to identify the context of the PIS.
            + `client_secret`: `UXhEczJacXh3Ri9SUkc4enhHTVVpQ119` (string, required) - Patient information system secret key issued upon integration request. Used to identify application developer.
            + `scope`: `declaration_request:read declaration_request:terminate declaration:read person:read app:read authentication_factor:read profile:read` (string, required) - List of scopes that is required in application business logic, separated by space.

+ Response 201 (application/json)
    + Attributes (`Response_OK`)
        + meta (Response__Meta)
            + code: 201 (number)
        + data (`Access_Token`)

### Use Refresh Token for Access Token extension [POST /oauth/tokens]

This endpoint is used to renew access token using refresh token. 

It is available to renew access token as many time as needed during the lifetime of refresh token.

+ Request (application/json)

    + Attributes (object)
        + token (object)
            + `client_id`: `6498d88e-97fb-47e2-85a5-99e884f888aa` (string, required) - Medical Service provider ID issued after legal_entity registration. Used to identify the context of the MSP/Pharmacy.
            + client_secret: `msp-001-secret-key` (string, required) - Medical Service provider secret key issued upon integration request. Used to identify MSP.
            + refresh_token: `my-oauth-refresh-token` (string, required) - oAuth refresh token.
            + `grant_type`: refresh_token (string, fixed) - oAuth Grant Type. Currently only `authorization_code` is supported.

+ Response 201 (application/json)
    + Attributes (`Response_OK`)
        + meta (Response__Meta)
            + code: 201 (number)
        + data (`Access_Token_1`)

### Logout [POST /auth/logout]

This endpoint is used to terminate users authenticated session based on a valid access token.

Refresh token from authenticated session will also be expired.

+ Request (application/json)

    + Headers

            Authorization: Bearer c2778f3064753ea70de870a53795f5c9

+ Response 200 (application/json)
    + Attributes (`Response_OK`)

##Sign-up [/api/sign-up]

### Verify phone number [POST /api/sms_verifications]

This endpoint is used to verify submitted phone number as a part of person registration process. 

In case number needs verification - generate and send OTP, in case phone does not need verification - return OK.

Authorization header must contain nonce that was generated for trusted PIS.

+ Request (application/json)

    + Headers

            Authorization: Bearer eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJjYWJpbmV0LXJlZ2lzdHJhdGlvbiIsImVtYWlsIjoiYXByb2tvcHBoYXJtZGlyNEB1a3IubmV0IiwiZXhwIjoxNjgyNjkzNTc3LCJpYXQiOjE2ODI2NjQ3NzcsImlzcyI6IkVIZWFsdGgiLCJqdGkiOiIxOTAyYTkyYS00MDcyLTQ3MWEtYmU4NS1iZWU0MzQzNmNlYjEiLCJuYmYiOjE2ODI2NjQ3NzYsInN1YiI6ImFwcm9rb3BwaGFybWRpcjRAdWtyLm5ldCIsInR5cCI6ImFjY2VzcyJ9.EXTuYRQenjqzsjNAJ5agmEbSHcg_XRKwc3VOGAtSjfMOy4uIJ_BBMUeUWSVzy4_OezPjEIiVcnaLTN4pZbtgow

    + Attributes (object)
        + `factor`: `+380501112233` (string, required) - phone number that needs to be verified.
        + `type`: SMS (enum, required) - verification type.
            - SMS
        + `content_hash`: `76dea970d89477ed03dc5289f297443c` (string, required) - MD5 hash of content with phone number that needs to be verified.

+ Response 200 (application/json)
    + Attributes (`Response_OK`)
        + meta (`Response__Meta`)
            + code: 200 (number)
        + data (object, required)
            + `result`: `OTP sent` (enum, required) - phone verification result.
                - `OTP sent`
                - `Verified`
        + urgent (object, optional)
            + `next_step`: `REQUEST_OTP` (string, optional) - next step that needs to be taken in phone verification process.

### Patient sign-up [POST /api/pis/sign-up]

This endpoint is used to authenticate, create mpi record for patient if needed, create user for patient if needed, approve scopes and sign-in user.

This endpoint must be used only by trusted PIS clients.

Signed content must contain nonce that was generated for trusted PIS.

Look at [**Dummy Patient sign-up**](#reference/public.-dummy-methods/sign-up/dummy-patient-sign-up) for more details.

+ Request (application/json)

    + Headers

            api-key: uXhEczJ56adsfh3Ri9SUkc4en

    + Attributes (object)
        + `signed_content`: `ewogICAgImZpcnN0X25hbWUiOiAi0J/QtdGC0YDQviIsCiAgICAibGFzdF9uYW1lIjogItCG0LLQsNC90L7QsiIsCiAgICAic2Vjb25kX25hbWUiOiAi0JzQuNC60L7Qu9Cw0LnQvtCy0LjRhyIsCiAgICAiYmlydGhfZGF0ZSI6ICIxOTkxLTA4LTE5IiwKICAgICJiaXJ0aF9jb3VudHJ5IjogItCj0LrRgNCw0ZfQvdCwIiwKICAgICJiaXJ0aF9zZXR0bGVtZW50IjogItCS0ZbQvdC90LjRhtGPIiwKICAgICJnZW5kZXIiOiAiTUFMRSIsCiAgICAiZW1haWwiOiAiZW1haWxAZXhhbXBsZS5jb20iLAogICAgInRheF9pZCI6ICIzMTI2NTA5ODE2IiwKICAgICJzZWNyZXQiOiAic2VjcmV0IiwKICAgICJkb2N1bWVudHMiOiBbCiAgICAgIHsKICAgICAgICAidHlwZSI6ICJQQVNTUE9SVCIsCiAgICAgICAgIm51bWJlciI6ICIxMjA1MTgiLAogICAgICAgICJpc3N1ZWRfYnkiOiAi0KDQvtC60LjRgtC90Y/QvdGB0YzQutC40Lwg0KDQkiDQk9CjINCc0JLQoSDQmtC40ZfQstGB0YzQutC+0Zcg0L7QsdC70LDRgdGC0ZYiLAogICAgICAgICJpc3N1ZWRfYXQiOiAiMjAxNy0wMi0yOCIKICAgICAgfQogICAgXSwKICAgICJhZGRyZXNzZXMiOiBbCiAgICAgIHsKICAgICAgICAidHlwZSI6ICJSRVNJREVOQ0UiLAogICAgICAgICJjb3VudHJ5IjogIlVBIiwKICAgICAgICAiYXJlYSI6ICLQltC40YLQvtC80LjRgNGB0YzQutCwIiwKICAgICAgICAicmVnaW9uIjogItCR0LXRgNC00LjRh9GW0LLRgdGM0LrQuNC5IiwKICAgICAgICAic2V0dGxlbWVudCI6ICLQmtC40ZfQsiIsCiAgICAgICAgInNldHRsZW1lbnRfdHlwZSI6ICJDSVRZIiwKICAgICAgICAic2V0dGxlbWVudF9pZCI6ICI0MzQzMjQzMiIsCiAgICAgICAgInN0cmVldF90eXBlIjogIlNUUkVFVCIsCiAgICAgICAgInN0cmVldCI6ICLQstGD0LsuINCd0ZbQttC40L3RgdGM0LrQsCIsCiAgICAgICAgImJ1aWxkaW5nIjogIjE1IiwKICAgICAgICAiYXBhcnRtZW50IjogIjIzIiwKICAgICAgICAiemlwIjogIjAyMDkwIgogICAgICB9CiAgICBdLAogICAgInBob25lcyI6IFsKICAgICAgewogICAgICAgICJ0eXBlIjogIk1PQklMRSIsCiAgICAgICAgIm51bWJlciI6ICIrMzgwNTAzNDEwODcwIgogICAgICB9CiAgICBdLAogICAgImF1dGhlbnRpY2F0aW9uX21ldGhvZHMiOiBbCiAgICAgIHsKICAgICAgICAidHlwZSI6ICJPVFAiLAogICAgICAgICJwaG9uZV9udW1iZXIiOiAiKzM4MDUwODg4NzcwMCIKICAgICAgfQogICAgXSwKICAgICJwcmVmZXJyZWRfd2F5X2NvbW11bmljYXRpb24iOiAiZW1haWwiLAogICAgImVtZXJnZW5jeV9jb250YWN0IjogewogICAgICAiZmlyc3RfbmFtZSI6ICLQn9C10YLRgNC+IiwKICAgICAgImxhc3RfbmFtZSI6ICLQhtCy0LDQvdC+0LIiLAogICAgICAic2Vjb25kX25hbWUiOiAi0JzQuNC60L7Qu9Cw0LnQvtCy0LjRhyIsCiAgICAgICJwaG9uZXMiOiBbCiAgICAgICAgewogICAgICAgICAgInR5cGUiOiAiTU9CSUxFIiwKICAgICAgICAgICJudW1iZXIiOiAiKzM4MDUwMzQxMDg3MCIKICAgICAgICB9CiAgICAgIF0KICAgIH0sCiAgICAicHJvY2Vzc19kaXNjbG9zdXJlX2RhdGFfY29uc2VudCI6IHRydWUKICB9Cn0=` (string, required)
        + `signed_content_encoding`: base64 (string, required)
        + otp: 1234 (number, optional) - optional OTP that was sent to authentication method phone number via `Verify phone number` method
        + token (object, required)
            + `grant_type`: pis_auth (string, fixed, required) - Auth Grant Type. Currently only `pis_auth` is supported.
            + `client_id`: `4fc161ad-5e3d-4c5e-9a9e-189e2ddffe56` (string, required) - Patient information system ID. Used to identify the context of the PIS.
            + `client_secret`: `UXhEczJacXh3Ri9SUkc4enhHTVVpQ119` (string, required) - Patient information system secret key issued upon integration request. Used to identify application developer.
            + `scope`: `declaration_request:read declaration_request:terminate declaration:read person:read app:read authentication_factor:read profile:read` (string, required) - List of scopes that is required in application business logic, separated by space.
            
+ Response 201 (application/json)
    + Attributes (`Response_OK`)
        + meta (`Response__Meta`)
            + code: 201 (number)
        + data (object, required)
            + person (object, required)
                + id: `1380df72-275a-11e7-93ae-92361f002671` (string, required)
                + include `Person`
                + emergency_contact (object, required)
                    + include `Emergency_Contact`
            + user (object, required)
                + `id`: `7673eb5a-0cae-4fa8-9f81-e6da46aa2940` (string, optional)
                + tax_id: 3000080053 (string, required)
            + token (`Access_Token`)

### Confidant patient sign-up [POST /api/pis/confidant/sign-up]

This endpoint is used to register patient (Legally Incapacitated) in the system by the hands of their confidant patient

> Note: It could be done ONLY when the system is able to validate their relation using trusted external DBs (eg. GOV services)

This endpoint must be used only by trusted PIS clients.

Signed content must contain patient data needed to create new MPI record

Look at [**Dummy Confidant patient sign-up**](#reference/public.-dummy-methods/sign-up/dummy-confidant-patient-sign-up) for more details.

+ Request (application/json)

    + Headers
            
            api-key: uXhEczJ56adsfh3Ri9SUkc4en

    + Attributes (object)
        + `signed_content`: `ewogICAgImZpcnN0X25hbWUiOiAi0J/QtdGC0YDQviIsCiAgICAibGFzdF9uYW1lIjogItCG0LLQsNC90L7QsiIsCiAgICAic2Vjb25kX25hbWUiOiAi0JzQuNC60L7Qu9Cw0LnQvtCy0LjRhyIsCiAgICAiYmlydGhfZGF0ZSI6ICIxOTkxLTA4LTE5IiwKICAgICJiaXJ0aF9jb3VudHJ5IjogItCj0LrRgNCw0ZfQvdCwIiwKICAgICJiaXJ0aF9zZXR0bGVtZW50IjogItCS0ZbQvdC90LjRhtGPIiwKICAgICJnZW5kZXIiOiAiTUFMRSIsCiAgICAiZW1haWwiOiAiZW1haWxAZXhhbXBsZS5jb20iLAogICAgInRheF9pZCI6ICIzMTI2NTA5ODE2IiwKICAgICJzZWNyZXQiOiAic2VjcmV0IiwKICAgICJkb2N1bWVudHMiOiBbCiAgICAgIHsKICAgICAgICAidHlwZSI6ICJQQVNTUE9SVCIsCiAgICAgICAgIm51bWJlciI6ICIxMjA1MTgiLAogICAgICAgICJpc3N1ZWRfYnkiOiAi0KDQvtC60LjRgtC90Y/QvdGB0YzQutC40Lwg0KDQkiDQk9CjINCc0JLQoSDQmtC40ZfQstGB0YzQutC+0Zcg0L7QsdC70LDRgdGC0ZYiLAogICAgICAgICJpc3N1ZWRfYXQiOiAiMjAxNy0wMi0yOCIKICAgICAgfQogICAgXSwKICAgICJhZGRyZXNzZXMiOiBbCiAgICAgIHsKICAgICAgICAidHlwZSI6ICJSRVNJREVOQ0UiLAogICAgICAgICJjb3VudHJ5IjogIlVBIiwKICAgICAgICAiYXJlYSI6ICLQltC40YLQvtC80LjRgNGB0YzQutCwIiwKICAgICAgICAicmVnaW9uIjogItCR0LXRgNC00LjRh9GW0LLRgdGM0LrQuNC5IiwKICAgICAgICAic2V0dGxlbWVudCI6ICLQmtC40ZfQsiIsCiAgICAgICAgInNldHRsZW1lbnRfdHlwZSI6ICJDSVRZIiwKICAgICAgICAic2V0dGxlbWVudF9pZCI6ICI0MzQzMjQzMiIsCiAgICAgICAgInN0cmVldF90eXBlIjogIlNUUkVFVCIsCiAgICAgICAgInN0cmVldCI6ICLQstGD0LsuINCd0ZbQttC40L3RgdGM0LrQsCIsCiAgICAgICAgImJ1aWxkaW5nIjogIjE1IiwKICAgICAgICAiYXBhcnRtZW50IjogIjIzIiwKICAgICAgICAiemlwIjogIjAyMDkwIgogICAgICB9CiAgICBdLAogICAgInBob25lcyI6IFsKICAgICAgewogICAgICAgICJ0eXBlIjogIk1PQklMRSIsCiAgICAgICAgIm51bWJlciI6ICIrMzgwNTAzNDEwODcwIgogICAgICB9CiAgICBdLAogICAgImF1dGhlbnRpY2F0aW9uX21ldGhvZHMiOiBbCiAgICAgIHsKICAgICAgICAidHlwZSI6ICJPVFAiLAogICAgICAgICJwaG9uZV9udW1iZXIiOiAiKzM4MDUwODg4NzcwMCIKICAgICAgfQogICAgXSwKICAgICJwcmVmZXJyZWRfd2F5X2NvbW11bmljYXRpb24iOiAiZW1haWwiLAogICAgImVtZXJnZW5jeV9jb250YWN0IjogewogICAgICAiZmlyc3RfbmFtZSI6ICLQn9C10YLRgNC+IiwKICAgICAgImxhc3RfbmFtZSI6ICLQhtCy0LDQvdC+0LIiLAogICAgICAic2Vjb25kX25hbWUiOiAi0JzQuNC60L7Qu9Cw0LnQvtCy0LjRhyIsCiAgICAgICJwaG9uZXMiOiBbCiAgICAgICAgewogICAgICAgICAgInR5cGUiOiAiTU9CSUxFIiwKICAgICAgICAgICJudW1iZXIiOiAiKzM4MDUwMzQxMDg3MCIKICAgICAgICB9CiAgICAgIF0KICAgIH0sCiAgICAicHJvY2Vzc19kaXNjbG9zdXJlX2RhdGFfY29uc2VudCI6IHRydWUKICB9Cn0=` (string, required)
        + `signed_content_encoding`: base64 (string, required)
        + token (object, required)
            + `grant_type`: pis_auth (string, fixed, required) - Auth Grant Type. Currently only `pis_auth` is supported.
            + `client_id`: `4fc161ad-5e3d-4c5e-9a9e-189e2ddffe56` (string, required) - Patient information system ID. Used to identify the context of the PIS.
            + `client_secret`: `UXhEczJacXh3Ri9SUkc4enhHTVVpQ119` (string, required) - Patient information system secret key issued upon integration request. Used to identify application developer.
            + `scope`: `declaration_request:read declaration_request:terminate declaration:read person:read app:read authentication_factor:read profile:read` (string, required) - List of scopes that is required in application business logic, separated by space.
            
+ Response 201 (application/json)
    + Attributes (`Response_OK`)
        + meta (`Response__Meta`)
            + code: 201 (number)
        + data (object, required)
            + person (object, required)
                + id: `1380df72-275a-11e7-93ae-92361f002671` (string, required)
                + include `Person`
                + emergency_contact (object, required)
                    + include `Emergency_Contact`
            + user (object, required)
                + `id`: `7673eb5a-0cae-4fa8-9f81-e6da46aa2940` (string, optional)
                + tax_id: 3000080053 (string, required)
            + token (`Access_Token`)

## Person requests [/api/pis/trusted/person_requests]

### Initialize Update Person details [POST /api/pis/trusted/person_requests]

Use this method to initialize creation of Person request to update the person details according to his id, which was previously found using person_id from access token.

This endpoint must be used only by trusted PIS clients.

After person request is created, [Complete Update Person details](https://ehealthpisapi.docs.apiary.io/#reference/public.-patient-information-system/person-requests/complete-update-person-details) method must be called.


+ Request (application/json)

    + Headers

            Authorization: Bearer c2778f3064753ea70de870a53795f5c9
            api-key: uXhEczJ56adsfh3Ri9SUkc4en

    + Attributes (object)
        + `person` (object, required)
            + include `Update_Person_Request_PIS`
        + `patient_signed`: false (boolean, required)
        + `process_disclosure_data_consent`: true (boolean, required)

+ Response 201 (application/json)
    + Attributes (`Response_OK`)
        + meta (`Response__Meta`)
            + code: 201 (number)
        + data (object, required)
            + include `Person_request_details`
        + urgent (object, required)
            + documents (array[`media_content`], optional)

# Group Public. Dummy methods

##Sign-in [/dummy/sign-in]

### Dummy Confidant patient sign-in [POST /dummy/pis/confidant/sign-in]

+ Request (application/json)
    + Attributes (object)
        + `last_name`: `Петров` (string, required)
        + `given_name`: `Петро Петрович` (string, required)
        + `tax_id`: `2323232323` (string, optional)
        + `document` (object, optional)
            + `type`: PASSPORT (string, required) - `Dictionary DOCUMENT_TYPE`
            + `number`: АА120518 (string, required) - document issue number

+ Response 201 (application/json)
    + Attributes (`Response_OK`)
        + meta (`Response__Meta`)
            + code: 201 (number)
        + data (object, required)
            + user (object, required)
                + `id`: `7673eb5a-0cae-4fa8-9f81-e6da46aa2940` (string, optional)
                + tax_id: 3000080053 (string, required)
            + token (`Access_Token`)

##Sign-up [/dummy/sign-up]

### Dummy Patient sign-up [POST /dummy/pis/sign-up]

+ Request (application/json)
    + Attributes (object)
        + `person` (object, required)
            + include `Person_Request_PIS`
        + `patient_signed`: true (boolean, required)
        + `process_disclosure_data_consent`: true (boolean, required)
        + `jwt`: `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbWFpbCI6InNwLnZpcm55QGdtYWlsLmNvbSIsInRpbWVzdGFtcCI6IjIwMTgtMDItMjggMTA6Mzg6MDAifQ.LJRLTqK-zf9gxDNMONcI8cMCSYosDtmAIZqhzZUdhz4` (string, required)

+ Response 201 (application/json)
    + Attributes (`Response_OK`)
        + meta (`Response__Meta`)
            + code: 201 (number)
        + data (object, required)
            + person (object, required)
                + id: `1380df72-275a-11e7-93ae-92361f002671` (string, required)
                + include `Person`
                + emergency_contact (object, required)
                    + include `Emergency_Contact`
            + user (object, required)
                + `id`: `7673eb5a-0cae-4fa8-9f81-e6da46aa2940` (string, optional)
                + tax_id: 3000080053 (string, required)
            + token (`Access_Token`)

### Dummy Confidant patient sign-up [POST /dummy/pis/confidant/sign-up]

+ Request (application/json)
    + Attributes (object)
        + `person` (object, required)
            + include `Person_Request_PIS_With_Confidant`
        + `patient_signed`: true (boolean, required)
        + `process_disclosure_data_consent`: true (boolean, required)

+ Response 201 (application/json)
    + Attributes (`Response_OK`)
        + meta (`Response__Meta`)
            + code: 201 (number)
        + data (object, required)
            + person (object, required)
                + id: `1380df72-275a-11e7-93ae-92361f002671` (string, required)
                + include `Person`
                + emergency_contact (object, required)
                    + include `Emergency_Contact`
            + user (object, required)
                + `id`: `7673eb5a-0cae-4fa8-9f81-e6da46aa2940` (string, optional)
                + tax_id: 3000080053 (string, required)
            + token (`Access_Token`)

# Data Structures
### `Access_Token`
+ value: `SnNRdCtvU0tTOENBV2dLRUZwNmIzZz09` (string, required) - oAuth access token.
+ user_id: `3ff33ced-69dc-415a-b231-c6446898335a` (string, required) - User identifier
+ name: `access_token` (string, required) - oAuth token name
+ id: `3ff33ced-69dc-415a-b231-c6446898335a` - oAuth token identifier
+ expires_at: 1498749591 (number, required) - expiration date-time timestamp
+ details (object)
    + app_id: `d290f1ee-6c54-4b01-90e6-d701748f0851` - Identifier of approval between user, applicant user and client that was used to issue access token
    + applicant_user_id: `d290f1ee-6c54-4b01-90e6-d701748f0851` - Identifier of user that initiated access token generation
    + applicant_person_id: `d290f1ee-6c54-4b01-90e6-d701748f0851` - Identifier of person that is accosiated with user who initiated access token generation
    + scope: `capitation_contracts:view capitation_contracts:create patients:view patients:create` (string, required) - List of scopes that is required in application business logic, separated by space
    + refresh_token: `my-oauth-refresh-token` (string, required) - oAuth refresh token
    + `grant_type`: `pis_auth`
    + client_id: `d290f1ee-6c54-4b01-90e6-d701748f0851` (string, required) - Client ID of authorized user

### `Access_Token_1`
+ value: `SnNRdCtvU0tTOENBV2dLRUZwNmIzZz09` (string, required) - oAuth access token.
+ user_id: `3ff33ced-69dc-415a-b231-c6446898335a` (string, required) - User identifier
+ name: `access_token` (string, required) - oAuth token name
+ id: `3ff33ced-69dc-415a-b231-c6446898335a` - oAuth token identifier
+ expires_at: 1498749591 (number, required) - expiration date-time timestamp
+ details (object)
    + app_id: `d290f1ee-6c54-4b01-90e6-d701748f0851` - Identifier of approval between user, applicant user and client that was used to issue access token
    + applicant_user_id: `d290f1ee-6c54-4b01-90e6-d701748f0851` - Identifier of user that initiated access token generation
    + applicant_person_id: `d290f1ee-6c54-4b01-90e6-d701748f0851` - Identifier of person that is accosiated with user who initiated access token generation
    + scope: `capitation_contracts:view capitation_contracts:create patients:view patients:create` (string, required) - List of scopes that is required in application business logic, separated by space
    + `grant_type`: `refresh_token`
    + client_id: `d290f1ee-6c54-4b01-90e6-d701748f0851` (string, required) - Client ID of authorized user.

### `Response_OK`
+ meta (Response__Meta, fixed-type)
+ data (object, fixed-type)

### `Response__Meta`
+ code: 200 (number) - HTTP response code.
+ url: https://example.com/resource (string) - URL to requested resource.
+ type (enum) - Type of data that is located in `data` attribute.
    - object (string) - `data` attribute is a JSON object.
    - list (string) - `data` attribute is a list.
+ `request_id`: `6617aeec-15e2-4d6f-b9bd-53559c358f97#17810` (string) - [Request ID](https://docs.apimanifest.apiary.io/#introduction/interacting-with-api/request-id). Send it with `X-Request-ID` header.

### `Response_Collection`
+ meta (Response__Meta, fixed-type)
+ data (array[], fixed-type)
+ paging (Response__Pagination, fixed-type)

### `Response__Pagination`
+ limit: 20 (number) - A limit on the number of objects to be returned, between 1 and 100. Default: 50.
+ cursors (object)
    + `starting_after`: 56c31536a60ad644060041af (string) - A cursor for use in pagination. An object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `obj_foo`, your subsequent call can include `starting_after=obj_foo` in order to fetch the next page of the list.
    + `ending_before`: 56c31536a60ad644060041aa (string) - A cursor for use in pagination. An object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with `obj_bar`, your subsequent call can include `ending_before=obj_bar` in order to fetch the previous page of the list.
+ size: 50 (number) - Total number of objects in collection.
+ has_more: false (boolean) - Is this collection have more data to load in the same style as last request loaded it.

### `media_content`
+ type: `PASSPORT` (string, required)
+ url: `https://storage.ehealth.world` (string, required)

### `Approval_Response`
+ id: `approval-1380df72-275a-11e7-93ae-92361f002671` (string) - Internal app ID, a UUID string.
+ `created_at`: `2017-04-20T19:14:13Z` (string, required) - ISO 8601 date and time in UTC timezone.
+ `updated_at`: `2017-04-20T19:14:13Z` (string, required) - ISO 8601 date and time in UTC timezone.

### `Emergency_Contact`
+ first_name: Петро (string, required)
+ last_name: Іванов (string, required)
+ second_name: Миколайович (string, optional)
+ phones (array[`Phone`], required)

### `Phone`
+ type: MOBILE (string, required) - `Dictionary PHONE_TYPE` type of phone Land Line or Mobile. At least one of type must be present. Each type can be represented only once.
+ number: `+380503410870` (string, required) - phone number in format '+38/'

### `Person`
+ first_name: Петро (string, required)
+ last_name: Іванов (string, required)
+ second_name: Миколайович (string, optional)
+ birth_date: `1991-08-19` (string, required)
+ birth_country: `Україна` (string, required)
+ birth_settlement: `Вінниця` (string, required)
+ gender: MALE, FEMALE (enum[string], required)
+ email: email@example.com (string, optional)
+ tax_id: 3126509816 (string, optional)
+ secret: secret (string, required)
+ documents (array[`Document`], required)
+ addresses (array[`Address`], required)
+ phones (array[`Phone`], optional)
+ `authentication_methods` (array[`Authentication_Method`], required)
+ preferred_way_communication: email (enum, optional) - the way how a patient wants to be reached
    - email
    - phone

### `Authentication_Method`
+ type (enum, required)
    - OTP
    - OFFLINE
    - NA
+ phone_number: `+38093*****85` (string, optional)

### `Address`
+ type: RESIDENCE (string, required) - `Dictionary ADDRESS_TYPE`. 
+ country: UA (enum[string], required) - `Dictionary COUNTRY`
+ area: Житомирська (string, required) - one of Ukraianian area
+ region: Бердичівський (string, optional) - district of area
+ settlement: Київ (string, required) - city name
+ `settlement_type`: CITY (string, required) - `Dictionary SETTLEMENT_TYPE` - type of settlement as city/town/village etc
+ `settlement_id`: `b075f148-7f93-4fc2-b2ec-2d81b19a9b7b` (string, required) - settlement identificator from uaadresses
+ `street_type`: STREET (string, optional) - `Dictionary STREET_TYPE` - type of street as street/road/line etc
+ street: `вул. Ніжинська` (string, optional) - street name
+ building: 15 (string, optional) - number of building
+ apartment: 23 (string, optional) - number of appartment
+ zip: 02090 (string, optional) - system of postal codes

### `Document`
+ type: PASSPORT (string, required) - `Dictionary DOCUMENT_TYPE`
+ number: АА120518 (string, required) - document issue number
+ `expiration_date`: `2021-02-28` (string, optional) - `document expiration date. Required for NATIONAL_ID document type`
+ issued_by: `Рокитнянським РВ ГУ МВС Київської області` (string, optional) - authority which issued the document
+ issued_at: `2017-02-28` (string, optional) - the date when document was issued

### `Person_info_Public_PIS`
+ first_name: Петро (string, required)
+ last_name: Іванов (string, required)
+ second_name: Миколайович (string, optional)
+ birth_date: `2009-07-05` (string, required)
+ birth_country: `Україна` (string, required)
+ birth_settlement: `Вінниця` (string, required)
+ gender: MALE, FEMALE (enum[string], required)
+ email: email@example.com (string, optional)
+ no_tax_id: false (boolean, required)
+ tax_id: 3999869394 (string, optional)
+ secret: secret (string, required)
+ documents (array, required)
    + (object)
        + type: BIRTH_CERTIFICATE (string, required) - `Dictionary DOCUMENT_TYPE`
        + number: АА120518 (string, required) - document issue number
        + issued_by: `Рокитнянським РВ ГУ МВС Київської області` (string, required) - authority which issued the document
        + issued_at: `2017-02-28` (string, required) - the date when document was issued
        + expiration_date: `2027-02-28` (string, optional) - the date when document expired, is necessery for those documents which has this date, ex, Temporary certificate, etc.
+ addresses (array[`Address`], required)
+ phones (array[`Phone`], optional)
+ `authentication_methods` (array[`Authentication_Method_Patient_Request`], optional)
+ unzr: `20090705-00011` (string, optional) - the record number in the demographic register
+ emergency_contact (object, required)
    + include `Emergency_Contact`
+ `confidant_person` (object, required)
    + include `Confidant_Person_PIS`
+ preferred_way_communication: email (enum, optional) - the way how a patient wants to be reached
    - email
    - phone

### `Confidant_Person_PIS`
+ person_id: `b075f148-7f93-4fc2-b2ec-2d81b19a9b7b` (string, required)
+ relation_type: PRIMARY (enum, required)
    - PRIMARY
    - SECONDARY
+ documents_relationship (array[`RelationshipDocument`], required)

### RelationshipDocument
+ type: BIRTH_CERTIFICATE (string, required) - `Dictionary DOCUMENT_RELATIONSHIP_TYPE`
+ number: АА120518 (string, required) - document issue number
+ issued_by: `Рокитнянським РВ ГУ МВС Київської області` (string, optional) - authority which issued the document
+ issued_at: `2017-02-28` (string, optional) - the date when document was issued

### `Authentication_Method_Patient_Request`
+ type (enum, required)
    - THIRD_PERSON
    - OTP
    - OFFLINE
    - NA
+ phone_number: `+380508887700` (string, optional) - required for type = OTP
+ value: `c282f8a9-e709-40aa-94b4-dde1402bf4b6` (string, optional) - requered for type = THIRD_PERSON
+ alias: `husband` (string, optional) - required it type = THIRD_PERSON,  and optional for type = OTP or OFFLINE

### `Authentication_Method_PIS_Patient`
+ type (enum, required)
    - OTP
+ phone_number: `+380508887700` (string, optional) - required for type = OTP

### `Authentication_Method_PIS_Patient_With_Confidant`
+ type (enum, required)
    - THIRD_PERSON
+ value: `c282f8a9-e709-40aa-94b4-dde1402bf4b6` (string, optional) - requered for type = THIRD_PERSON
+ alias: `husband` (string, optional) - required it type = THIRD_PERSON,  and optional for type = OTP or OFFLINE

### `Person_Request_PIS`
+ first_name: Петро (string, required)
+ last_name: Іванов (string, required)
+ second_name: Миколайович (string, optional)
+ birth_date: `2009-07-05` (string, required)
+ birth_country: `Україна` (string, required)
+ birth_settlement: `Вінниця` (string, required)
+ gender: MALE, FEMALE (enum[string], required)
+ email: email@example.com (string, optional)
+ no_tax_id: false (boolean, required)
+ tax_id: 3999869394 (string, optional)
+ secret: secret (string, required)
+ documents (array, required)
    + (object)
        + type: PASSPORT (string, required) - `Dictionary DOCUMENT_TYPE`
        + number: АА120518 (string, required) - document issue number
        + issued_by: `Рокитнянським РВ ГУ МВС Київської області` (string, required) - authority which issued the document
        + issued_at: `2017-02-28` (string, required) - the date when document was issued
        + expiration_date: `2027-02-28` (string, optional) - the date when document expired, is necessery for those documents which has this date, ex, Temporary certificate, etc.
+ addresses (array[`Address`], required)
+ phones (array[`Phone`], optional)
+ `authentication_methods` (array[`Authentication_Method_PIS_Patient`], optional)
+ unzr: `20090705-00011` (string, optional) - the record number in the demographic register
+ emergency_contact (object, required)
    + include `Emergency_Contact`
+ preferred_way_communication: email (enum, optional) - the way how a patient wants to be reached
    - email
    - phone

### `Person_Request_PIS_With_Confidant`
+ first_name: Петро (string, required)
+ last_name: Іванов (string, required)
+ second_name: Миколайович (string, optional)
+ birth_date: `2009-07-05` (string, required)
+ birth_country: `Україна` (string, required)
+ birth_settlement: `Вінниця` (string, required)
+ gender: MALE, FEMALE (enum[string], required)
+ email: email@example.com (string, optional)
+ no_tax_id: false (boolean, required)
+ tax_id: 3999869394 (string, optional)
+ secret: secret (string, required)
+ documents (array, required)
    + (object)
        + type: BIRTH_CERTIFICATE (string, required) - `Dictionary DOCUMENT_TYPE`
        + number: АА120518 (string, required) - document issue number
        + issued_by: `Рокитнянським РВ ГУ МВС Київської області` (string, required) - authority which issued the document
        + issued_at: `2017-02-28` (string, required) - the date when document was issued
        + expiration_date: `2027-02-28` (string, optional) - the date when document expired, is necessery for those documents which has this date, ex, Temporary certificate, etc.
+ addresses (array[`Address`], required)
+ phones (array[`Phone`], optional)
+ `authentication_methods` (array[`Authentication_Method_PIS_Patient_With_Confidant`], optional)
+ unzr: `20090705-00011` (string, optional) - the record number in the demographic register
+ emergency_contact (object, required)
    + include `Emergency_Contact`
+ `confidant_person` (object, required)
    + include `Confidant_Person_PIS`
+ preferred_way_communication: email (enum, optional) - the way how a patient wants to be reached
    - email
    - phone

### `Update_Person_Request_PIS`
+ first_name: Петро (string, required)
+ last_name: Іванов (string, required)
+ second_name: Миколайович (string, optional)
+ birth_date: `2009-07-05` (string, required)
+ birth_country: `Україна` (string, required)
+ birth_settlement: `Вінниця` (string, required)
+ gender: MALE, FEMALE (enum[string], required)
+ email: email@example.com (string, optional)
+ no_tax_id: false (boolean, optional)
+ tax_id: 3999869394 (string, optional)
+ secret: secret (string, required)
+ documents (array, required)
    + (object)
        + type: PASSPORT (string, required) - `Dictionary DOCUMENT_TYPE`
        + number: АА120518 (string, required) - document issue number
        + issued_by: `Рокитнянським РВ ГУ МВС Київської області` (string, required) - authority which issued the document
        + issued_at: `2017-02-28` (string, required) - the date when document was issued
        + expiration_date: `2027-02-28` (string, optional) - the date when document expired, is necessery for those documents which has this date, ex, Temporary certificate, etc.
+ addresses (array[`Address`], required)
+ phones (array[`Phone`], optional)
+ unzr: `20090705-00011` (string, optional) - the record number in the demographic register
+ emergency_contact (object, required)
    + include `Emergency_Contact`
+ preferred_way_communication: email (enum, optional) - the way how a patient wants to be reached
    - email
    - phone

### `Person_request_details`
+ id: `b075f148-7f93-4fc2-b2ec-2d81b19a9b7b` (string, required)
+ status: APPROVED (enum, required)
    - NEW
    - APPROVED
    - SIGNED
    - REJECTED
    - EXPIRED
    - CANCELED
+ channel: `PIS` (string, optional)
+ inserted_at: `2021-11-09T00:00:00.000Z` (string, required) - ISO Datetime
+ updated_at: `2021-11-09T00:00:00.000Z` (string, optional) - ISO Datetime
+ `patient_signed`: true (boolean, required)
+ `process_disclosure_data_consent`: true (boolean, required) - ознакf погодження на використання персональних даних
+ content: `Person content` (string, optional) - HTML document 
+ person (`pis_person`)

### `pis_person`
+ id: `7e9cffd9-c75f-45fb-badf-6e8d20b6a8a8` (string, required) - person id
+ first_name: Петро (string, required)
+ last_name: Іванов (string, required)
+ second_name: Миколайович (string, optional)
+ birth_date: `1991-08-19` (string, required)
+ birth_country: `Україна` (string, required)
+ birth_settlement: `Вінниця` (string, required)
+ gender: MALE, FEMALE (enum[string], required)
+ email: email@example.com (string, optional)
+ tax_id: 3126509816 (string, optional)
+ no_tax_id: true (boolean, required)
+ secret: secret (string, required)
+ documents (array[`Document`], required)
+ addresses (array[`Address`], required)
+ phones (array[`Phone`], optional)
+ preferred_way_communication: email (enum, optional) - the way how a patient wants to be reached
    - email
    - phone
+ unzr: `19900101-00099` (string, optional)
+ `emergency_contact`(`Emergency_Contact`, required)