NAV Navbar
console

OpenMRS REST API

Welcome to the OpenMRS REST API documentation! OpenMRS is a software platform and a reference application which enables the design of a customized medical records system with no programming knowledge (although medical and systems analysis knowledge is required).

It is a common platform upon which medical informatics efforts in developing countries can be built. The system is based on a conceptual database structure which is not dependent on the actual types of medical information required to be collected or on particular data collection forms and so can be customized for different uses.

This document provides High level documentation of OpenMRS APIs with code samples which are in the dark area to the right. If you find anything missing or incorrect please consider proposing revision on GitHub.

This documentation serves as a reference to the bespoke REST API for OpenMRS.

Getting Started

If you are new to OpenMRS checkout the Getting Started as a Developer Guide from OpenMRS

Current version

Purpose

Schema

All API access is over HTTPS, and can be accessed from https://demo.openmrs.org/openmrs/ws/rest/v1. All data is sent and received as JSON.

curl -X GET "https://demo.openmrs.org/openmrs/ws/rest/v1/concept"
connection: keep-alive
content-length: 9731
content-type: application/json;charset=UTF-8
date: Wed, 20 Nov 2019 14:13:54 GMT
etag: "04c83ff0cf2cc35cf05a2075ad117df83"
server: nginx/1.10.3 (Ubuntu)
strict-transport-security: max-age=15768000

Resources

Subresources

Examples

Adding a person name.

POST /openmrs/ws/rest/v1/person/:target_person_uuid/name
{
  "givenName": "John",
  "familyName": "Smith"
}

Editing a person's name.

POST /openmrs/ws/rest/v1/person/:target_person_uuid/name/:target_name_uuid
{
  "givenName": "Johnny"
}

Instead, these should be queries on the encounter resource:

Get an encounter list for a specific patient.

 GET /encounter?patient=:target_patient_uuid

Get an encounter list for a specific location.

 GET /encounter?location=:target_location_uuid

Resources with subtypes

Examples

POST /openmrs/ws/rest/v1/order
{"t": "testorder", /*... and other properties */}

Get encounter orders of drug order subtype.

GET  /openmrs/ws/rest/v1/order?&t=drugorder&v=full'

Authentication

Retrieve session token

The session token is retrieved using Basic authentication on the /session endpoint. The response will include a JSESSIONID in the header. This session ID is also included in the response object

GET /openmrs/ws/rest/v1/session 
  -H 'Authorization: Basic Auth <base64 encoded username:password'

HTTP/1.1 200 OK
Set-Cookie: JSESSIONID=FB0629C001449CE14DF1078ACDDBA858; Path=/openmrs; HttpOnly
{
    "authenticated": true,
    "locale": "en_GB",
    "sessionId": "FB0629C001449CE14DF1078ACDDBA858",
    "user": {
        "systemId": "admin",
    }
}

The sessionId token should be passed with all subsequent calls as a cookie named JSESSIONID.

Logout User/End session

DELETE /openmrs/ws/rest/v1/session -H 'Accept: application/json'
-H 'Authorization: Basic Auth' (required to indetify the user)

Changing Password

Since version 2.17 of the webservices.rest module:

POST /openmrs/ws/rest/v1/password/:target_user_uuid 
{
  "newPassword" : "newPassword"
}
POST /openmrs/ws/rest/v1/password 
{
  "oldPassword" : "oldPassword",
  "newPassword" : "newPassword"
}

Getting all location without authentication

While fetching individual locations requires authentication, you can get a list of available locations by passing the special tag "Login Location" as a query parameter.

GET /openmrs/ws/rest/v1/location?tag=Login+Location' 

User

User Overview

A User in OpenMRS is an account that a person may use to log into the system.

The real-life person is represented by a Person record in OpenMRS, and a person may have more than one user account. If you want a patient to be able to view her record in OpenMRS, then you need to create a user account and link it to the patient's person record.

Available operations for User

  1. List users
  2. Create a user
  3. Update a user
  4. Delete a user

List user

List all non-retired users.

Quickly filter users with given query parameters. Returns a 404 Not Found status if the user does not exist. If not logged in to perform this action, a 401 Unauthorized status is returned.

Query Parameters

Parameter Type Description
q Search Query Filter users by username or system ID
GET /user?
q=user1

Get user by UUID.

Retrieve a user by its UUID. Returns a 404 Not Found status if the user does not exist. If not logged in to perform this action, a 401 Unauthorized status is returned.

GET /user/:target_user_uuid

Create a user

Attributes

Parameter Type Description
name String Name of the user
description `String Description of the user
username `String username of the user
password `String password of the user
person String person resource associated with the user
systemId String a unique identifier assigned to each user
roles Array[] : role a list of roles attributed to the user
userProperties JSON Object A set of key value pairs. Used to store user specific data
secretQuestion String A secret question chosen by the user
POST /user
{
  "name": "Mohit Kumar",
  "description": "A GSoD participant."
  "username": "batbrain7"
  "password": "******"
  "person" :
        {
        "names": [
            {
                "givenName": "Mohit",
                "familyName": "Kumar"
            }
        ],
        "gender": "M",
        "birthdate": "1997-09-02",
        "addresses": [
        {
         "address1": "30, Vivekananda Layout, Munnekolal,Marathahalli",
        "cityVillage": "Bengaluru",
        "country": "India",
        "postalCode": "560037"
        }
    ]
},
"systemId": "string",
"userProperty": {},
"secretQuestion" : "What is the name of your high school?"
}

Update a user

Attributes

Parameter Type Description
name String Name of the user
description `String Description of the user
username `String username of the user
password `String password of the user
person String person resource associated with the user
systemId String a unique identifier assigned to each user
roles Array[] : role a list of roles attributed to the user
userProperties JSON Object A set of key value pairs. Used to store user specific data
secretQuestion String A secret question chosen by the user
POST /user/:target_user_uuid
{
  "name": "Mohit Sharma",
  "description": "An OpenMRS Developer."
  "username": "batbrain7"
  "password": "******"
  "person" :
        {
        "names": [
            {
                "givenName": "Mohit",
                "familyName": "Sharma"
            }
        ],
        "gender": "M",
        "birthdate": "1997-09-02",
        "addresses": [
        {
         "address1": "30, Vivekananda Layout, Munnekolal,Marathahalli",
        "cityVillage": "Bengaluru",
        "country": "India",
        "postalCode": "560037"
        }
    ]
},
"systemId": "string",
"userProperty": {},
"secretQuestion" : "In which year did you graduate"
}

Delete a user

Query Parameters

Parameter Type Description
purge Boolean The resource will be voided unless purge = ‘true’
DELETE /user/:target_user_uuid?purge=true

Role

Role Overview

A Role represents a group of privileges in the system. Roles may inherit privileges from other roles, and users may have one or more roles.

Available operations for Role.

  1. List roles
  2. Create a role
  3. Update a role
  4. Delete a role

List roles

GET /role
GET /role/:target_role_uuid

Create a role

POST /role
{
  "name": "Clinician",
  "description": "A provider assisting the Lead Surgeon.",
  "privileges": [{
      "name": "Delete Patients",
      "description": "Able to delete patients"
  }]
}

Update a role

POST /role
{
  "name": "Configures Forms",
  "description": "Manages forms and attaches them to the UI"
}

Delete a role

DELETE /role/:target_role_uuid?purge=true

Person

Person Overview

Every individual who is referred to in a patient record in OpenMRS is stored in the system as a Person. These include Patients, any patient relative or caretaker, Providers, and Users.

All Persons have these characteristics.

Subresource types

Names

A person can have one or more names, one of which must be marked as the preferred name. The preferred name will be displayed in search results and patient screens.

Addresses

A person may have zero or more contact addresses. You may configure the format of these addresses for your particular locale.

Person Attributes

To support your local needs, you can define additional information about the people in your system, on top of those that are natively supported by OpenMRS. You can define the datatype of a Person Attribute, as well as any constraints on the possible values, using metadata. This metadata is called a Person Attribute Type.

Person Attributes are suitable for storing other information. But historical values of person attributes are not retained. For example, you should use a person attribute to record a patient's contact telephone number. This information may change, but if it does so, the system need only store the most recent value, and need not retain previous values. It is not appropriate to use a person attribute to store something like the patient's height, which is recorded at a given point in time, but can be expected to change and should be tracked as it does so.

Available Operations for Person type

  1. Search Persons
  2. Create Persons
  3. Update Persons
  4. Delete Persons
  5. List person names
  6. Create person name
  7. Update person name
  8. Delete person name
  9. List person addresses
  10. Create person address
  11. Update person address
  12. Delete person address
  13. List person attributes
  14. Create person attribute
  15. Update person attribute
  16. Delete person attribute

Search Persons

GET /person?q=john
GET /person/:target_person_uuid

Create a person

POST /person
{
    "names": [
        {
        "givenName": "Mohit",
        "familyName": "Kumar"
        }
    ],
    "gender": "M",
    "birthdate": "1997-09-02",
    "addresses": [
        {
        "address1": "30, Vivekananda Layout, Munnekolal,Marathahalli",
        "cityVillage": "Bengaluru",
        "country": "India",
        "postalCode": "560037"
        }
    ]
}

Update a person

POST /person/:target_person_uuid
{
    "gender": "M",
    "birthdate": "1997-01-13",
}

Delete a person

DELETE /person/:target_person_uuid?purge=true

List person name

GET /person/:target_person_uuid/name
GET /person/:target_person_uuid/name/:target_name_uuid

Create person name subresource

POST person/:target_person_uuid/name
{ 
    "givenName": "Mohit",
    "familyName": "Kumar",
    "preferred": true,
    "prefix": "Mr."
}

Update person name

POST person/:target_person_uuid/name
{ 
    "givenName": "Mohit",
    "familyName": "Verma",
    "preferred": true,
    "prefix": "Dr."
}

Delete a person name subresource

DELETE /person/:target_person_uuid/person/:target_name_uuid

List person address subresource

GET /person/:target_person_uuid/address
GET /person/:target_person_uuid/address/:target_address_uuid

Create person address subresource

POST person/:target_person_uuid/address
{ 
    "address1": "30, Vivekananda Layout, Munnekolal,Marathahalli",
    "cityVillage": "Bengaluru"
    "stateProvince": "Karnataka",
    "postalCode": "560037",
    "lattitude": "28.65033",
    "longitude": "77.304255"
}

Update person address subresource

POST person/:target_person_uuid/address
{ 
    "address1": "30, Vivekananda Layout, Munnekolal,Marathahalli",
    "cityVillage": "Bengaluru"
    "stateProvince": "Karnataka",
    "postalCode": "560037",
    "lattitude": "28.65033",
    "longitude": "77.304255"
}

Delete a person address subresource

DELETE /person/:target_person_uuid/person/:target_address_uuid

List person attribute subresource

GET /person/:target_person_uuid/attribute
GET /person/:target_person_uuid/name/:target_attribute_uuid

Create person attribute subresource

POST person/:target_person_uuid/attribute
{ 
    "attributeType": "8d8718c2-c2cc-11de-8d13-0010c6dffd0f",
    "value": "Birthplace",
}

Update person attribute subresource

POST person/:target_person_uuid/attribute
{ 
    "attributeType": "8d8718c2-c2cc-11de-8d13-0010c6dffd0f",
    "value": "Birthplace",
}

Delete a person attribute subresource

DELETE /person/:target_person_uuid/person/:target_attribute_uuid

Person Attribute Type

Person Attribute Type Overview

Available operations.

  1. List person attribute types
  2. Create a person attribute type
  3. Update a person attribute type
  4. Delete a person attribute type

List person attribute types

GET /personattributetype?q=race
GET /personattributetype/:target_person_attribute_type_uuid

Create a person attribute type

POST /personattributetype
{
    "name": "Edit Civil Status",
    "description": "Able to manage the civil status of persons",
    "format": "org.openmrs.Concept",
    "foreignKey": 1054,
    "searchable": false,
    "editPrivilege": {
        "name": "Super User",
        "description": "Change and update the person attribute type"
    }
}

Update a person attribute type

POST /personattributetype
{
    "name": "Edit Civil Status",
    "description": "Able to manage the civil status of persons",
    "format": "org.openmrs.Concept",
    "foreignKey": 1054,
    "searchable": true,
    "editPrivilege": {
        "name": "Super User",
        "description": "Change and update the person attribute type"
    }
}

Delete a person attribute type

DELETE /personattributetype/:target_person_attribute_type_uuid?purge=true

Patients

Patients Overview

Subresource types of Patient

PatientIdentifier (Identifier)

Allergy

Available operations for Patients

  1. List Patients
  2. Create a patient record
  3. Update a patient record
  4. Delete a patient record
  5. List patientIdentifier sub resource
  6. Create patientIdentifier sub resource with properties
  7. Update patientIdentifier sub resource
  8. Delete patientIdentifier sub resource
  9. List allergy sub resource
  10. Create allergy sub resource with properties
  11. Update allergy sub resource
  12. Delete allergy sub resource

Search patients

GET /patient?
country=india
&gender=M
GET /patient/:target_patient_uuid

Create a patient

POST /patient
{
    "person": "uuid",
    "identifiers": [
    {
        "identifier": "string",
        "identifierType": "uuid",
        "location": "uuid",
        "preferred": true
    }
    ]
}

Update a patient

    POST /patient/:target_patient_uuid
    -d modified_patient_object

Delete a patient

DELETE /patient/:target_patient_uuid?purge=true

List patientIdentifier sub resources

GET /patient/:target_patient_uuid/identifier
GET /patient/:target_patient_uuid/identifier/:target_identifier_uuid

Create a patientIdentifier sub resource with properties

POST patient/:target_patient_uuid/identifier
{ 
    "identifier" : "string",
    "identifierType" : "target_identifer_uuid",
    "location" : "target_location_uuid",
    "preferred" : true/false
}

Update patientIdentifier sub resource with properties

POST patient/:target_patient_uuid/identifier/:target_identifier_uuid
{ 
"identifier" : "string",
"identifierType" : "target_identifer_uuid",
"location" : "target_location_uuid",
"preferred" : true/false
}

Delete patientIdentifier sub resource with properties

DELETE /patient/:target_patient_uuid/identifier/:target_identifier_uuid

List allergy subresources

GET /patient/:target_patient_uuid/allergy/:target_allergy_uuid

Create a allergy sub resource with properties

POST patient/:target_patient_uuid/allergy
{
    "allergen": {},
    "severity": {
        "uuid": "string"
    },
    "comment": "string",
    "reactions": [
        {
            "allergy": {
            "uuid": "string"
        },
        "reaction": {
            "uuid": "string"
        }
    }
]
}

Update allergy sub resource with properties

POST patient/:target_patient_uuid/allergy/:target_allergy_uuid
{
"allergen": {},
"severity": {
    "uuid": "string"
},
"comment": "string",
"reactions": [
    {
        "allergy": {
        "uuid": "string"
    },
    "reaction": {
        "uuid": "string"
    }
}
]
}

Delete allergy sub resource with properties

DELETE /patient/:target_patient_uuid/allergy/:target_allergy_uuid

PatientIdentifierType

PatientIdentifierType Overview

Administrators define what types of identifiers they will collect. These range from National ID numbers, to driver's license numbers, to per-hospital medical record numbers.

Properties on PatientIdentifierType:

Available operations for PatientIdentifierType

  1. List PatientIdentifierType resources
  2. Create a patientIdentifierType record
  3. Update a patientIdentifierType record
  4. Delete a patientIdentifierType record

List PatientIdentifierType resource

GET /patientidentifiertype
GET /patientidentifiertype/:target_patientIdentifierType_uuid

Create a patientIdentifierType

Properties

Parameter Type Description
name string label for the identifier
description string a small description about the patientIdentifier
format string a regular expression defining what the identifier text should contain
formatDescription string an optional description of the regular expression
required boolean a true/false whether every patient MUST have this type
checkDigit boolean a true/false whether this identifier has a checkdigit at the end
validator string org.openmrs.patient.IdentifierValidator
locationBehavior "REQUIRED" or "NOT USED" behavior of the location with respect to the identifier
uniquenessBehavior string specify the uniqueness of the behaviour, it can be either Unique, Non Unique or Location.
POST /patientidentifiertype
{
    "name": "Wilson Hosp MRN",
    "description": "Wilson Hospital Medical Record Number",
    "format": "\d{1,10}-\d",
    "formatDescription": "Up to ten digts followed by a hyphen and another digit",
    "required": true,
    "validator": "org.openmrs.patient.impl.LuhnIdentifierValidator",
    "checkDigit": true,
    "locationBehavior": "REQUIRED",
    "uniquenessBehavior": "Unique"
}

Update a patientIdentifierType

POST /patientidentifertype/:target_patientidentifiertype_uuid
{
    "name": "Amani Identifier",
    "description": "Medical record number for Amani Health System",
    "format": "\\d{1,10}-\\d",
    "formatDescription": "Up to ten digts followed by a hyphen and another digit",
    "required": false,
    "validator": "org.openmrs.patient.impl.LuhnIdentifierValidator",
    "locationBehavior": "NOT_USED",
    "uniquenessBehavior": "UNIQUE"
}

Delete a patientIdentifierType

DELETE /patientidentifiertype/:target_patientidentifiertype_uuid?purge=true

Visits

Visits Overview

Let’s look at an example of Visits

At the Amani Clinic, a patient might typically check-in at registration, be seen by a doctor, and receives medication dispensed in the pharmacy. This would be recorded as one visit of visit type of Outpatient , and contain three encounters (Registration, Consultation, and Dispensing) .

Visits Sub Resource types

Visits Attribute

Available operations for Visits

  1. List visits
  2. Create a visit
  3. Update a visit
  4. Delete a visit
  5. List attribute sub resource
  6. Create attribute sub resource with properties
  7. Update attribute sub resource
  8. Delete attribute sub resource

List visits

GET /visit?
includeInactive=true
&fromStartDate=2016-10-08T04:09:23.000Z
&patient=target_patient_uuid
&location=target_location_uuid
GET /visit/:target_visit_uuid

Create visit

POST /visit
{
    "patient": "target_patient_uuid",
    "visitType": "target_visitType_uuid",
    "startDatetime": "2016-10-08T04:09:25.000Z",
    "location": "target_location_uuid",
    "indication": null,
    "encounters": [
    "target_encounter_uuid"
    ],
    "attributes": [
    {
        "attributeType": "target_attributeType_uuid",
        "value": "value_for_attribute"
    }
    ]
}

Update visit

POST /visit/:target_visit_uuid
-d  modified_visit_object

Delete visit

DELETE /visit/:target_visit_uuid?purge=true

List attribute sub resources

GET /visit/:target_visit_uuid/attribute 
GET /visit/:target_visit_uuid/attribute/:target_attribute_uuid

Create an attribute sub resource with properties

POST visit/:target_visit_uuid/attribute 
{
    "attributeType": "target_attribute_type_uuid",
    "value": "value_for_the_attriute"
}

Update attribute sub resource

POST visit/:target_visit_uuid/attribute/:target_attribute_uuid
{
    "attributeType": "target_attribute_type_uuid",
    "value": "modified_attriute_value"
} 

Delete attribute sub resource

DELETE /visit/:target_visit_uuid/attribute/:target_attribute_uuid

Visits Type

Visits Type Overview

Available operations for Visits Type

  1. List visits types
  2. Create a visit type
  3. Update a visit type
  4. Delete a visit type

List visits types

GET /visittype?q="Search Query"
GET /visittype/:target_visit_type_uuid

Create a visit type

POST /visittype
{
    "name": "Name for the visit type",
    "description": "Description for the visit type"
}

Update a visit type

POST /type/:target_visit_type_uuid
{
    "name": "Modified name for the visit type",
    "description": "Modified description for the visit type"
}

Delete a visit type

DELETE /visittype/:target_visit_type_uuid?purge=true

Visits Attribute Type

Visits Attribute Type Overview

Available operations for Visits Attribute Type

  1. List visits attribute types
  2. Create a visit attribute type
  3. Update a visit attribute type
  4. Delete a visit attribute type

List visits attribute types

GET /visitattributetype?q="Search Query"
GET /visitattributetype/:target_visit_attribute_type_uuid

Create a visit attribute type

POST /visitattributetype
{
  "name": "Patient condition",
  "description": "This attribute type will record the health conditon of the patient",
  "datatypeClassname": "org.openmrs.customdatatype.datatype.LongFreeTextDatatype",
  "minOccurs": 0,
  "maxOccurs": 1,
  "datatypeConfig": "default",
  "preferredHandlerClassname": "org.openmrs.web.attribute.handler.LongFreeTextTextareaHandler",
  "handlerConfig": "dafault"
}

Update a visit attribute type

POST /visitattributetype/:target_visit_attribute_type_uuid
{
  "name": "Patient condition modified",
  "description": "This attribute type will record the health conditon of the patient",
  "datatypeClassname": "org.openmrs.customdatatype.datatype.LongFreeTextDatatype",
  "minOccurs": 0,
  "maxOccurs": 2,
  "datatypeConfig": "default",
  "preferredHandlerClassname": "org.openmrs.web.attribute.handler.LongFreeTextTextareaHandler",
  "handlerConfig": "dafault"
}

Delete a visit attribute type

DELETE /visitattributetype/:target_visit_attribute_type_uuid?purge=true

Location

Location Overview

Location Sub Resource types

Location Attribute.

Available operations for Location

  1. List location
  2. Create a location
  3. Update a location
  4. Delete a location
  5. List location attribute sub resource
  6. Create location attribute sub resource with properties
  7. Update location attribute sub resource
  8. Delete location attribute sub resource

List location

GET /location?
q="amani"
GET /location/:target_location_uuid

Create a location

POST /location
{
    "name": "Salzburg Hospital",
    "description": "Salzburg hospital location",
    "address1": "Mullner House 48",
    "address2": "",
    "cityVillage": "salzburg",
    "stateProvince": "salzburg",
    "country": "Austria",
    "postalCode": "5020",
    "latitude": "",
    "longitude": "",
    "countyDistrict": "salzburg",
    "tags": [
    "target_location_tag_uuid"
    ],
    "parentLocation": "target_parent_location_uuid",
    "childLocations": [
    "target_child_location_uuid"
    ],
    "attributes": [
        {
            "attributeType": "target_attributeType_uuid",
            "value": "value_for_attribute"
        }
    ]
}

Update a location

POST /location/:target_location_uuid
{
    "name": "Salzburg Hospital",
    "description": "Modified location of Salzburg hospital location",
    "address1": "Mullner House 48",
    "address2": "",
    "cityVillage": "salzburg",
    "stateProvince": "salzburg",
    "country": "Austria",
    "postalCode": "5020",
    "latitude": "47.811195",
    "longitude": "13.03322",
    "countyDistrict": "salzburg",
    "tags": [
    "target_location_tag_uuid"
    ],
    "parentLocation": "target_parent_location_uuid",
    "childLocations": [
    "target_child_location_uuid"
    ],
    "attributes": [
        {
            "attributeType": "target_attributeType_uuid",
            "value": "value_for_attribute"
        }
    ]
}       

Delete a location

DELETE /location/:target_location_uuid?purge=true

List location attribute sub resources

GET /location/:target_location_uuid/attribute 
GET /location/:target_location_uuid/attribute/:target_attribute_uuid

Create a location attribute sub resource with properties

POST location/:target_location_uuid/attribute 
{
    "attributeType": "target_location_attribute_type_uuid",
    "value": "value_for_the_attriute"
}

Update a location attribute sub resource

POST location/:target_location_uuid/attribute/:target_location_attribute_uuid
{
    "attributeType": "target_attribute_type_uuid",
    "value": "modified_attriute_value"
} 

Delete a location attribute sub resource

DELETE /location/:target_location_uuid/attribute/:target_location_attribute_uuid

Location Tag Type

Location Tag Overview

Available operations for Location Tag

  1. List location tags
  2. Create a location tag
  3. Update a location tag
  4. Delete a location tag

List location tags

GET /locationtag?q="visit"
GET /locationtag/:target_location_tag_uuid

Create a location tag

POST /locationtag
{
  "name": "Visit Location",
  "description": "Visits are only allowed to happen at locations tagged with this location tag.",
  "retired": false
}

Update a location tag

POST /locationtag/:target_location_tag_uuid
{
  "name": "Visit Location",
  "description": "Visits are only allowed to happen at locations tagged with this location tag.",
  "retired": true,
  "retiredReason": "Not valid anymore"
}

Delete a location tag

DELETE /locationtag/:target_location_tag_uuid?purge=true

Location Attribute Type

Location Attribute Overview

Available operations for Location Attribute

  1. List location attribute types
  2. Create a location attribute type
  3. Update a location attribute type
  4. Delete a location attribute type

List location attribute types

GET /locationattributetype?q="humidity"
GET /locationattributetype/:target_location_attribute_type_uuid

Create a location attribute type

POST /locationattributetype
{
  "name": "humidity",
  "description": "This attribute type will record the humidity of the location",
  "datatypeClassname": "org.openmrs.customdatatype.datatype.LongFreeTextDatatype",
  "minOccurs": 0,
  "maxOccurs": 1,
  "datatypeConfig": "default",
  "preferredHandlerClassname": "org.openmrs.web.attribute.handler.LongFreeTextTextareaHandler",
  "handlerConfig": "dafault"
}

Update a location attribute type

POST /locationattributetype/:target_location_attribute_type_uuid
{
  "name": "humidity",
  "description": "This attribute type will record the humidity of the location"",
  "datatypeClassname": "org.openmrs.customdatatype.datatype.LongFreeTextDatatype",
  "minOccurs": 0,
  "maxOccurs": 2,
  "datatypeConfig": "default",
  "preferredHandlerClassname": "org.openmrs.web.attribute.handler.LongFreeTextTextareaHandler",
  "handlerConfig": "dafault"
}

Delete a location attribute type

DELETE /locationattributetype/:target_location_attribute_type_uuid?purge=true

Encounters

Encounter Overview

Let’s look at an example of Encounter

During a typical Amani Clinic Outpatient Visit, a patient checks in at registration, is seen by a doctor, and receives medicine dispensed in the pharmacy. This would be recorded as one visit containing three encounters, whose types are Registration, Consultation, and Dispensing.

Sub Resource types of Encounter

Encounter Provider

Available operations for Encounter

  1. List encounters
  2. Create an encounters
  3. Update an encounters
  4. Delete an encounters
  5. List encounter provider sub resource
  6. Create encounter provider sub resource with properties
  7. Update encounter provider sub resource
  8. Delete encounter provider sub resource

List encounters

GET /encounter?
patient=96be32d2-9367-4d1d-a285-79a5e5db12b8
&fromdate=2016-10-08
GET /encounter/:target_encounter_uuid

Create an encounter

POST /encounter
{
  "encounterDatetime": "2019-10-16 12:08:43",
  "patient": "070f0120-0283-4858-885d-a20d967729cf",
  "encounterType": "e22e39fd-7db2-45e7-80f1-60fa0d5a4378",
  "location": "aff27d58-a15c-49a6-9beb-d30dcfc0c66e",
  "encounterProviders": [
    {
      "provider": "bb1a7781-7896-40be-aaca-7d1b41d843a6",
      "encounterRole": "240b26f9-dd88-4172-823d-4a8bfeb7841f"
    }
  ]
}

Update an encounter

POST /encounter/:target_encounter_uuid
{
  "encounterDatetime": "2019-10-16 12:08:43",
  "patient": "070f0120-0283-4858-885d-a20d967729cf",
  "encounterType": "e22e39fd-7db2-45e7-80f1-60fa0d5a4378",
  "location": "aff27d58-a15c-49a6-9beb-d30dcfc0c66e",
  "encounterProviders": [
    {
      "provider": "bb1a7781-7896-40be-aaca-7d1b41d843a6",
      "encounterRole": "240b26f9-dd88-4172-823d-4a8bfeb7841f"
    }
  ]
}

Delete an encounter

  DELETE /encounter/:target_encounter_uuid?purge=true

List encounter provider sub resources

GET /encounter/:target_encounter_uuid/encounterprovider 
GET /encounter/:target_encounter_uuid/encounterprovider/:target_encounter_provider_uuid

Create an encounter provider sub resource with properties

POST encounter/:target_encounter_uuid/encounterprovider 
{
  "provider": "bb1a7781-7896-40be-aaca-7d1b41d843a6",
  "encounterRole": "240b26f9-dd88-4172-823d-4a8bfeb7841f"
}

Update encounter provider sub resource

POST encounter/:target_encounter_uuid/encounterprovider/:target_encounter_provider_uuid
{
  "provider": "bb1a7781-7896-40be-aaca-7d1b41d843a6",
  "encounterRole": "240b26f9-dd88-4172-823d-4a8bfeb7841f"
}

Delete encounter provider sub resource

DELETE /encounter/:target_encounter_uuid/encounterprovider/:target_encounter_provider_uuid

Encounter Type

Encounter Type Overview

Available operations for Encounter Type

  1. List encounter types
  2. Create an encounter type
  3. Update an encounter type
  4. Delete an encounter type

List encounter types

GET /encountertype?
    q=Admission
GET /encountertype/:target_encounter_type_uuid

Create an encounter type

POST /encountertype
{
    "name": "Discharge",
    "description": "Attach encounters related to hospital dischargers"
}

Update an encounter type

POST /encountertype/:target_encounter_type_uuid
{
    "name": "Discharge",
    "description": "Encounters related to hospital dischargers"
}

Delete an encounter type

DELETE /encountertype/:target_encounter_type_uuid?purge=true

Encounter Role

Encounter Role Overview

Available operation for Encounter Roles

  1. List encounter roles
  2. Create an encounter role
  3. Update an encounter role
  4. Delete an encounter role

List encounter roles

GET /encounterrole?
    q=Clinician
    ```

* ### Get encounter role by UUID.

    Retrieve an encounter role by its UUID. Returns a `404 Not Found` status if encounter role not exists. If user not logged 
    in to perform this action, a `401 Unauthorized` status returned.

```console
GET /encounter/:target_encounter_role_uuid

Create an encounter role

POST /encounterrole
{
    "name": "Clinician",
    "description": "A provider assisting the Lead Surgeon."
}

Update an encounter role

POST /encounterrole/:target_encounter_role_uuid
{
    "name": "Assisting Surgeon"",
    "description": "A surgeon who assisted the Lead Surgeon"
}

Delete an encounter role

DELETE /encounterrole/:target_encounter_role_uuid?purge=true

Concepts

Concepts Overview

Sub Resource types of Concepts

Concept Attribute.

Concept Name.

Concept Mapping.

Concept Description.

Available operations for Concepts

  1. List concepts
  2. Create a concept
  3. Update a concept
  4. Delete a concept
  5. List concept mapping
  6. Create concept mapping with properties
  7. Update concept mapping
  8. Delete concept mapping
  9. List concept name
  10. Create concept name with properties
  11. Update concept name
  12. Delete concept name
  13. List concept attribute
  14. Create concept attribute with properties
  15. Update concept attribute
  16. Delete concept attribute
  17. List concept description
  18. Create concept description with properties
  19. Update concept description
  20. [Delete concept description](#delete-concept-description

List concepts

GET /concept?
  term=38341003
  &source=SNOMED%20CT
GET /concept/:target_concept_uuid

Create a concept

POST /concept
{
  "names": [
    {
      "name": "What is the blood type for the patient?",
      "locale": "en",
      "localePreferred": true,
      "conceptNameType": "FULLY_SPECIFIED"
    }
  ],
  "datatype": "8d4a4c94-c2cc-11de-8d13-0010c6dffd0f",
  "version": "1.2.2",
  "conceptClass": "8d492774-c2cc-11de-8d13-0010c6dffd0f"
}

Update a concept

POST /concept/:target_concept_uuid
{
  "names": [
    {
      "name": "What is the blood type for the sick patient?",
      "locale": "en",
      "localePreferred": true,
      "conceptNameType": "FULLY_SPECIFIED"
    }
  ],
  "datatype": "8d4a4c94-c2cc-11de-8d13-0010c6dffd0f",
  "version": "1.2.2",
  "conceptClass": "8d492774-c2cc-11de-8d13-0010c6dffd0f"
}

Delete a concept

DELETE /concept/:target_concept_uuid?purge=true

List concept mapping

GET /concept/:target_concept_uuid/mapping 
GET /concept/:target_concept_uuid/mapping/:target_concept_mapping_uuid

Create a concept mapping with properties

POST concept/:target_concept_uuid/mapping
{
  "conceptReferenceTerm": "21fb14d7-5cd9-3621-ac30-c9e57320e233",
  "conceptMapType": "35543629-7d8c-11e1-909d-c80aa9edcf4e"
}

Update a concept mapping

POST concept/:target_concept_uuid/mapping
{
  "conceptReferenceTerm": "21fb14d7-5cd9-3621-ac30-c9e57320e233",
  "conceptMapType": "35543629-7d8c-11e1-909d-c80aa9edcf4e"
}

Delete a concept mapping

DELETE concept/:target_concept_uuid/mapping/:target_concept_mapping_uuid

List concept name

GET /concept/:target_concept_uuid/name 
GET /concept/:target_concept_uuid/name/:target_concept_name_uuid

Create a concept name with properties

POST concept/:target_concept_uuid/name
{
  "name": "Bronchospasm",
  "locale": "en",
  "localePreferred": true,
  "conceptNameType": "FULLY_SPECIFIED"
}

Update concept name

POST concept/:target_concept_uuid/name
{
  "name": "Bronchospasm",
  "locale": "en",
  "localePreferred": true,
  "conceptNameType": "FULLY_SPECIFIED"
}

Delete concept name

DELETE concept/:target_concept_uuid/name/:target_concept_name_uuid

List concept attribute

GET /concept/:target_concept_uuid/attribute 
GET /concept/:target_concept_uuid/attribute/:target_concept_attribute_uuid

Create a concept attribute with properties

POST concept/:target_concept_uuid/attribute
{
  "attributeType": "target_concept_attribute_type_uuid",
  "value": "value_for_the_attriute"
}

Update concept attribute

POST concept/:target_concept_uuid/attribute
{
  "attributeType": "target_concept_attribute_type_uuid",
  "value": "value_for_the_attriute"
}

Delete concept attribute

DELETE concept/:target_concept_uuid/attribute/:target_concept_attribute_uuid

List concept descriptions

    GET /concept/:target_concept_uuid/description 
GET /concept/:target_concept_uuid/description/:target_concept_description_uuid

Create a concept description with properties

POST concept/:target_concept_uuid/description
{
  "description": "Pregnancy terminated by a spontaneous abortion.",
  "locale": "en"
}

Update concept description

POST concept/:target_concept_uuid/description
{
  "description": "Pregnancy terminated by a spontaneous abortion.",
  "locale": "en"
}

Delete concept description

DELETE concept/:target_concept_uuid/description/:target_concept_description_uuid

Concept Source

Concept Source Overview

Available operations for Concept Source.

  1. List concept_source types
  2. Create a concept_source
  3. Update a concept_source type
  4. Delete a concept_source type

List concept source

GET /conceptsource?q="loinc"
GET /conceptsource/:target_concept_source_type_uuid

Create a concept source

POST /conceptsource
{
  "name": "SNOMED CT",
  "description": "SNOMED Preferred mapping",
  "hl7Code": "SCT"
}

Update a concept source

POST /conceptsource
{
 "name": "SNOMED CTS",
 "description": "SNOMED Preferred mapping",
 "hl7Code": "SCT"
}

Delete a concept source

DELETE /conceptsource/:target_concept_source_type_uuid?purge=true

Concept Attribute Type

Concept Attribute Type Overview

Available operations for Concept Attribute Type.

  1. List concept_attribute types
  2. Create a concept_attribute_type
  3. Update a concept_attribute type
  4. Delete a concept_attribute type

List concept attribute types

GET /conceptattributetype?q=time
GET /conceptattributetype/:target_concept_attribute_type_uuid

Create a concept attribute type

POST /conceptattributetype
{
  "name": "Time Span",
  "description": "This attribute type will record the time span for the concept",
  "datatypeClassname": "org.openmrs.customdatatype.datatype.LongFreeTextDatatype",
  "minOccurs": 0,
  "maxOccurs": 1,
  "datatypeConfig": "default",
  "preferredHandlerClassname": "org.openmrs.web.attribute.handler.LongFreeTextTextareaHandler",
  "handlerConfig": "dafault"
}

Update a concept attribute type

POST /conceptattributetype
{
  "name": "Time Span",
  "description": "This attribute type will record the time span for the concept",
  "datatypeClassname": "org.openmrs.customdatatype.datatype.LongFreeTextDatatype",
  "minOccurs": 0,
  "maxOccurs": 1,
  "datatypeConfig": "default",
  "preferredHandlerClassname": "org.openmrs.web.attribute.handler.LongFreeTextTextareaHandler",
  "handlerConfig": "dafault"
}

Delete a concept attribute type

DELETE /conceptattributetype/:target_concept_attribute_type_uuid?purge=true

Concept Data Type

Concept Data Type Overview

1. Numeric – any data represented numerically, also allows you to classify critical values and units, e.g. age, height, and liters consumed per day 2. Coded – allows answers to be only those provided, e.g. blood type can only be “A”, “B”, "AB", or “O” 3. Text – Open ended responses 4. N/A – the standard datatype for any non-query-like concepts (answers or things), e.g. symptoms, diagnoses, findings, anatomy, misc 5. Document 6. Date – structured day, month, and year 7. Time – structured time response 8. DateTime – structured response including both the date and the time 9. Boolean – checkbox response, e.g. yes or no queries 10. Rule 11. Structured

Available operations for Concept Data Type.

  1. List concept_data types
  2. Delete a concept_data type

List concept data types

GET /conceptdatatype"
GET /conceptdatatype/:target_concept_data_type_uuid

Delete a concept data type

DELETE /conceptdatatype/:target_concept_data_type_uuid?purge=true

Providers

Provider Overview

Sub Resource types of Provider

Provider Attribute.

Available operations for Provider.

  1. List providers
  2. Create a provider
  3. Update a provider
  4. Delete a provider
  5. List provider attribute sub resource
  6. Create provider attribute sub resource with properties
  7. Update provider attribute sub resource
  8. Delete provider attribute sub resource

List providers

GET /provider?
q=clerk
GET /provider/:target_provider_uuid

Create a provider

POST /provider
{
  "person": "007037a0-0500-11e3-8ffd-0800200c9a66",
  "identifier": "doctor",
  "attributes": [
    {
      "attributeType": "target_attributeType_uuid",
      "value": "value_for_attribute"
    }
  ],
  "retired": false
}

Update a provider

POST /provider/:target_provider_uuid
{
  "person": "007037a0-0500-11e3-8ffd-0800200c9a66",
  "identifier": "doctor",
  "attributes": [
    {
      "attributeType": "target_attributeType_uuid",
      "value": "value_for_attribute"
    }
  ],
  "retired": false
}

Delete a provider

DELETE /provider/:target_provider_uuid?purge=true

List provider attribute sub resources

GET /provider/:target_provider_uuid/attribute 
GET /provider/:target_provider_uuid/attribute/:target_provider_attribute_uuid

Create a provider attribute sub resource with properties

POST provider/:target_provider_uuid/attribute 
{
  "attributeType": "target_provider_attribute_type_uuid",
  "value": "New provider"
}

Update provider attribute sub resource

POST provider/:target_provider_uuid/attribute/:target_provider_attribute_uuid
{
    "attributeType": "target_provider_attribute_type_uuid",
    "value": "New provider"
}

Delete provider attribute sub resource

DELETE /provider/:target_provider_uuid/attribute/:target_provider_attribute_uuid

Provider Attribute Type

Provider Attribute Overview

Available operations for Provider Attribute type.

  1. List provider attribute types
  2. Create a provider attribute type
  3. Update a provider attribute type
  4. Delete a provider attribute type

List provider attribute types

GET /providerattributetype?q="Search Query"
GET /providerattributetype/:target_provider_attribute_type_uuid

Create a provider attribute type

Attributes

Parameter Type Description
name String Name of the provider attribute type (Required)
description String Description (Required)
datatypeClassname CustomDataType Resource Data type for the attribute type resource. OpenMRS provides Custom data type resource which gives flexibility to select the data type accordingly (Required)
minOccurs Number Minimum number of times this value can be specified for a single provider. Use 0 or 1 as the default value (Required)
maxOccurs Number Maximum number of times this value can be specified for a single provider (e.g., use 1 to prevent an attribute from being added to a provider multiple times)
preferredHandlerClassname Handler Specifies the Java class to be used when handling this provider attribute type. The java class must implement [CustomDataTypeHandler(https://docs.openmrs.org/doc/org/openmrs/customdatatype/CustomDatatypeHandler.html). If not specified, the system will try to choose the best handler for the chosen datatype.
datatypeConfig String Provides ability to define custom data types configuration for openMRS
handlerConfig String Allow handler to be used for more than one attribute type. The actual configuration depends on the needs of the specified handler. For example, a "Pre-defined List" handler could be made to implement a simple selection list and this configuration would tell the handler the possible choices in the list for this specific attribute type
POST /providerattributetype
{
  "name": "Provider Location",
  "description": "This attribute type will record the loication of the provider",
  "datatypeClassname": "org.openmrs.customdatatype.datatype.LongFreeTextDatatype",
  "minOccurs": 0,
  "maxOccurs": 1,
  "datatypeConfig": "default",
  "preferredHandlerClassname": "org.openmrs.web.attribute.handler.LongFreeTextTextareaHandler",
  "handlerConfig": "dafault"
}

Update a provider attribute type

Attributes

Parameter Type Description
name String Name of the provider attribute type
description String Description (Required)
datatypeClassname CustomDataType Resource Data type for the attribute type resource. OpenMRS provides Custom data type resource which gives flexibility to select the data type accordingly (Required)
minOccurs Number Minimum number of times this value can be specified for a single provider. Use 0 or 1 as the default value (Required)
maxOccurs Number Maximum number of times this value can be specified for a single provider (e.g., use 1 to prevent an attribute from being added to a provider multiple times)
preferredHandlerClassname Handler Specifies the Java class to be used when handling this provider attribute type. The java class must implement [CustomDataTypeHandler(https://docs.openmrs.org/doc/org/openmrs/customdatatype/CustomDatatypeHandler.html). If not specified, the system will try to choose the best handler for the chosen datatype.
datatypeConfig String Provides ability to define custom data types configuration for openMRS
handlerConfig String Allow handler to be used for more than one attribute type. The actual configuration depends on the needs of the specified handler. For example, a "Pre-defined List" handler could be made to implement a simple selection list and this configuration would tell the handler the possible choices in the list for this specific attribute type
POST /providerattributetype/:target_provider_attribute_type_uuid
{
  "name": "Provider Location",
  "description": "This attribute type will record the loication of the provider",
  "datatypeClassname": "org.openmrs.customdatatype.datatype.LongFreeTextDatatype",
  "minOccurs": 0,
  "maxOccurs": 2,
  "datatypeConfig": "default",
  "preferredHandlerClassname": "org.openmrs.web.attribute.handler.LongFreeTextTextareaHandler",
  "handlerConfig": "dafault"
}

Delete a provider attribute type

DELETE /providerattributetype/:target_provider_attribute_type_uuid?purge=true

Observations

Observations Overview

An Observation is one single piece of information that is recorded about a person at a moment in time.

Every observation has a Concept as its question, and depending on the datatype of the concept, it has a value that is a number, date, text, Concept, etc.

Most of the information you store in OpenMRS is in the form of Observations, and most Observations happen in an Encounter. When you enter a form in OpenMRS, typically one Encounter is created with anywhere between tens or hundreds of Observations.

Note that an individual Observation is valid only at one moment in time, and it does not carry forward. You may query the system for the last observation for pregnancy status but this does not tell you whether or not the patient is pregnant at any point after the moment of that observation.

Examples of observations include Serum Creatinine of 0.9mg/dL or Review of cardiopulmonary system is normal.

Available operations for Observations.

  1. List observations
  2. Create an observation
  3. Update an observation
  4. Delete an observation

List observations

GET /obs?patient=070f0120-0283-4858-885d-a20d967729cf"
GET /obs/:target_observation_uuid

Create an observation

POST /obs 
{
  "person": "070f0120-0283-4858-885d-a20d967729cf",
  "concept": "5089AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
  "obsDatetime": "2019-11-14T07:37:31.000+0000",
  "value": 70
}

Update an observation

POST /obs/:uuid_of_obs_to_be_updated
{
  "value": 71
}

Delete an observation

DELETE /obs/:target_obs_uuid?purge=true

Order

Order Overview

An Order represents a request from a provider such as a lab test, procedure, referral, etc.

For example a provider could order a Complete Blood Count laboratory panel for a patient.

An Order only records an intention, not whether or not the action is carried out. The results of an Order are typically recorded later as Observations.

Available operations for Order type.

  1. List orders
  2. Create an order
  3. Update an order
  4. Delete an order

List orders

GET /order?q=penicillin
GET /order/:target_order_uuid

Create an order

POST /order
{
  "encounter": "69f83020-caf2-4c9e-bca7-89b8e62b52e1",
  "action": "new",
  "urgency": "ROUTINE",
  "patient": "070f0120-0283-4858-885d-a20d967729cf",
  "dateActivated": "2018-10-16 12:08:43"
}

Update an order

POST /order/:target_order_uuid
{
  "encounter": "69f83020-caf2-4c9e-bca7-89b8e62b52e1",
  "action": "new",
  "urgency": "ROUTINE",
  "patient": "070f0120-0283-4858-885d-a20d967729cf",
  "dateStopped": "2019-03-12 11:48:23"
}

Delete an order

DELETE /order/:target_order_uuid?purge=true

Order type

Order type Overview

Available operations for Order type.

  1. List orders
  2. Create an order
  3. Update an order
  4. Delete an order

List orders

GET /ordertype
GET /ordertype/:target_ordertype_uuid

Create an order type

POST /ordertype
{
  "name": "drug order",
  "description": "One 500mg tablet of Ciprofloxacin, twice a day",
  "parent": "070f0120-0283-4858-885d-a20d967729cf",
}

Update an order type

POST /ordertype/:target_ordertype_uuid
{
  "name": "drug order",
  "description": "One 400mg tablet of Ciprofloxacin, twice a day"
}

Delete an order type

DELETE /ordertype/:target_ordertype_uuid

Contributing

Help us keep this documentation up to date by forking this repository and submitting pull requests with improvements or corrections. The quality of our documentation depends on the collective contributions of persons just like you. Thank you for your contributions!

Our documentation is written in simple markdown. The markdown pages can be found in the repository under in the subfolder source/includes/. We use Slate to convert our markdown into a friendly and searchable format. More details on contributing may be found in the README of our repository.