1 Properties of a REST API method document
2 Purpose
3 Logic
4 Configuration parameters
5 Dictionaries
6 Input parameters
7 Request structure
8 Headers
9 Request data validation
- 9.1 Authorize
- 9.2 Validate request
10 Processing
- 10.1 Search existing MPI entity
11 Response structure examples
12 HTTP status codes
13 Post-processing processes
14 Technical modules where the method is used

Properties of a REST API method document

Document type	Метод REST API
Document title	REST API Search for a person [API-010-001-003-0360]
Guideline ID	GUI-0011
Author	@Yuliia Mazur (UA SoE eHealth)
Document version	1
Document status	DRAFT
Date of creation	ХХ.ХХ.ХХХХ (дата фінальної версії документа – RC або PROD)
Date of update	ХХ.ХХ.ХХХХ (дата зміни версії)
Method API ID	API-010-001-003-0360
Microservices (namespace)	MPI, IL, ADMIN FE
Component	Person
Component ID	COM-010-001
Link на API-специфікацію	https://ehealthmisapi1.docs.apiary.io/#reference/public.-medical-service-provider-integration-layer/persons/search-for-a-person
Resource	{{host}}/api.ehealth.gov.ua/api/persons
Scope	person:read
Protocol type	REST
Request type	GET
Sync/Async	Sync
Public/Private	Public

Purpose

This method allows to search for a Person (MPI) without disclosing personal data.

Logic

Method returns only requested parameters, birth place and second name in addition for manual identification on MSP side.

Configuration parameters

N/A

Dictionaries

GENDER
PHONE_TYPE

Input parameters

	Input parameter	Mandatory	Type	Description	Example

	Input parameter	Mandatory	Type	Description	Example
1	first_name	M	String		Example: `Петро`
2	last_name	M	String		Example: `Іванов`
3	second_name	O	String		Example: `Миколайович`
4	birth_date	M	String	Complete date format	Example: `1991-08-19`
5	tax_id	O	String		Example: `3126509816`
6	phone_number	O	String		Example: `+380508887700`
7	birth_certificate	O	String	birth_certificate is optional parameter for search	Example: `123456`

Request structure

See on https://ehealthmisapi1.docs.apiary.io/#reference/public.-medical-service-provider-integration-layer/persons/search-for-a-person

N/A

Headers

Key	Value	Mandatory (M/O)	Description	Example

Key	Value	Mandatory (M/O)	Description	Example
Content-Type	application/json	M	Вказує формат даних у тілі запиту/відповіді	Content-Type: application/json
Authorization	Bearer {{access_token}}	M	Вказує токен авторизації для доступу	Authorization: Bearer Token

Request data validation

When flag `USE_DEDUPLICATION_MODEL` is turned ON, use this logic.

Authorize

Request to process the request using a token in the headers.

Validate request

Validate mandatory query params
1. first_name
2. last_name
3. birth_date
Validate optional query params
1. second_name
2. tax_id
3. birth_certificate
4. phone_number (phone_number or auth_number)

Processing

Search existing MPI entity

Search only active persons - MPI.persons.is_active=true.

We are looking for such parameters:

tax_id and phone_number
tax_id and last_name( by MetaPhoneRu)
birth_certificate and phone_number
birth_certificate and last_name( by MetaPhoneRu)
phone_number and last_name( by MetaPhoneRu)
birth_date and last_name( by MetaPhoneRu) and first_name( by MetaPhoneRu)

When search by phone use mpi.person_phones.number and mpi.person_auth_method.phone_number. If person has auth_method = third_person, don't search by third_person.auth_method.phone_number

After the search we get the clusters (maximum 6) and display them one by one - persons from the first cluster, then from the second, etc.

And within each cluster we sort:

last_name_distance == 0
last_name_distance + first_name_distance + tax_id_distance (Ascending)

Return empty array if no data found

Return only requested params (if equal tax_id, birth_certificate, birth_date, phone_number), last_name(if match by metaphone ) id, first_name, second_name, gender, birth_place and merged_persons if data found.

Response structure examples

Example:

{
  "meta": {
    "code": 200,
    "url": "https://example.com/resource",
    "type": "object",
    "request_id": "6617aeec-15e2-4d6f-b9bd-53559c358f97#17810"
  },
  "data": [
    {
      "id": "b075f148-7f93-4fc2-b2ec-2d81b19a9b7b",
      "first_name": "Петро",
      "last_name": "Іванов",
      "second_name": "Миколайович",
      "birth_date": "1991-08-19",
      "gender": "FEMALE",
      "tax_id": "3126509816",
      "phones": [
        {
          "type": "MOBILE",
          "number": "+380503410870"
        }
      ],
      "birth_settlement": "Вінниця",
      "birth_country": "Україна",
      "merged_persons": [
        {
          "id": "57e30ea3-16f1-4f8e-adcd-1a05e99e2d22",
          "inserted_at": "2019-05-08T15:34:00Z",
          "merge_person_id": "bdadc2a7-7283-4f24-bc99-8d8d9808af80",
          "person_id": "b075f148-7f93-4fc2-b2ec-2d81b19a9b7b",
          "updated_at": "2019-05-08T15:34:00Z"
        }
      ]
    }
  ]
}

{
  "meta": {
    "code": 403,
    "url": "https://example.com/resource",
    "type": "object",
    "request_id": "6617aeec-15e2-4d6f-b9bd-53559c358f97#17810"
  },
  "error": {
    "type": "too_many_results",
    "message": "This API method returns only exact match results, please retry with more specific search result"
  }
}

HTTP status codes

	Response code	HTTP Status code	Message	Internal name	Description

	Response code	HTTP Status code	Message	Internal name	Description
1	Базові
2		200	Response		Надано відповідь
3		403	This API method returns only exact match results, please retry with more specific search result		Error cause: Too many results Метод повертає результати тільки із точним співпадінням. Спробуйте повторно уточнити результати пошуку.
4	Специфічні
5

Post-processing processes

N/A

Technical modules where the method is used

ЕСОЗ публічна документація

REST API Search for a person [API-010-001-003-0360]

Analytics