MCI Patient APIs

1. Format

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

2. Authentication

All APIs described below need authentication. The client_id and From are given when registering with the Identity Provider. The signin API of Identity Provider should be used to get the auth token(To be provided in the "X-Auth-Token" header). Refer the Identity Provider page for more information on how to use the Identity Provider APIs.

3. Validations

For Validations on the API fields below and codes used refer this page.

Described below are the various API definitions.

Create Patient API

Request :

POST  https://{mci_service}/api/v1/patients

Headers :

X-Auth-Token : {auth token returned from Identity Service Provider}

client_id : {client id of requester in Identity Service Provider}

From : {email_id of requester registered in Identity Service Provider}

Content-Type : application/json

Body (example with mandatory fields) :

{
	"given_name": "Sara",
	"sur_name": "M",
	"date_of_birth": "1970-11-06",
	"gender": "F",
	"present_address": {
		"address_line": "37, Good Street,",
		"division_id": "30",
		"district_id": "33",
		"upazila_id": "34"
	}
}

Response Codes :

201 - Created

400 - Bad Request (incorrect data)

401 - Unauthorized (check X-Auth-Token, From and client_id in headers)

403 - Access Denied (check roles in identity provider service)

Response :

{
  "http_status": 201,
  "id": "98001038192"
}

The id field contains the health id of the patient.

Create Patient API can be called with or without "hid" field.

Creating a patient without the "hid" field will automatically create a Health ID for the patient. The response returns the created Health ID.
Creating a patient with the "hid" field. (The organization for which a Health ID was assigned, will only be able to create a patient using that Health ID)
If the organization to whom the Health ID was assigned and the organization trying to create the patient is different the create patient will fail.
In addition to the above example payload it should have field hid as well. ("hid" = "9xxxxxxxxxx")

Example with hid field

{
	"given_name": "Sara",
	"sur_name": "M",
	"date_of_birth": "1970-11-06",
	"gender": "F",
	"present_address": {
		"address_line": "37, Good Street,",
		"division_id": "30",
		"district_id": "33",
		"upazila_id": "34"
	},
	"hid": "91001038152"
}

Example with all fields

{
    "nid": "19901678901234567",
    "uid": "02781230123",
    "bin_brn": "76543210123456780",
	"household_code":"233",
    "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"
    },
    "hid_card_status" : "REGISTERED",
    "confidential": "No"
}

Update Patient API :

Request :

PUT  https://{mci_service}/api/v1/patients/{health_id}

Headers :

X-Auth-Token : {auth token returned from Identity Service Provider}

client_id : {client id of requester in Identity Service Provider}

From : {email_id of requester registered in Identity Service Provider}

Content-Type : application/json

Body should contain fields which are to be modified (May or may not include other feilds).

Example :

{
	"given_name": "Sohel",
	"sur_name": "Masud"
}

Response:-

{
	"http_status": 202,
	"id": "98001023053"
}

Response Codes :

202 - Updated

400 - Bad Request (incorrect data)

401 - Unauthorized (check X-Auth-Token, From and client_id in headers)

403 - Access Denied (check roles in identity provider service)

Get Patient API :

Request :

GET  https://{mci_service}/api/v1/patients/{health_id}

Headers :

X-Auth-Token : {auth token returned from Identity Service Provider}

client_id : {client id of requester in Identity Service Provider}

From : {email_id of requester registered in Identity Service Provider}

Response Codes :

200 - ok

401 - Unauthorized (check X-Auth-Token, From and client_id in headers)

403 - Access Denied (check roles in identity provider service)

Example Response

{ 
  "hid": "98001023053",
  "given_name": "Sara",
  "sur_name": "M",
  "date_of_birth": "1970-11-06T00:00:00.000+05:30",
  "dob_type": "1",
  "gender": "F",
  "present_address": {
    "address_line": "37, Good Street,",
    "division_id": "30",
    "district_id": "33",
    "upazila_id": "34",
    "country_code": "050"
  },
  "confidential": "No",
  "created_by": {
    "facility": null,
    "provider": {
      "id": "113112",
      "name": null
    },
    "admin": null
  },
  "updated_by": {
    "facility": null,
    "provider": {
      "id": "113112",
      "name": null
    },
    "admin": null
  },
  "status": {
    "type": "1"
  },
  "active": true,
  "hid_card_status": "REGISTERED",
  "provider": null,
  "created": "2017-03-31T14:45:37.095+05:30",
  "modified": "2017-03-31T14:45:37.095+05:30"
}

Errors:

Error Categories: (Application error code series)

Validation error - 1000
Invalid request - 2000
Permission Error - 3000

Validation Error-

Required - 1001
Pattern - 1002
DataType - 1003
Incorrect Value - 1004 (Like registries lookup)
Server Error - 500
Dependency error -1005

Invalid Request-

Invalid JSON - 2001
Unrecognized field - 2002

Permission Error-

Field not permitted for the request -3001
Field update not permitted -3002

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