MCI Patient API

Context: Various Government Ministries, divisions, Directorates and departments retain Citizen relevant information in their own forms and databases. Such that each of such organization can effectively maintain unified meaningful information for Citizens, Bangladesh Cabinet recommends a Citizen Core Data Structure (CCDS) be adopted and maintained, for semantic interoperability, so that there is a standard way of indexing enterprise information. CCDS is meant to simplify information management through consistent classification and assignment of standard identifiers to the data names. This approach is very similar to Universal Data Element Framework (UDEF). Although Bangladesh CCDS does not currently adopt the generic UDEF framework, but the intention is that such following of metadata definitions of the CCDS elements will ensure initial country-wide e-Governance applications interoperability. The CCDS recommendation speculatd that applying UDEF may unncessarily complicate its adoption and delay; however CCDS can easily adopt UDEF at a later stage for international and industry wide interoperability when situation so warrants.

Bangladesh Cabinet Portal - CCDS Document

1. Format

The API is based on REST convention and would use JSON as the default data format.

2. Authentication

All the endpoints in this Patient API requires authentication. The requesting party should include the API key in the request header under the key “Auth-Token”.

3. Validations

Please see details in attached Word Doc

CCDS.doc

4. Definitions

Described below are the various API definitions.

Create Patient

Parameters:

Note: The required fields are marked in BLUE

Example:

curl -XPOST /api/v1/patients -d “{
"nid": "13223432134567853",
"bid": null,
"uid": null,
"name_english": “Anis Ahmad”,
"gender": 1,
"present_address": {
   "division": 1,
   "district": 1
   ...
}
}

Response:

Status: 201 Created

Location: http://www.mci-local.dev/api/v1/patients/1234567890

{
"hid": "1234567890",
"nid": "13223432134567853",
"bid": null,
"uid": null,
"name_english": “Anis Ahmad”,
"name_bangla": null,
"date_of_birth": null,
"place_of_birth": null,
"present_address": {
   "division": 1,
   "district": 1
   ...
}

"gender": 1,
}

Full Create API Fields

{
 "nid": "19901678901234567",
 "uid": "02781230123",
 "bin_brn": "76543210123456780",
 
 "name_bangla": "সুজানা জাফর খান",
 "given_name": "Suzana Zafar",
 "sur_name": "Khan",

 "date_of_birth": "1990-02-28",
 "dob_type":"1",
 
 "gender": "F",
 "occupation": "02",
 "edu_level": "15",
 "religion": "1",
 "blood_group": "5",
 "disability": "0",
 "ethnicity": "11",
 "place_of_birth": "Narayanganj",
 "nationality": "bangladeshi",
 "marital_status": "2",

 "phone_number": 
{
 "country_code": "88",
 "area_code": null,
 "number": "01678904560",
 "extension": null
 },

 "primary_contact": "Farzana Zebin",

 "primary_contact_number": 
{
 "country_code": null,
 "area_code": "02",
 "number": "9887766",
 "extension": "0987"
 },

 "relations": [
 {
 "type": "FTH",
 "name_bangla": "মোঃ সাকিব আলী খান",
 "given_name": "Md. Sakib Ali",
 "sur_name": "Khan",
 "nid": "1951557890163",
 "uid": "09811217611",
 "bin_brn": "76545678901633456",
 "hid": "58767890987"
 },
 {
 "type": "MTH",
 "name_bangla": "শবনম চৌধুরী",
 "given_name": "Shabnam",
 "sur_name": "Chowdhury",
 "nid": "1960567890163",
 "uid": "03689119011",
 "bin_brn": "92345678901633456",
 "hid": "56456789098"
 },
 {
 "type": "SPS",
 "name_bangla": "আজাদ খান",
 "given_name": "Azad",
 "sur_name": "Khan",
 "nid": "1990567890163",
 "uid": "38761111111",
 "bin_brn": "52345678901633456",
 "hid": "56789098765",
 "marriage_id": "12345678",
 "relational_status": "3"
 }

 ],
 "present_address": 
{
 "address_line": "Dhaka",
 "division_id": "10",
 "district_id": "04",
 "upazila_id": "09",
 "city_corporation_id": "99",
 "union_or_urban_ward_id": "13",
 "rural_ward_id": null,

 "area_mouja": "Dhanmondi",
 "village": "Lalmatia",
 "holding_number": "House # 7/9 (3rd floor), Block B, Lalmatia",
 "street": "Plot 51,Satmasjid Road",
 "post_office": "Mohammadpur",
 "post_code": "1209",
 "country_code": "050"
 },

 "permanent_address":
 {
 "address_line": "Barishal",
 "division_id": "10",
 "district_id": "04",
 "upazila_id": "09",
 "city_corporation_id": "20",
 "union_or_urban_ward_id": "04",
 "rural_ward_id": null,

 "area_mouja": "Barguna",
 "village": "Amtali",
 "holding_number": "2/KA Palace House",
 "street": "Road no.27",
 "post_office": "Amtali",
 "post_code": "1225",
 "country_code": "050"
 },

"status": {
        "type": "2",
        "date_of_death": "1990-02-28"
 },



 "confidential": "No"
 } }

MCI field definitions based on CCDS

#	Field Name	JSON Key	Type	Description
1.1	UHID	hid	11 Char	Unique Health ID
1.2	NID	nid	13 or 17 digits, Only numbers. No spaces, special characters allowed.	For those who already have NID
1.3	BIN / BRN	bin_brn	17 digits. No alphabets, space or special characters allowed.	For those who do NOT have NID (Only for those who were below 18 on 2009)
1.4	UID	uid	Alphanumeric. No space or special characters allowed.	This is the proposed Unique Identifier for ALL the Citizens and Residents in Bangladesh. It will be system generated 11 characters Alphanumeric Number during the National Population Registration building process. This is very important for hassle-free Citizens' Services with integration of various services.
2.1.1	Name in Bangla	name_bangla	125 Char	Full name in Bangla. Citizens may have difficulties in Bangla typing
2.1.2	Given Name in English	given_name	100 Char, space allowed, all apecial characters including dot is allowed, numbers are also allowed.	Name that is common in the family
2.1.3	Surname in English	sur_name	25 Char, no spaces, no special characters, numbers are allowed.	Name that are common in the family
3.1.1	Father’s name (Bangla)	name_bangla	125 Char	Full name in Bangla. Citizens may have difficulties in Bangla typing
3.1.2	Father’s given name (English)	given_name	100Char, space, numbers, alphabets, special characters, all accepted.
3.1.3	Father’s surname (English)	sur_name	25 Char
3.1.4	Father's Identity (UID)	uid	Char	Father's UID: Unique available Identifier of the Citizen's Father. the proposed UID from NPR. This is also needed for relationship verification. Very important for Land Mutation and inheritance issues.
3.1.5	Father's Identity (NID)	nid	13 or 17 Char	Father's NID: Unique available Identifier of the Citizen's Father. NID from EC, This is also needed for relationship verification. Very important for Land Mutation and inheritance issues.
3.1.6	Father's Identity (BRN)	bin_brn	17 Char	Father's BRN: BRN from BRIS. This is also needed for relationship verification. Very important for Land Mutation and inheritance issues.
3.2.1	Mother’s given name (English)	given_name	100Char, space, numbers, alphabets, special characters, all accepted.100 Char	First name in English
3.2.2	Mother’s surname (English)	sur_name	25 Char	Last name in English
3.2.3	Mother’s name (Bangla)	name_bangla	125 Char	Full name in Bangla. Citizens may have difficuties in Bangla typing
3.2.4	Mother's Identity (UID)	uid	Char	Mother's UID: Unique available Identifier of the Citizen's mother. the proposed UID from NPR.
3.2.5	Mother's Identity (NID)	nid	13 or 17 Char	Mother's NID: Unique available Identifier of the Citizen's mother. NID from EC,
3.2.6	Mother's Identity (BRN)	bin_brn	17 Char	Mother's BRN: BRN from BRIS. This is also needed for relationship verification.
4.	Date of birth	date_of_birth	10 Char, No limit on the age.	Date of birth as in NID or BIN [ yyyy-mm-dd]
5.	Place of birth	place_of_birth	20 Char. Alphabets, numbers, special characters allowed. Space not allowed.	RMO + Area/Village
6.	Present address	present_address	Address Block. Must accept only Bangladesh address (verified in country code)	From BBS
7.	Permanent Address	permanent_address	Address Block (can accept foreign address, in which case the hierarchy fields will be disabled. )	From BBS
8.	Gender	gender	1 Char	From BBS
9.1	Marital status	marital_status	1 Char
9.2	Relational status	relational_status	1 Char
9.3	Marriage ID	marriage_id	8 Char, alphanumeric allowed, spaces & special characters not allowed	Proposed Marriage ID for a particular marriage of a Citizen. Needed for the social reality in Bangladesh to record multiple spouses for males. May also be used to track multiple marriage events for either male or female Citizen to resolve inheritance issues.
9.3.1	Spouse’s name (Bangla)	name_bangla	125 Char
9.3.2	Spouse’s given name (English)	given_name	100Char, space, numbers, alphabets, special characters, all accepted.
9.3.3	Spouse’s surname (English)	sur_name	25 Char, numbers and alphabets allowed. Space and special characetrs not allowed.
9.3.4	Spouse’s Identity (NID)	nid	13 or 17 Char	Spouse UID / NID / BRN: Unique available Identifier of the Citizen's Spouse. Either the proposed UID from NPR, or the NID from EC, or the BRN from BRIS. This is also needed for relationship verification. Very important for Land Mutation and inheritance issues.
9.3.5	Spouse's Identity (BRN)	bin_brn	17 Char
9.3.6	Spouse's Identity (UID)	uid	Char
10	Religion	religion	1 Char	From BBS
11	Occupation	occupation	2 Char	From BBS
12	Blood group	blood_group	1 Char	From BBS
13	Nationality	nationality	50 Char, space, alphabets, numbers, special characters allowed.	From BBS
14	Educational qualification	edu_level	2 Char	From BBS
15	Disability	disability	2 Char	From BBS
16	Ethnicity	ethnicity	2 Char	From BBS
17	Biometric IDs		TBD
18	Country code	country_code	No length validation. Spaces, alphabets,special characters not allowed.	Digits (no symbol)
19	Area code	area_code	No length validation. Spaces, alphabets,special characters not allowed.	Digits (no symbol)
20	Number	number	12 digits	Digits (no symbol)
21	Extension	extension	No length validation. Spaces, alphabets,special characters not allowed.	Digits (no symbol)
22	Primary contact	primary_contact	100 Char, spaces, numbers, spacial characters allowed
23	Status	status	1 Char
24	Date of death	date_of_death	10 Char
25	Confidential	confidential		Yes , No
26	Date of birth type	dob_type	1 Char

CCDS fields validations.pdf

Appendix A

a. Address Object

The address object would contain the following fields:

The table below represents an expansion of the Address Field number 6 & 7:

	Address Blocks	Json Key	Size	Code	Description
A1	Holding number	holding_number	50 Char		From BBS
A2	Street	street	50 Char		From BBS
A3	Area/mouja	area_mouja	50 Char		From BBS
A4	Village	village	50 Char		From BBS
A5	Post Office	post_office	50 Char		From POSTOFFICE
A6	Post Code	post_code	4 Char	4 Digit	From POSTOFFICE
A7	Upazila	upazila_id	2 Char	2 Digit	From BBS
A8	Union/urban ward id	union_or_urban_ward_id	2 Char	2 Digit	From BBS
A9	Rural ward id	rural_ward_id
A10	City Corporation/Pouroshobha	city_corporation_id	2 Char	2 Digit	From BBS
A11	Zila (District)	district_id	2 Char	2 Digit	From BBS
A12	Division	division_id	2 Char	2 Digit	From BBS
A13	Country code	country_code	3 Char	3 Digit	From BBS
A14	Address line	address_line	3 to 256 Char		Free text

b. Marital Info Object

The marital info object would contain the following fields:

- The marital status field will be outside of the marital info object.

Name	Type	Description
marriage_id	string	Marriage ID from marriage registration system
name_bangla	string	Spouse’s full name in bangla
given_name	string	Spouse’s given name in english
sur_name	string	Spouse’s sur name in english
nid/bin_brn/uid	string	Spouse’s NID/BRN/UID
relational_status	number	Spouse's relational status

c. Gender Code

Value	Code
Male	M
Female	F
Others	O

d. Marital Status Code

Value	Code
Unmarried	1
Married	2
Widow/Widower	3
Separated	4
Divorced	5

e. Relational Status Code

Value	Code
Married	2
Widow/Widower	3
Separated	4
Divorced	5

f. Religion Code

Value	Code
Muslim	1
Hindu	2
Buddho	3
Christian	4
Refuse to disclose	8
Not a believer	9
Others	0

g. Blood Group Code

Value	Code
O⁺ ( O Positive)	1
O^- ( O Negative)	2
A+ ( A Positive)	3
A- ( A Negative)	4
B+ ( B Positive)	5
B- ( B Negative)	6
AB⁺( AB Positive)	7
AB^-( AB Negative)	8

h. Disability Code

Value	Code
Null	0
Mute	1
Visual impairment	2
Hearing impairment	3
Physical	4
Psychological	5

i. Status Code

Value	Code
Alive	1
Deceased	2
Unknown	3

j. Confidential Code

Value	Code
Confidential	Yes
Non-confidential	No

k. Death of Birth Type

Value	Code
Declared	1
Verified	2
Estimated	3

l. Occupation Code

See the attached word document (CCDS)

m. Education Code

See the attached word document (CCDS)

Response Codes

Success:

Single resource operation:

response code: 201 , id: healthid (create)

response code: 202 , id: healthid (update)

response code: 200 , id: healthid (ok)

{
    http_status: 200/201/202
    id : {RESOURCE_ID} 
}

2. Resource collections:

{
    http_status: 200
    results : {[],[],[]} 
        additional_info : {}
}

Errors:

Error Categories: (Application error code series)

1. Validation error - 1000
2. Invalid request - 2000
3. Permission Error - 3000

Validation Error-

1. Required - 1001
2. Pattern - 1002
4. DataType - 1003
3. Incorrect Value - 1004 (Like registries lookup)
4. Server Error - 500

5. Dependency error -1005

For example-

{

error_code: 1000
http_status: 400
message: "validation error"
-
errors: [
- -
  {
  - code: 1002
  - field: "sur_name"
  - message: "invalid sur_name"
  }
]

}

Invalid Request-

1. Invalid JSON - 2001
2. Unrecognized field - 2002

For example-

{

error_code: 2000
http_status: 400
message: "invalid.request"
-
errors: [
- -
  {
  - code: 2002
  - field: "patient_gender"
  - message: "Unrecognized field: 'patient_gender'"
  }
]

}

Permission Error-

1. Field not permitted for the request -3001

2. Field update not permitted -3002

100Char, space, numbers, alphabets, special characters, all accepted.

MCI Patient API

Create Patient

MCI field definitions based on CCDS

Field Name

50 Char, space, alphabets, numbers, special characters allowed.

From BBS

2 Char

From BBS

2 Char

From BBS

2 Char

From BBS

Biometric IDs

TBD

a. Address Object

b. Marital Info Object

c. Gender Code

d. Marital Status Code

e. Relational Status Code

f. Religion Code

g. Blood Group Code

h. Disability Code

i. Status Code

j. Confidential Code

k. Death of Birth Type

l. Occupation Code

m. Education Code

Response Codes

Success:

Errors: