NAV Navbar
shell java

OpenMRS REST API

Getting started with examples.

  1. Before executing the examples, get the okttp dependency jar and import it the project.
  2. These code stubs will be elided from all the examples for clarity
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;
import java.io.IOException;

public class Main {
    public static void main(String[] args) {
        try {
            // the examples go here

        } catch (IOException exception) {

            //handle exception here
        }
    }
}

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

Fetching concepts

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
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
Request request = new Request.Builder()
  .url("https://demo.openmrs.org/openmrs/ws/rest/v1/concept")
  .method("GET", null)
  .addHeader("Authorization", "Basic YWRtaW46QWRtaW4xMjM=")
  .addHeader("Cookie", "JSESSIONID=6D8DA35A3C57ECF332AFACC843609A23")
  .build();
Response response = client.newCall(request).execute();

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.

Resources

Subresources

Examples

Adding a person name.

Adding a person's name

POST /openmrs/ws/rest/v1/person/:target_person_uuid/name
{
  "givenName": "John",
  "familyName": "Smith"
}
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\r\n  \"givenName\": \"John\",\r\n  \"familyName\": \"Smith\"\r\n}");
Request request = new Request.Builder()
  .url("https://demo.openmrs.org/openmrs/ws/rest/v1/person/070f0120-0283-4858-885d-a20d967729cf/name
")
  .method("POST", body)
  .addHeader("Authorization", "Basic YWRtaW46QWRtaW4xMjM=")
  .addHeader("Content-Type", "application/json")
  .addHeader("Cookie", "JSESSIONID=6D8DA35A3C57ECF332AFACC843609A23")
  .build();
Response response = client.newCall(request).execute();

Editing a person's name.

Editing a person's name

POST /openmrs/ws/rest/v1/person/:target_person_uuid/name/:target_name_uuid
{
  "givenName": "Johnny"
}
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\r\n  \"givenName\": \"Johnny\"\r\n}");
Request request = new Request.Builder()
  .url("https://demo.openmrs.org/openmrs/ws/rest/v1/person/070f0120-0283-4858-885d-a20d967729cf/name/c280a829-7a86-47a5-b876-df8f53e89dac
")
  .method("POST", body)
  .addHeader("Authorization", "Basic YWRtaW46QWRtaW4xMjM=")
  .addHeader("Content-Type", "application/json")
  .addHeader("Cookie", "JSESSIONID=6D8DA35A3C57ECF332AFACC843609A23")
  .build();
Response response = client.newCall(request).execute();

Instead, these should be queries on the encounter resource:

Get an encounter list for a specific patient.

Get an encounter list for a specific patient

 GET /encounter?patient=:target_patient_uuid
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
Request request = new Request.Builder()
  .url("https://demo.openmrs.org/openmrs/ws/rest/v1/encounter?patient=7379bf1c-b64f-4958-b27f-2a769d8d291c")
  .method("GET", null)
  .addHeader("Authorization", "Basic YWRtaW46QWRtaW4xMjM=")
  .addHeader("Cookie", "JSESSIONID=6D8DA35A3C57ECF332AFACC843609A23")
  .build();
Response response = client.newCall(request).execute();

Get an encounter list for a specific location.

Get an encounter list for a specific location

 GET /encounter?location=:target_location_uuid
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
Request request = new Request.Builder()
  .url("https://demo.openmrs.org/openmrs/ws/rest/v1/encounter?location=aff27d58-a15c-49a6-9beb-d30dcfc0c66e")
  .method("GET", null)
  .addHeader("Authorization", "Basic YWRtaW46QWRtaW4xMjM=")
  .addHeader("Cookie", "JSESSIONID=6D8DA35A3C57ECF332AFACC843609A23")
  .build();
Response response = client.newCall(request).execute();

Resources with subtypes

Examples

POST examples on order resource

POST /openmrs/ws/rest/v1/order
{
  "type":"testorder",
  "encounter": "69f83020-caf2-4c9e-bca7-89b8e62b52e1",
  "action": "new",
  "urgency": "ROUTINE",
  "dateActivated": "2018-10-16 12:08:43"
}
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\r\n  \"type\":\"testorder\",\r\n  \"encounter\": \"69f83020-caf2-4c9e-bca7-89b8e62b52e1\",\r\n  \"action\": \"new\",\r\n  \"urgency\": \"ROUTINE\",\r\n  \"dateActivated\": \"2018-10-16 12:08:43\"\r\n}");
Request request = new Request.Builder()
  .url("https://demo.openmrs.org/openmrs/ws/rest/v1/order")
  .method("POST", body)
  .addHeader("Authorization", "Basic YWRtaW46QWRtaW4xMjM=")
  .addHeader("Content-Type", "application/json")
  .addHeader("Cookie", "JSESSIONID=6D8DA35A3C57ECF332AFACC843609A23")
  .build();
Response response = client.newCall(request).execute();

Get encounter orders of drug order subtype.

Get encounter orders of drug order subtype

GET  /openmrs/ws/rest/v1/order?type=drugorder&v=full'
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
Request request = new Request.Builder()
  .url("https://demo.openmrs.org/openmrs/ws/rest/v1/order?type=drugorder")
  .method("GET", null)
  .addHeader("Authorization", "Basic YWRtaW46QWRtaW4xMjM=")
  .addHeader("Cookie", "JSESSIONID=6D8DA35A3C57ECF332AFACC843609A23")
  .build();
Response response = client.newCall(request).execute();

Authentication

Retrieve session token

Retrieve session token

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",
    }
}
    OkHttpClient client = new OkHttpClient().newBuilder()
            .build();
    Request request = new Request.Builder()
            .url("https://demo.openmrs.org/openmrs/ws/rest/v1/session")
            .method("GET", null)
            .addHeader("Authorization", "Basic YWRtaW46QWRtaW4xMjM=")
            .build();
    Response response = client.newCall(request).execute();

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

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

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

Logout User/End session

Logout User/End session

DELETE /openmrs/ws/rest/v1/session -H 'Accept: application/json'
-H 'Authorization: Basic Auth' (required to identify the user)
    OkHttpClient client = new OkHttpClient().newBuilder().build();
    Request request = new Request.Builder()
        .url("https://demo.openmrs.org/openmrs/ws/rest/v1/session")
        .method("DELETE", null)
        .addHeader("Authorization", "Basic YWRtaW46QWRtaW4xMjM=")
        .build();
    Response response = client.newCall(request).execute();      

Changing Password

Password change By Admin


    OkHttpClient client = new OkHttpClient().newBuilder()
            .build();
    MediaType mediaType = MediaType.parse("application/json");

    //password should contain atleast 1 integer
    RequestBody body = RequestBody.create(mediaType, "{ \r\n    \"newPassword\" : \"password1\"\r\n}");
    Request request = new Request.Builder()
            .url("https://demo.openmrs.org/openmrs/ws/rest/v1/password/45ce6c2e-dd5a-11e6-9d9c-0242ac150002")
            .method("POST", body)
            .addHeader("Authorization", "Basic YWRtaW46QWRtaW4xMjM=")
            .addHeader("Content-Type", "application/json")
            .build();
    Response response = client.newCall(request).execute();
}

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

Since version 2.17 of the webservices.rest module:

Password change By Users

POST /openmrs/ws/rest/v1/password 
{
  "oldPassword" : "oldPassword",
  "newPassword" : "newPassword"
}
    OkHttpClient client = new OkHttpClient().newBuilder().build();
    MediaType mediaType = MediaType.parse("application/json");

    RequestBody body = RequestBody.create(mediaType, "{\r\n  \"oldPassword\" : \"Admin123\",\r\n  \"newPassword\" : \"newPassword1\"\r\n}");
    Request request = new Request.Builder()
      .url("https://demo.openmrs.org/openmrs/ws/rest/v1/password")
      .method("POST", body)
      .addHeader("Authorization", "Basic YWRtaW46QWRtaW4xMjM=")
      .addHeader("Content-Type", "application/json")
      .build();
    Response response = client.newCall(request).execute();

Getting all location without authentication

Getting all location without authentication

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

    OkHttpClient client = new OkHttpClient().newBuilder()
            .build();
    Request request = new Request.Builder()
            .url("https://demo.openmrs.org/openmrs/ws/rest/v1/location?tag=Login+Location")
            .method("GET", null)
            .addHeader("Authorization", "Basic YWRtaW46QWRtaW4xMjM=")
            .build();
    Response response = client.newCall(request).execute();

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.

System Setting

System Setting Overview

Available operations for systemsetting type.

  1. List System Settings
  2. Create a System Setting
  3. Update a System Setting
  4. Delete a System Setting

List System Settings

List system settings

GET /systemsetting?limit=5

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
Request request = new Request.Builder()
  .url("https://demo.openmrs.org/openmrs/ws/rest/v1/systemsetting?limit=5")
  .method("GET", null)
  .addHeader("Authorization", "Basic YWRtaW46QWRtaW4xMjM=")
  .addHeader("Cookie", "JSESSIONID=34D261A0DB322FE60502E3FF4DEC6FCC")
  .build();
Response response = client.newCall(request).execute();

Query Parameters

Parameter Type Description
limit integer use this parameter to limit the number of results to be returned
startIndex integer the offset where to start the query
v String the required representation to return (i.e., ref, default, full or custom )
q String the search query

Get a particular System Setting

Get a particular system setting

GET /systemsetting/:target_systemsetting_uuid

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
Request request = new Request.Builder()
  .url("https://demo.openmrs.org/openmrs/ws/rest/v1/systemsetting/e368193e-b0aa-4e90-9a1b-15623e291d11")
  .method("GET", null)
  .addHeader("Authorization", "Basic YWRtaW46QWRtaW4xMjM=")
  .addHeader("Cookie", "JSESSIONID=34D261A0DB322FE60502E3FF4DEC6FCC")
  .build();
Response response = client.newCall(request).execute();

Retrieve a particular System Setting. If not authenticated or authenticated user does not have sufficient privileges, a 401 Unauthorized status is returned.

Create a System Setting

Create a system setting

POST /systemsetting
{
  "property": "property name",
  "description": "dummy description",
  "datatypeClassname": "org.openmrs.customdatatype.datatype.LongFreeTextDatatype",
  "datatypeConfig": "default",
  "preferredHandlerClassname":"org.openmrs.web.attribute.handler.LongFreeTextTextareaHandler",
  "handlerConfig": "default",
  "value": "dummy value"
}

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\r\n  \"property\": \"propert name\",\r\n  \"description\": \"dummy description\",\r\n  \"datatypeConfig\": \"default\",\r\n  \"preferredHandlerClassname\":\"org.openmrs.web.attribute.handler.LongFreeTextTextareaHandler\",\r\n  \"handlerConfig\": \"default\",\r\n  \"value\": \"dummy value\"\r\n}");
Request request = new Request.Builder()
  .url("https://demo.openmrs.org/openmrs/ws/rest/v1/systemsetting")
  .method("POST", body)
  .addHeader("Authorization", "Basic YWRtaW46QWRtaW4xMjM=")
  .addHeader("Content-Type", "application/json")
  .addHeader("Cookie", "JSESSIONID=34D261A0DB322FE60502E3FF4DEC6FCC")
  .build();
Response response = client.newCall(request).execute();

Update a System Setting

Updating system setting

POST /systemsetting/:target_systemsetting_uuid
{
  "property": "property name",
  "description": "dummy description",
  "datatypeClassname": "org.openmrs.customdatatype.datatype.LongFreeTextDatatype",
  "datatypeConfig": "default",
  "preferredHandlerClassname":"org.openmrs.web.attribute.handler.LongFreeTextTextareaHandler"
  "handlerConfig": "default",
  "value": "dummy value"
}

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\r\n  \"property\": \"propert name\",\r\n  \"description\": \"dummy description changed\",\r\n  \"datatypeConfig\": \"default\",\r\n  \"preferredHandlerClassname\":\"org.openmrs.web.attribute.handler.LongFreeTextTextareaHandler\",\r\n  \"handlerConfig\": \"default\",\r\n  \"value\": \"dummy value changed\"\r\n}");
Request request = new Request.Builder()
  .url("https://demo.openmrs.org/openmrs/ws/rest/v1/systemsetting/14b15bdc-5bd8-42c0-852b-3cd002498613")
  .method("POST", body)
  .addHeader("Authorization", "Basic YWRtaW46QWRtaW4xMjM=")
  .addHeader("Content-Type", "application/json")
  .addHeader("Cookie", "JSESSIONID=34D261A0DB322FE60502E3FF4DEC6FCC")
  .build();
Response response = client.newCall(request).execute();

Attributes

Parameter Type Description
property String the property name for this System Setting, names can be up to 255 chars, must be unique, and follow a convention of module ID followed by category & name lower camelCase separated by periods for e.g., addresshierarchy.allowFreetext.
description String a description for the usage of this property.
datatypeClassname String Data type for this System Setting.OpenMRS provides Custom data type resource, which gives flexibility to select the data type accordingly.
datatypeConfig String An optional identifier from the fulfiller e.g., lab
preferredHandlerClassname String Handler subresource for the Custom Data Type used. Can optionally define a specific handler class wants to use (otherwise, the framework will choose the best handler for the chosen DataType).
handlerConfig String Allow the handler have any name and config it wants/needs. This will help to identify the data type unambiguously which has been contained and will allow introspecting.
value String the value assigned to this system setting.

Delete a System Setting

Delete a system setting

DELETE /systemsetting/:target_systemsetting_uuid?purge=true

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
  .url("https://demo.openmrs.org/openmrs/ws/rest/v1/systemsetting/1029a09d-a796-41dc-ba5f-65a559d63f3d")
  .method("DELETE", body)
  .addHeader("Authorization", "Basic YWRtaW46QWRtaW4xMjM=")
  .addHeader("Cookie", "JSESSIONID=34D261A0DB322FE60502E3FF4DEC6FCC")
  .build();
Response response = client.newCall(request).execute();

System Information

System Information Overview

Header Brief Description
1. OpenMRS Information This section holds information like OpenMRS Version Snapshot and other system wide informations like System Date and Time.
2. Java Runtime Environment Information This section has the relevant Java parameters along with the the operating system and its architecture information.For e.g. Operating System : Linux
3. Memory Information This section holds the total , free and the maximum heap Size memory information of the system.
4. Database Information This section has the relevant information about the database. For e.g. Database Schema name : openmrs-db
5. Module Information This section has the record of all the snapshot versions for each of the current modules. For e.g. Allergy UI Module : 1.8.3-SNAPSHOT

Available operations for systeminformation type.

List System Inforamation

List system information


GET /systeminformation?limit=5&startIndex=0&v=default


OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
Request request = new Request.Builder()
  .url("https://qa-refapp.openmrs.org/openmrs/ws/rest/v1/systeminformation?limit=5&startIndex=0&v=default
")
  .method("GET", null)
  .addHeader("Authorization", "Basic YWRtaW46QWRtaW4xMjM=")
  .addHeader("Cookie", "JSESSIONID=DECF639CF6A8545F34637E1F339972D8")
  .build();
Response response = client.newCall(request).execute();

Query Parameters

Parameter Type Description
limit integer use this parameter to limit the number of results to be returned
startIndex integer the offset where to start the query
v String the required representation to return (i.e., ref, default, full or custom )

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.

Get all non-retired Users

GET /user?
q=admin

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
Request request = new Request.Builder()
  .url("https://demo.openmrs.org/openmrs/ws/rest/v1/user?q=admin")
  .method("GET", null)
  .addHeader("Authorization", "Basic YWRtaW46QWRtaW4xMjM=")
  .addHeader("Cookie", "JSESSIONID=154692F02BBBC664825F3C4C224A474B")
  .build();
Response response = client.newCall(request).execute();

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 by UUID.

Get User by UUID

GET /user/:target_user_uuid

1. Here the target UUID used is of the admin user.  

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
Request request = new Request.Builder()
  .url("https://demo.openmrs.org/openmrs/ws/rest/v1/user/45ce6c2e-dd5a-11e6-9d9c-0242ac150002")
  .method("GET", null)
  .addHeader("Authorization", "Basic YWRtaW46QWRtaW4xMjM=")
  .addHeader("Cookie", "JSESSIONID=154692F02BBBC664825F3C4C224A474B")
  .build();
Response response = client.newCall(request).execute();

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.

Create a user

Create a new User

POST /user
{
   "username":"demoUser",
   "password":"Password123",
   "person":{
      "names":[
         {
            "givenName":"Demo",
            "familyName":"User"
         }
      ],
      "gender":"M",
      "birthdate":"1997-09-02",
      "addresses":[
         {
            "address1":"30, Vivekananda Layout, Munnekolal,Marathahalli",
            "cityVillage":"Bengaluru",
            "country":"India",
            "postalCode":"560037"
         }
      ]
   },
   "systemId":"systemId"
}


OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\r\n    \"username\": \"demoUser\",\r\n    \"password\": \"Password123\",\r\n    \"person\" :\r\n        {\r\n        \"names\": [\r\n            {\r\n                \"givenName\": \"Demo\",\r\n                \"familyName\": \"User\"\r\n            }\r\n        ],\r\n        \"gender\": \"M\",\r\n        \"birthdate\": \"1997-09-02\",\r\n        \"addresses\": [\r\n        {\r\n         \"address1\": \"30, Vivekananda Layout, Munnekolal,Marathahalli\",\r\n        \"cityVillage\": \"Bengaluru\",\r\n        \"country\": \"India\",\r\n        \"postalCode\": \"560037\"\r\n        }\r\n    ]\r\n        },\r\n\"systemId\": \"systemId\"\r\n}");
Request request = new Request.Builder()
  .url("https://demo.openmrs.org/openmrs/ws/rest/v1/user")
  .method("POST", body)
  .addHeader("Authorization", "Basic YWRtaW46QWRtaW4xMjM=")
  .addHeader("Content-Type", "application/json")
  .addHeader("Cookie", "JSESSIONID=154692F02BBBC664825F3C4C224A474B")
  .build();
Response response = client.newCall(request).execute();

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

Update a user

Update a user using its UUID

POST /user/:target_user_uuid
{
   "username":"demoUser",
   "password":"Password123",
   "person":{
      "names":[
         {
            "givenName":"Demo",
            "familyName":"User"
         }
      ],
      "gender":"M",
      "birthdate":"1997-09-02",
      "addresses":[
         {
            "address1":"30, Vivekananda Layout, Munnekolal,Marathahalli",
            "cityVillage":"Bengaluru",
            "country":"India",
            "postalCode":"560037"
         }
      ]
   },
   "systemId":"systemId"
}


OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\r\n    \"username\": \"demoUser\",\r\n    \"password\": \"Password123\",\r\n    \"person\" :\r\n        {\r\n        \"names\": [\r\n            {\r\n                \"givenName\": \"Demo\",\r\n                \"familyName\": \"User\"\r\n            }\r\n        ],\r\n        \"gender\": \"M\",\r\n        \"birthdate\": \"1997-09-02\",\r\n        \"addresses\": [\r\n        {\r\n         \"address1\": \"30, Vivekananda Layout, Munnekolal,Marathahalli\",\r\n        \"cityVillage\": \"Bengaluru\",\r\n        \"country\": \"India\",\r\n        \"postalCode\": \"560037\"\r\n        }\r\n    ]\r\n        },\r\n\"systemId\": \"systemId\"\r\n}");
Request request = new Request.Builder()
  .url("https://demo.openmrs.org/openmrs/ws/rest/v1/user/564b2790-0508-11e3-8ffd-0800200c9a66
")
  .method("POST", body)
  .addHeader("Authorization", "Basic YWRtaW46QWRtaW4xMjM=")
  .addHeader("Content-Type", "application/json")
  .addHeader("Cookie", "JSESSIONID=154692F02BBBC664825F3C4C224A474B")
  .build();
Response response = client.newCall(request).execute();

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

Delete a user

Delete a user using its UUID

DELETE /user/:target_user_uuid?purge=true

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
  .url("https://demo.openmrs.org/openmrs/ws/rest/v1/user/b953d87d-7e67-47b9-ad1e-fa8b7cdaea4d?purge=true")
  .method("DELETE", body)
  .addHeader("Authorization", "Basic YWRtaW46QWRtaW4xMjM=")
  .addHeader("Cookie", "JSESSIONID=154692F02BBBC664825F3C4C224A474B")
  .build();
Response response = client.newCall(request).execute();

Query Parameters

Parameter Type Description
purge Boolean The resource will be voided unless 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

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

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 name
  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

Search Persons

GET /person?q=john

Fetch all non-voided persons that match the search query parameter. Returns a 200 OK status with the Person response.

Parameters

Parameter Type Description
q string search by name

List person by UUID

GET /person/:target_person_uuid

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

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 subresource

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 subresource

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

Delete 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 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

List all non-retired person attribute types.

GET /personattributetype?q=race

Quickly filter person attribute types with a given search query. If the request is not authenticated or the authenticated user does not have appropriate permissions, a 401 Unauthorized status is returned.

### Query Parameters

Parameter Type Description
q Search Query Query to filter person attributes by its name(partial search is not supported)

Get person attribute type by UUID.

GET /personattributetype/:target_person_attribute_type_uuid

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

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

Search patients

GET /patient?
country=india
&gender=M

Fetch all non-retired patients that match any specified parameters otherwise fetch all non-retired patients. Returns a 200 OK status with the patient response.

Query Parameters

Parameter Description
matchSimilar use this parameter to enter anything to match
country Country where the patient is registered
birthDate must be used with matchSimilar
Gender Gender of the patient
city City where the patient is registered
address Address of the patients
familyName must be used with matchSimilar
middleName must be used with matchSimilar
postalCode must be used with matchSimilar
givenname must be used with matchSimilar
state must be used with matchSimilar

List patient by UUID.

GET /patient/:target_patient_uuid

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

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

Retrieve all identifier sub resources of a patient resource by target_patient_uuid.Returns a 404 Not Found status if patientIdentifier not exists. If user not logged in to perform this action, a 401 unauthorized status returned.

GET /patient/:target_patient_uuid/identifier/:target_identifier_uuid

Retrieve a patientIdentifier sub resources of a patient resource. Returns a 404 Not Found status if patientIdentifier not exists. If you are not logged in to perform this action, a 401 Unauthorized status returned.

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

List patientIdentifierType

GET /patientidentifiertype

Fetch all non-retired patientIdentifierTypes resources that match any specified parameters otherwise fetch all non-retired patients. Returns a 200 OK status with the patientIdentifierType response. If the user is not logged in a 401 Unauthorized status is returned.

Get patientIdentifierType by UUID.

GET /patientidentifiertype/:target_patientIdentifierType_uuid

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

Create a patientIdentifierType

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"
}

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.

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 visit
  3. Update visit
  4. Delete visit
  5. List attribute subresource
  6. Create attribute subresource with properties
  7. Update attribute subresource
  8. Delete attribute subresource

List visits

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

Query Parameters

Parameter Type Description
patient Patient UUID Get visits for this patient
location Location UUID Get visits for this location
includeInactive Boolean Active/Inactive status of visit
fromStartDate Date (ISO8601 Long) Start date of the visit
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 subresources

GET /visit/:target_visit_uuid/attribute 

Create an attribute subresource with properties

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

Update attribute subresource

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

Delete attribute subresource

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
GET /visittype?q="Search Query"

Query Parameters

Parameter Type Description
q Search Query Display Name of Visit Type.
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"

Query Parameters

Parameter Type Description
q Search Query Display Name of Visit attribute type.
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 subresource
  6. Create location attribute subresource with properties
  7. Update location attribute subresource
  8. Delete location attribute subresource

List location

GET /location?
q="amani"

List all non-retired locations`.

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

Query Parameters

Parameter Type Description
q Search Query Display Name of Location object.

List location by UUID.

GET /location/:target_location_uuid

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

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 subresources

List all location attribute subresources for a location.

GET /location/:target_location_uuid/attribute 

Retrieve all attribute sub resources of a location resource by target_location_uuid.Returns a 404 Not Found status if the attribute not exists. If the user not logged in to perform this action, a 401 Unauthorized status returned.

List location attribute subresources by own UUID and parent location UUID.

GET /location/:target_location_uuid/attribute/:target_attribute_uuid

Retrieve an attribute sub resources of a location resource.Returns a 404 Not Found status if the attribute not exists. If the user are not logged in to perform this action, a 401 Unauthorized status returned.

Create a location attribute subresource with properties

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

Update a location attribute subresource

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

Delete a location attribute subresource

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

List all non-retired location tags.

GET /locationtag?q="visit"

Quickly filter location tags with a given search query. Returns a 404 Not Found status if the location tag not exists. If the user not logged in to perform this action, a 401 Unauthorized status returned.

### Query Parameters

Parameter Type Description
q Search Query Display Name of Location location tag type.

List location tag by UUID.

GET /locationtag/:target_location_tag_uuid

Retrieve a location tag by its UUID. Returns a 404 Not Found status if the location tag type not exists. If the user not logged in to perform this action, a 401 Unauthorized status returned.

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

List all non-retired location attribute types.

GET /locationattributetype?q="humidity"

Quickly filter location attribute types with a given search query. Returns a 404 Not Found status if the location attribute type not exists. If the user not logged in to perform this action, a 401 Unauthorized status returned.

### Query Parameters

Parameter Type Description
q Search Query Display Name of Location attribute type.

List location attribute type by UUID.

GET /locationattributetype/:target_location_attribute_type_uuid

Retrieve a location attribute type by its UUID. Returns a 404 Not Found status if the location attribute type not exists. If the user not logged in to perform this action, a 401 Unauthorized status returned.

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

List all non-voided encounters.

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

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

Query Parameters

Parameter Type Description
q Search Query Get encounter by Encounter UUID, Patient Identifier or name
patient Patient UUID Get encounter(s) for a patient
encounterType Encounter_Type UUID Filter by encounter type (must be used with patient)
order Order UUID Filter to encounter(s) containing the specified order (must be used with patient)
obsConcept Concept UUID Filter to encounter(s) containing observation(s) for the given concept (must be used with patient)
obsValues String Filter to encounter(s) containing an observations with the given value (must be used with patient & obsConcept)
fromdate Date or Timestamp (ISO 8601) Start date of the encounter (must be used with patient)
todate Date or Timestamp (ISO 8601) End date of the encounter (must be used with patient)

List encounter by UUID.

GET /encounter/:target_encounter_uuid

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

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"
    }
  ]
}

Attributes

Parameter Type Description
encounterDatetime Date (ISO8601 Long) The date and time the encounter was created (required)
patient Patient UUID The patient to whom the encounter applies
encounterType EncounterType UUID The type of encounter – e.g., Initial visit, Return visit, etc. (required)
location Location UUID The location at which the encounter occurred (required)
encounterProviders Array of Provider UUID and associated Encounter Role UUID An array of providers and their role within the encounter. At least one provider is required
obs Array[]: Obs Array of observations and values for the encounter
orders Array[]: Order UUID List of orders created during the encounter
form Form UUID Target Form UUID to be filled for the encounter
visit Visit UUID When creating an encounter for an existing visit, this specifies the visit

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"
    }
  ]
}

Attributes

Parameter Type Description
encounterDatetime Date (ISO8601 Long) The date and time the encounter was created
patient Patient UUID The patient to whom the encounter applies
encounterType EncounterType UUID The type of encounter – e.g., Initial visit, Return visit, etc.
location Location UUID The location at which the encounter occurred
encounterProviders Array of Provider UUID and associated Encounter Role UUID An array of providers and their role within the encounter. At least one provider is required
obs Array[]: Obs Array of observations and values for the encounter
orders Array[]: Order UUID List of orders created during the encounter
form Form UUID Target Form UUID to be filled for the encounter
visit Visit UUID When creating an encounter for an existing visit, this specifies the visit

Delete an encounter

  DELETE /encounter/:target_encounter_uuid?purge=true

List encounter provider subresources

List all encounter provider subresources for a visit.

GET /encounter/:target_encounter_uuid/encounterprovider 

Retrieve all encounter provider sub resources of an encounter resource by target_encounter_uuid. Returns a 404 Not Found status if encounter provider not exists. If user not logged in to perform this action, a 401 Unauthorized status returned.

List encounter provider subresources by it's UUID and parent encounter UUID.

GET /encounter/:target_encounter_uuid/encounterprovider/:target_encounter_provider_uuid

Retrieve an encounter provider sub resources of a encounter resource. Returns a 404 Not Found status if encounter provider not exists. If you are not logged in to perform this action, a 401 Unauthorized status returned.

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 subresource

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 subresource

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

List all not-retired encounter types.

GET /encountertype?
    q=Admission

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

Query Parameters

Parameter Type Description
q Search Query Query to filter encounter type by its name

Get encounter type by UUID.

GET /encountertype/:target_encounter_type_uuid

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

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

List all non-voided encounter roles.

GET /encounterrole?
    q=Clinician

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

Query Parameters

Parameter Type Description
q Search Query Query to filter encounter role by its name

Get encounter role by UUID.

GET /encounter/:target_encounter_role_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.

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

List all concepts.

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

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

Query Parameters

Parameter Type Description
q Search Query Display Name of concept object
code String Represents a name from a standard medical code
name String ConceptNames are the words or phrases used to express the idea of a Concept within a particular locale
term String Medical coding term or OpenMRS concept dictionary term that could be mapped to a concept
source String A concept can have any number of mappings to any number of other vocabularies. Other vocabularies are called "concept sources" in OpenMRS (ie. LOINC, SNOMED, ICD-9, ICD10, RxNORM, etc), but the concept source can also be a custom (ie. org.openmrs.module.mdrtb, PIH, AMPATH, MVP, etc.). Every concept can define a string for its mapping in any "concept source" defined in the database
class String The concept's class provides a useful way to narrow down the scope of the information that the concept is intended to capture. In this way, the class is helpful for data extraction. This classification elaborates how a concept will be represented (i.e. as a question or an answer) when the information is stored. OpenMRS contains several default classes to use when defining concepts, but implementation sites may also create additional custom concept classes.

Query concept by UUID.

GET /concept/:target_concept_uuid

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

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

List all concept mappings for a concept.

GET /concept/:target_concept_uuid/mapping 

Retrieve all concept mapping subresources of a concept resource by target_concept_uuid. Returns a 404 Not Found status if concept mapping not exists. If the user is not logged in to perform this action, a 401 Unauthorized status returned.

List concept mapping by its UUID and parent concept UUID.

GET /concept/:target_concept_uuid/mapping/:target_concept_mapping_uuid

Retrieve a concept mapping subresources of a concept resource. Returns a 404 Not Found status if concept mapping not exists. If you are not logged in to perform this action, a 401 Unauthorized status returned.

Create a concept mapping with properties

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

Attributes

Parameter Type Description
conceptReferenceTerm target_concept_reference_term_type_uuid A concept term defines a medical coding term or OpenMRS concept dictionary term that could be mapped to a concept (required)
conceptMapType target_concept_map_type_uuid A concept map connects a concept term to a concept (required)

Update a concept mapping

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

Attributes

Parameter Type Description
conceptReferenceTerm target_concept_reference_term_type_uuid A concept term defines a medical coding term or OpenMRS concept dictionary term that could be mapped to a concept (required)
conceptMapType target_concept_map_type_uuid A concept map connects a concept term to a concept (required)

Delete a concept mapping

DELETE concept/:target_concept_uuid/mapping/:target_concept_mapping_uuid

Query Parameters

Parameter Type Description
purge Boolean The resource will be voided unless purge = ‘true’. Purging will attempt to remove the concept mapping type from the system irreversibly. Concept mapping types that have been used (i.e., are referenced from existing data) cannot be purged.

List concept name

List all concept names for a concept.

GET /concept/:target_concept_uuid/name 

Retrieve all concept name subresources of a concept resource by target_concept_uuid. Returns a 404 Not Found status if concept name not exists. If the user isnot logged in to perform this action, a 401 Unauthorized status returned.

List concept name it's UUID and parent concept UUID.

GET /concept/:target_concept_uuid/name/:target_concept_name_uuid

Retrieve a concept name subresources of a concept resource. Returns a 404 Not Found status if concept name not exists. If you are not logged in to perform this action, a 401 Unauthorized status returned.

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

List all concept attributes for a concept.

GET /concept/:target_concept_uuid/attribute 

Retrieve all concept attribute subresources of a concept resource by target_concept_uuid. Returns a 404 Not Found status if a concept attribute not exists. If the user isnot logged in to perform this action, a 401 Unauthorized status returned.

List concept attribute by its UUID and parent concept UUID.

GET /concept/:target_concept_uuid/attribute/:target_concept_attribute_uuid

Retrieve a concept attribute subresources of a concept resource. Returns a 404 Not Found status if a concept attribute not exists. If you are not logged in to perform this action, a 401 Unauthorized status returned.

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

List all concept descriptions for a concept.

    GET /concept/:target_concept_uuid/description 

Retrieve all concept description subresources of a concept resource by target_concept_uuid. Returns a 404 Not Found status if concept description not exists. If the user is not logged in to perform this action, a 401 Unauthorized status returned.

List concept description by its UUID and parent concept UUID.

GET /concept/:target_concept_uuid/description/:target_concept_description_uuid

Retrieve a concept description subresources of a concept resource. Returns a 404 Not Found status if concept description not exists. If you are not logged in to perform this action, a 401 Unauthorized status returned.

Create a concept description with properties

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

Update concept description

POST concept/:target_concept_uuid/description
{
  "description": "Pregnancy terminated by 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

List all non-retired concept source.

GET /conceptsource?q="loinc"

Quickly filter concept source types with a given search query. Returns a 404 Not Found status if concept source type not exists. If the user is not logged in to perform this action, a 401 Unauthorized status returned.

#### Query Parameters

Parameter Type Description
q String Full or partial match to concept source name. Search is case-insensitive

Query concept source by UUID.

GET /conceptsource/:target_concept_source_type_uuid

Retrieve a concept source type by its UUID. Returns a 404 Not Found status if concept source type not exists. If user not logged in to perform this action, a 401 Unauthorized status returned.

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

List all non-retired concept attribute types.

GET /conceptattributetype?q=time

Quickly filter concept attribute types with a given search query. Returns a 404 Not Found status if concept attribute type not exists. If the user is not logged in to perform this action, a 401 Unauthorized status returned.

#### Query Parameters

Parameter Type Description
q String Full or partial display name of concept source

List concept attribute type by UUID.

GET /conceptattributetype/:target_concept_attribute_type_uuid

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

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"
}

Attributes

Parameter Type Description
name String Name of the concept 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 concept. Use 0 or 1 as the default value (Required)
maxOccurs Number Maximum number of times this value can be specified for a single concept (e.g., use 1 to prevent an attribute from being added to a concept multiple times)
preferredHandlerClassname Handler Specifies the Java class to be used when handling this concept 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

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"
}

Attributes

Parameter Type Description
name String Name of the concept 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
minOccurs Number Minimum number of times this value can be specified for a single concept. Use 0 or 1 as the default value
maxOccurs Number Maximum number of times this value can be specified for a single concept (e.g., use 1 to prevent an attribute from being added to a concept multiple times)
preferredHandlerClassname Handler Specifies the Java class to be used when handling this concept 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

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

List all non-retired concept data types.

GET /conceptdatatype"

Get concept data types. Returns a 404 Not Found status if concept data type not exists. If the user is not logged in to perform this action, a 401 Unauthorized status returned.

Get concept data type by UUID.

GET /conceptdatatype/:target_concept_data_type_uuid

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

Delete a concept data type

DELETE /conceptdatatype/:target_concept_data_type_uuid?purge=true

Concept Map Type

Overview

Available operations.

  1. List concept mapping types
  2. Create a concept mapping type
  3. Update a concept mapping typee
  4. Delete a concept mapping type

List concept map types

List all non-retired concept map types.

  GET /conceptmaptype?q="same"

Quickly filter concept map types with a given search query. Returns a 404 Not Found status if concept map type not exists. If the user is not logged in to perform this action, a 401 Unauthorized status returned.

##### Query Parameters

Parameter Type Description
q String Full or partial name search term. Search is case insensitive.

List concept map type by UUID.

  GET /conceptmaptype/:target_concept_map_type_uuid

Retrieve a concept map type by its UUID. Returns a 404 Not Found status if concept map type not exists. If user not logged in to perform this action, a 401 Unauthorized status returned.

Create a concept map type

console POST /conceptmaptype { "name": "SAME-AS", "isHidden": false }

Attributes

Parameter Type Description
name String Name of the concept mapping type (Required)
description String A brief description of the concept mapping type
isHidden Boolean State to record concept map is hidden or not

Update a concept map type

        POST /conceptmaptype
        {
          "name": "SAME-AS",
          "isHidden": true
        }
    ```
*  Update a target concept map type with given UUID, this method only modifies properties in the request. Returns a `404 Not Found` 
status if concept map not exists. If the user is not logged in to perform this action, a `401 Unauthorized` status returned.

    #### Attributes

    Parameter | Type | Description
    --- | --- | ---
    *name* | `String` | Name of the concept mapping type (Required)
    *description* | `String` |  A brief description of the concept mapping type
    *isHidden* | `Boolean` | State to record concept map is hidden or not


### Delete a concept map type


    ```console
        DELETE /conceptmaptype/:target_concept_map_type_uuid?purge=true
    ```

* Delete or Retire a target concept map type by its UUID. Returns a `404 Not Found` status if concept map not exists. If user not logged in to perform this action, a `401 Unauthorized` status returned.

    #### Query Parameters

    Parameter | Type | Description
    --- | --- | ---
    *purge* | `Boolean` | The resource will be voided/retired unless purge = ‘true’

Concept Reference Term

Overview

Available operations.

  1. List concept reference terms
  2. Create a concept reference term
  3. Update a concept reference term
  4. Delete a concept reference term

List concept reference terms

List all concepts reference terms.

    GET /conceptreferenceterm?
      codeOrName=274663001

Quickly filter concept reference term with given query parameters. Returns a 404 Not Found status if concept reference term type not exists. If the user is not logged in to perform this action, a 401 Unauthorized status returned.

Query Parameters

Parameter Type Description
codeOrName String Represents a name from a standard medical code
source String A concept can have any number of mappings to any number of other vocabularies. Other vocabularies are called "concept sources" in OpenMRS (i.e., LOINC, SNOMED, ICD-9, ICD10, RxNORM, etc.), but the concept source can also be a custom (i.e., org.openmrs.module.mdrtb, PIH, AMPATH, MVP, etc.). Every concept can define a string for its mapping in any "concept source" defined in the database

Query concept reference term by UUID.

console GET /conceptreferenceterm/:target_concept_reference_term_type_uuid

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

Create a concept reference term

        POST /conceptreferenceterm
        {
          "code": "274663001",
          "conceptSource": "1ADDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD",
          "version": "1.0.0"
        }

Attributes

Parameter Type Description
names String Name for the concept reference term
description String A concept datatype prescribes the structured format by which you desire the data to be represented. In simple terms, the data type defines the type of data that the concept is intended to collect
code String Represents a name from a standard medical code (required)
conceptSource target_concept_source_UUID A concept can have any number of mappings to any number of other vocabularies. Other vocabularies are called "concept sources" in OpenMRS (i.e., LOINC, SNOMED, ICD-9, ICD10, RxNORM, etc.), but the concept source can also be a custom (i.e., org.openmrs.module.mdrtb, PIH, AMPATH, MVP, etc.). Every concept can define a string for its mapping in any "concept source" defined in the database (required)
version String A method to keep track of the number of updates applied to a specific concept reference term type

Update a concept reference term

        POST /conceptreferenceterm/:target_concept_reference_term_type_uuid
        {
          "code": "274663001",
          "conceptSource": "1ADDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD",
          "version": "1.0.1"
        }

Delete a concept reference term

        DELETE /conceptreferenceterm/:target_concept_reference_term_type_uuid?purge=true    ```

* Delete or retire a target concept reference term by its UUID. Returns a `404 Not Found` status if concept reference term not exists. If the user not logged in to perform this action, a `401 Unauthorized` status returned.

    #### Query Parameters

    Parameter | Type | Description
    --- | --- | ---
    *purge* | `Boolean` | The resource will be retired unless purge = ‘true’

Concept Class

Overview

Available operations.

  1. List concept classes
  2. Create a concept class
  3. Update a concept class
  4. Delete a concept class

List concept classes

List all non-retired concept classes.

console GET /conceptclass"

List all concept classes with a given search query. Returns a 404 Not Found status if concept classes not exist. If the user is not logged in to perform this action, a 401 Unauthorized status returned.

List concept class type by UUID.

console GET /conceptclass/:target_concept_class_uuid

Retrieve a concept class by its UUID. Returns a 404 Not Found status if concept class type not exists. If user not logged in to perform this action, a 401 Unauthorized status returned.

Create a concept class

        POST /conceptclass
        {
          "name": "Procedure",
          "description": "Describes a clinical procedure"
        }

Update a concept class

        POST /conceptclass
        {
          "name": "Procedure",
          "description": "Describes a clinical procedure"
        }

Delete a concept class

        DELETE /conceptclass/:target_concept_class_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 subresources

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 subresource

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

Delete provider attribute subresource

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

List all non-retired provider attribute types.

GET /providerattributetype?q="Search Query"

Quickly filter provider attribute types with a given search query. Returns a 404 Not Found status if the provider attribute type not exists. If the user is not authenticated or the authenticated user does not have appropriate permissions, a 401 Unauthorized status is returned.

Query Parameters

Parameter Type Description
q Search Query Display Name of provider attribute type.

List provider attribute type by UUID.

GET /providerattributetype/:target_provider_attribute_type_uuid

Retrieve a provider attribute type by its UUID. Returns a 404 Not Found status if the provider attribute type not exists. If the user is not authenticated or the authenticated user does not have appropriate permissions, a 401 Unauthorized status is returned.

Create a provider 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"
}

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

Update a provider 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"
}

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

Delete a provider attribute type

DELETE /providerattributetype/:target_provider_attribute_type_uuid?purge=true

Observations

Observations Overview

Observation is one piece of information recorded about a person at the 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 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 a Review of the 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

List all observations.

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

Quickly filter observations with given query parameters. If not authenticated or authenticated user does not have sufficient privileges, a 401 Unauthorized status is returned.

Query Parameters

Parameter Type Description
patient target_patient_uuid patient resource UUID
concept target_concept_uuid concept resource UUID (this parameter to be used with patient)

Query observations by UUID.

GET /obs/:target_observation_uuid

Retrieve an observation by its UUID. If not authenticated or authenticated user does not have sufficient privileges, a 401 Unauthorized status is returned.

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

Query Parameters

Parameter Type Description
q String Full or partial display name of order

Get a particular order

GET /order/:target_order_uuid

Retrieve a particular order. If not authenticated or authenticated user does not have sufficient privileges, a 401 Unauthorized status is returned.

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 a particular order type

GET /ordertype/:target_ordertype_uuid

Retrieve a particular order. If not authenticated or authenticated user does not have sufficient privileges, a 401 Unauthorized status is returned.

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

Forms

Forms Overview

Subresource types of Forms

formFields

Available operations for Forms

  1. List Forms
  2. Create a form
  3. Update a form
  4. Delete a form
  5. List formfields
  6. Create formFields subresource with properties
  7. Update formFields subresource with properties
  8. Delete formFields subresource with properties

List Forms

search-forms

GET /form?

Fetch all non-retired Forms that match any specified parameters otherwise fetch all non-retired forms. Returns a 200 OK status with the form response, and returns a 401 response when the user is not logged in.

Query Parameters

Parameter Description
limit use this parameter to limit the number of results to be returned
startIndex the offset where to start the query
v the required representation to return (i.e., ref, default, full or custom )
q the search query

List forms by UUID

GET /form/:target_form_uuid

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

Query Parameters

Parameter Description
v the required representation to return (i.e. ref, default, full or custom )
uuid the target form UUID

Create-a-form

POST /form
{
  "name": "Admission",
  "description": "dummy description",
  "version": "1.0",
  "encounterType": "Vitals",
  "published": true,
  "formFields": [
    "medication","allergies"
  ],
  "xslt": "xslt specification for this form",
  "template": "dummy template"
}

Update a form

POST /form/:target_form_uuid
{
  "name": "Admission",
  "description": "dummy description",
  "version": "1.0",
  "encounterType": "Vitals",
  "published": true,
  "formFields": [
    "medication","allergies"
  ],
  "xslt": "xslt specification for this form",
  "template": "dummy template"
}

Delete a form

DELETE /form/:target_form_uuid?purge=true

List formfields

List all formFields subresources for a form.

GET /form/:target_form_uuid/formFields

Retrieve all formFields subresources of a form resource by target_form_uuid. Returns a 404 Not Found status if formFields not exist. If the user is not logged in to perform this action, a 401 unauthorized status returned.

List formFields subresource by its UUID and parent form UUID.

GET /form/:target_form_uuid/formFields/:target_formFields_uuid

Retrieve a formFields subresources of a form resource. Returns a 404 Not Found status if formFields does not exist. If you are not logged in to perform this action, a 401 Unauthorized status returned.

create formfield subresource with properties

POST form/:target_form_uuid/formFields
{
  form: "UUID",
  field: "UUID",
  required: false,
  parent: "UUID",
  fieldNumber: 2,
  fieldPart: "4",
  pageNumber: 1,
  minOccurs: 0,
  maxOccurs: 1,
  sortWeight: false
}

Update formFields subresource with properties

POST form/:target_form_uuid/formFields/:target_formFields_uuid
{
  form: "UUID",
  field: "UUID",
  required: false,
  parent: "UUID",
  fieldNumber: 2,
  fieldPart: "4",
  pageNumber: 1,
  minOccurs: 0,
  maxOccurs: 1,
  sortWeight: false
}

Delete formFields subresource with properties

DELETE /form/:target_form_uuid/formFields/:target_formFields_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.