Current version

• By default, all requests to /openmrs/ws/rest receive the v1 version of the REST API.

• We have hosted online swagger documentation that is generated on the fly.

Resources

• Every available object in the web services (ws) module is written up as a resource.

• The resource class defines the properties that are exposed and the setters that are available.

• The class also defines the representations and what goes in them (ref vs default vs full).

See documentation about resources and their URIs here: REST Web Service Resources in OpenMRS 1.9

Subresources

• There are some objects that are not defined or do not make sense apart from their parent object which we refer as subresources.

• Examples are PersonNames, PersonAddresses, ConceptNames, etc.

• You can act on subresources under the parent url.

Examples :

Adding a person name.

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

Editing a person's name.

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

• A subresource can have only one parent.

• If it seems like an object has two or more parents, then it is most likely a top-level resource.

• Example "encounters" should not be a subresource of "patient" and "location" resource type (answering questions of "all encounters of a patient" and "all encounters at a location").

Instead, these should be queries on the encounter resource:

 Get encounter list for specific patient.

 GET '/openmrs/ws/rest/v1/encounter?patient=target_patient_uuid'

 Get encounter list for specific location.

 GET '/openmrs/ws/rest/v1/encounter?location=target_location_uuid'

Resources with Subtypes

• Some resources can have multiple subtypes, for example the order resource contains drugorder and testorder subtypes

• When creating a resource that has subtypes via a POST, you must specify which subtype of the resource you are creating, with a special t property of the object.

Examples :

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

• If you GET a resource that has subtypes, each result will be of one of those subtypes, which you can see by looking at the special t property of each result.

• You may query for only a certain subtype of a resource by providing a t query parameter.

 Get encounter orders of druge order sub type.

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

Authentication

• Almost every API endpoint(other than the /session endpoint) in OpenMRS API requires an authenticated user in order to interact.

• There is a filter defined on the module that intercepts all calls and authenticates the given request.

• Currently, only BASIC authentication is supported. Along with the HTTP request, a request header of Authorization: Basic (base64 of username:password) needs to be sent.

Alternatively, a session token can be used to interact with the API endpoints.

Retrieve session token

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

This token should be passed with all subsequent calls as a cookie named jsessionid=token.

Logout User/End session

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

Changing Password

Since version 2.17 of the webservices.rest module:

• An administrator (with the EDIT_USER_PASSWORDS privilege) can change the password for other users.

POST /openmrs/ws/rest/v1/password/target_user-UUID 
{
  "oldPassword" : "oldPassword",
  "newPassword" : "newPassword"
}

• After authenticating user can change their own password, by

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

Getting all location without authentication

Fetching locations requires you to authenticate the user first .If it is required to display all locations prior to login or without authentication you can do it by

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

Patients

Patients Overview

• Anyone who receives care in OpenMRS must be a Patient.

• Every Patient must have atleast one Identifier, which is explained below. (for example, Anyone who has an Encounter or who is enrolled in a Program is a Patient.)

• A Patient is also a Person, meaning they must have at least one name and they may have addresses.

Sub resource types of Patient

PatientIdentifier (Identifier)

• A PatientIdentifier is a medical record number assigned by your facility, used to identify and re-identify the patient on subsequent visits.

Allergy

• OpenMRS lets you manually maintain an Allergy List for a patient, including the allergen, reaction, severity, etc.

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

  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

GET /patient?
country=india
&gender=M

• List patient by 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.

GET /patient/:target_patient_uuid

Create a patient

• To create a patient you need to specify the below properties in the request. If you are not logged in to perform this action, a 401 Unauthorized status is returned.

  Properties

  Parameter	Type	Description
  person	PERSON_UUID	Person resource UUID
  identifiers	Array[]: Identifiers	List of patientIdentifiers

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

Update a patient

• Update a target patient with given UUID, this method only modifies properties in the request. Returns a 404 Not Found status if patient not exists. If user not logged in to perform this action, a 401 Unauthorized status returned.

  Query Parameters

  Parameter	Type	Description
  uuid	target_patient_uuid	Target patient resource UUID

  Properties

  Parameter	Type	Description
  resource	Patient	Patient resource with updated properties

  POST /patient/:target_patient_uuid
  -d modified_patient_object
  

Delete a patient

• Delete or retire a target patient by its UUID. Returns a 404 Not Found status if patient not exists. If user is not logged in to perform this action, a 401 Unauthorized status returned.

  Query Parameters

  Parameter	Type	Description
  uuid	String	uuid to delete
  purge	Boolean	The resource will be voided/retired unless purge = 'true'

DELETE /patient/:target_patient_uuid?purge=true

List patientIdentifier sub resources

• List all patientIdentifier sub resources for a patient.

  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

• List patientIdentifier sub resource by it's UUID and parent patient 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.

GET /patient/:target_patient_uuid/identifier/:target_identifier_uuid

Create a patientIdentifier sub resource with properties

• To create a patientIdentifier sub resource for a specific patient resource you need to specifyn below properties in your request body. If user not logged in to perform this action, a 401 Unauthorized status returned.

  Query parameter

  Parameter	Description

  target_patient_uuid : patient resource uuid

  Properties for resource

  Parameter	type	Description
  identifier	String	value of the identifier
  identifierType	Identifier_Type_UUID	Create identifier from this Identifier_type
  location	Location UUID	Get patients for this location
  preferred	boolean	preferred/not preferred identifier

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

• Updates an patientIdentifier sub resource value with given uuid, this method will only modify value of the sub resource. Returns a 404 Not Found status if attribute not exists.If user not logged in to perform this action, a 401 Unauthorized status returned.

  Properties

  Parameter	Type	Description
  identifier	String	updated value of the identifier
  identifierType	Identifier_Type_UUID	Create identifier from this Identifier_type
  location	Location UUID	updated location
  preferred	boolean	updated status of preferred/not preferred identifier

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 or retire a target identifier sub resource by its UUID.Returns a 404 Not Found status if attribute 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’

DELETE /patient/:target_patient_uuid/identifier/:target_identifier_uuid

List allergy sub resources

• List allergy sub resource by it's UUID and parent patient UUID.

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

GET /patient/:target_patient_uuid/allergy/:target_allergy_uuid

Create a allergy sub resource with properties

• To create a allergy sub resource for a specific patient resource you need to specify below properties in your request body. If user not logged in to perform this action, a 401 Unauthorized status returned.

  Query parameter

  Parameter	Description

  target_patient_uuid : patient resource uuid

  Properties for resource

  Parameter	type	Description
  allergen	String	value of the allergen
  severity	Severity_UUID	Severity uuid
  comment	String	comment for the allergy
  allergy	allergy_UUID	allergy uuid
  reaction	reaction_UUID	reaction uuid

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

• Updates an allergy sub resource value with given uuid, this method will only modify value of the sub resource. Returns a 404 Not Found status if property not exists.If user not logged in to perform this action, a 401 Unauthorized status returned.

  Query parameter

  Parameter	Description

  target_patient_uuid : patient resource uuid target_allergy_uuid : allergy resource uuid

  Properties for resource

  Parameter	type	Description
  allergen	String	value of the allergen
  severity	Severity_UUID	Severity uuid
  comment	String	comment for the allergy
  allergy	allergy_UUID	allergy uuid
  reaction	reaction_UUID	reaction uuid

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 or retire a target allergy sub resource by its UUID.Returns a 404 Not Found status if attribute 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’

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:

• format: a regular expression defining what the identifier text should contain

• formatDescription: An optional description of the regular expression (used to explain the requirements of the regular expression in terms a user would understand). For example, a regular expression like \d{4,8} could have a description like "Must be a number between 4 and 8 digits in length."

• required: a true/false whether every patient MUST have this type

• checkDigit: a true/false whether this identifier has a checkdigit at the end

• validator: full class name of an IdentifierValidator (e.g., org.openmrs.patient.impl.LuhnIdentifierValidator)

• locationBehavior: "REQUIRED" if a location must be associated with the identifier; "NOT_USED" if the identifier does require a location

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

  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 it returns 401 Unauthorized status is returned.

GET /patientidentifiertype

• Get patientIdentifierType by 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.

GET /patientidentifiertype/:target_patientIdentifierType_uuid

Create a patientIdentifierType

• To create a patientIdentifierType you need to specify the below properties in the request. If you are not logged in to perform this action, a 401 Unauthorized status is returned.

  Properties

  Parameter	Type	Description
  name	string	label for the identifier
  description	string	a small description about the patientIdentifier
  format	string	a regular expression defining what the identifier text should contain
  formatDescription	string	an optional description of the regular expression
  required	boolean	a true/false whether every patient MUST have this type
  checkDigit	boolean	a true/false whether this identifier has a checkdigit at the end
  validator	string	org.openmrs.patient.IdentifierValidator
  locationBehavior	"REQUIRED" or "NOT USED"	behavior of the location with respect to the identifier
  uniquenessBehavior	string	specify the uniqueness of the behaviour, it can be either Unique, Non Unique or Location.

POST /patientidentifiertype
{
    "name": "Wilson Hosp MRN",
    "description": "Wilson Hospital Medical Record Number",
    "format": "\d{1,10}-\d",
    "formatDescription": "Up to ten digts followed by a hyphen and another digit",
    "required": true,
    "validator": "org.openmrs.patient.impl.LuhnIdentifierValidator",
    "checkDigit": true,
    "locationBehavior": "REQUIRED",
    "uniquenessBehavior": "Unique"
}

Update a patientIdentifierType

• Update a target patientIdentifierType with given UUID, this method only modifies properties in the request. Returns a 404 Not Found status if patientIdentifierType not exists. If user not logged in to perform this action, a 401 Unauthorized status returned.

  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 or retire a target patientIdentifierType by its UUID. Returns a 404 Not Found status if patientIdentifierType not exists. If user is 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'

DELETE /patientidentifiertype/:target_patientidentifiertype_uuid?purge=true

Visits

Visits Overview

• A Visit in OpenMRS represents precisely what it sounds like: a time when a patient is actively interacting with the the healthcare system, typically at a location.

• The metadata differentiating different types of visits is a Visit Type. Visit Types displayed in the user interface, also, can be searched against.

• A visit contains encounters, which store more granular data about treatments or services.

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

• If you wish to record extra information about visits, you can create Visit Attributes and assign them to Visit Types.

• Visit attributes exists specifically to allow implementations to extend the data model.

Available operations for Visits

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

List visits

• List all non-retired visits.

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

  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?
includeInactive=true
&fromStartDate=2016-10-08T04:09:23.000Z
&patient=target_patient_uuid
&location=target_location_uuid

• List visit by UUID.

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

GET /visit/:target_visit_uuid

Create visit

• To Create a visit you need to specify below attributes in the request body.If you are not logged in to perform this action, a 401 Unauthorized status returned.

  Attributes

  Parameter	Type	Description
  patient	Patient UUID	Patient resource UUID
  visitType	Patient UUID	Visit type resource UUID
  startDatetime	Date (ISO8601 Long)	Start date of the visit
  location	Location UUID	Location resource UUID
  indication	string	Any indication of the visit
  stopDatetime	Date (ISO8601 Long)	End date of the vist
  encounters	Array[]: Encounter UUID	Encounter resources UUID
  attributes	Array[]: Attribute	List of visit attributes

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

• Update a target visit with given UUID, this method only modifies properties in the request. Returns a 404 Not Found status if visit not exists. If user not logged in to perform this action, a 401 Unauthorized status returned.

  Query Parameters

  Parameter	Type	Description
  uuid	target_visit_uuid	Target visit resource UUID

  Attributes

  Parameter	Type	Description
  resource	Visit	Visit resource with updated properties.

POST /visit/:target_visit_uuid
-d  modified_visit_object

Delete visit

• Delete or Retire a target visit by its UUID. Returns a 404 Not Found status if visit 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’

DELETE /visit/:target_visit_uuid?purge=true

List attribute sub resources

• List all attribute sub resources for a visit.

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

GET /visit/:target_visit_uuid/attribute 

• List attribute sub resources by it's UUID and parent visit UUID.

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

GET /visit/:target_visit_uuid/attribute/:target_attribute_uuid

Create an attribute sub resource with properties

• To Create an attribute sub resource for a specific visit resource you need to specify below attributes in the request body. If user not logged in to perform this action, a 401 Unauthorized status returned.

  Attributes

  Parameter	Type	Description
  attributeType	Attribute_Type UUID	Create Attribute from this Attribute_Type
  value	Depends on Attribute_Type Selected	Value for the attribute

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

Update attribute sub resource

• Updates an attribute sub resource value with given uuid, this method will only modify value of the sub resource.Returns a 404 Not Found status if attribute not exists.If user not logged in to perform this action, a 401 Unauthorized status returned.

  Attributes

  Parameter	Type	Description
  attributeType	Attribute_Type UUID	Attribute_Type resource UUID
  updated value	Depends on Attribute_Type Selected	Updated value for the attribute

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

Delete attribute sub resource

• Delete or Retire a target attribute sub resource by its UUID.Returns a 404 Not Found status if attribute 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’

DELETE /visit/:target_visit_uuid/attribute/:target_attribute_uuid

Visits Type

Visits Type Overview

• A Visit Type is a name and description of a kind of visit.

• Every visit has a type. You should create visit types that match how your health site classifies visits, such as "Outpatient," "Hospitalization," "Dental," "Patient Education," or "TB Clinic.".

• It is mandatory to set up at least one visit type.

• Visit types will be shown as dropdown options when creating or editing a patient in Registration.

• Visit types can be added via the OpenMRS admin screen(Administration > Visits > Manage Visit Types) or via sql scripts.

Available operations for Visits Type

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

List visits types

• List all non-retired visits types.

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

  Query Parameters

  Parameter	Type	Description
  q	Search Query	Display Name of Visit Type.

GET /visittype?q="Search Query"

• List visit type by UUID.

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

GET /visittype/:target_visit_type_uuid

Create a visit type

• To Create a visit type you need to specify below attributes in the request body.If you are not logged in to perform this action, a 401 Unauthorized status returned.

  Attributes

  Parameter	Type	Description
  name	String	Name of the visit type (Required)
  description	Patient UUID	Visit type resource UUID (Required)

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

Update a visit type

• Update a target visit type with given UUID, this method only modifies properties in the request. Returns a 404 Not Found status if visit not exists. If user not logged in to perform this action, a 401 Unauthorized status returned.

  Query Parameters

  Parameter	Type	Description
  uuid	target_visit_type_uuid	Target visit type resource UUID

  Attributes

  Parameter	Type	Description
  name	String	Name of the visit type (Required)
  description	Patient UUID	Visit type resource UUID (Required)

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 or Retire a target visit type by its UUID. Returns a 404 Not Found status if visit 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’

DELETE /visittype/:target_visit_type_uuid?purge=true

Visits Attribute Type

Visits Attribute Type Overview

• If you wish to record extra information about visits, you can create Visit Attributes and assign them to Visit Types.

• For example, you might create attributes for "Followup Visit," or "Distance Patient Traveled."

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

• List all non-retired visits attribute types.

  Quickly filter visit attribute types with a given search query. Returns a 404 Not Found status if the visit 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 Visit attribute type.

GET /visitattributetype?q="Search Query"

• List visit attribute type by UUID.

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

GET /visitattributetype/:target_visit_attribute_type_uuid

Create a visit attribute type

• To Create a visit attribute type you need to specify below attributes in the request body.If the user not logged in to perform this action, a 401 Unauthorized status returned.

  Attributes

  Parameter	Type	Description
  name	String	Name of the visit 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 visit.Use 0 or 1 as the default value (Required)
  maxOccurs	Number	Maximum number of times this value can be specified for a single visit (e.g., use 1 to prevent an attribute from being added to a visit multiple times)
  preferredHandlerClassname	Handler	Handler sub resource for the Custom Data Type used.Can optionally define a specific handler class want to use (otherwise the framework will choose the best handler for the chosen datatype).To find which handlers to use for the Custom DataType please refer here
  datatypeConfig	String	Allow the data type have any name and config it wants/needs.
  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

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

• Update a target visit attribute type with given UUID, this method only modifies properties in the request. Returns a 404 Not Found status if the visit attribute not exists. If the user not logged in to perform this action, a 401 Unauthorized status returned.

  Query Parameters

  Parameter	Type	Description
  uuid	target_visit_attribute_type_uuid	Target visit attribute type resource UUID

  Attributes

  Parameter	Type	Description
  name	String	Name of the visit 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 visit.Use 0 or 1 as the default value (Required) (Required)
  maxOccurs	Number	Maximum number of times this value can be specified for a single visit (e.g., use 1 to prevent an attribute from being added to a visit multiple times)
  preferredHandlerClassname	Handler	Handler sub resource for the Custom Data Type used.Can optionally define a specific handler class want to use (otherwise the framework will choose the best handler for the chosen datatype).To find which handlers to use for the Custom DataType please refer here
  datatypeConfig	String	Allow the data type have any name and config it wants/needs.
  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

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 or Retire a target visit attribute type by its UUID. Returns a 404 Not Found status if the visit attribute type 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 voided/retired unless purge = ‘true’.Purging will attempt to irreversibly remove the attribute type from the system. Attribute types that have been used (i.e., are referenced from existing data) cannot be purged.

DELETE /visitattributetype/:target_visit_attribute_type_uuid?purge=true

Location

Location Overview

• A Location is a physical place where a patient may be seen, such as a hospital, a room, a clinic, or a district.

• Locations may have a hierarchy,such that each location may have one parent location.

• Also a Location can have one or more Children location example Children's Ward might be a location within the location Amani Clinic.

• You might also store physical areas (for example Eastern Province, or California) as Locations.

• You should not use locations to represent logical ideas like All District Hospitals they should be modeled using LocationTags.

Location Sub Resource types

Location Attribute.

• If you wish to record extra information about location, you can create Location Attributes and assign them to Location Types.

• Location attributes exists specifically to allow implementations to extend the data model.

Available operations for Location

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

List location

• 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.

GET /location?
q="amani"

• List location by 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.

GET /location/:target_location_uuid

Create a location

• To Create a location you need to specify below attributes in the request body.If the user not logged in to perform this action, a 401 Unauthorized status returned.

  Attributes

  Parameter	Type	Description
  name	String	Name of the location (Required)
  address1	String	Address of the location (Required)
  description	String	Description
  cityVillage	String	City/village
  stateProvince	String	State and province
  country	String	Country
  postalCode	String	Postal code of the location
  latitude	String	Latitude
  longitude	String	Longitude
  countyDistrict	String	District or Country
  tags	Array[]: LocationTag UUID	UUID's of the location tags
  parentLocation	Parent Location UUID	UUID of the target parent location
  childLocations	Array[]: Child Location UUID	UUID's of the target child locations
  attributes	Array[]: Attribute UUID	UUID's of location attributes

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

• Update a target location with given UUID, this method only modifies properties in the request. 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
  uuid	target_location_uuid	Target location resource UUID

  Attributes

  Parameter	Type	Description
  name	String	Name of the location (Required)
  address1	String	Address of the location (Required)
  description	String	Description
  cityVillage	String	City/village
  stateProvince	String	State and province
  country	String	Country
  postalCode	String	Postal code of the location
  latitude	String	Latitude
  longitude	String	Longitude
  countyDistrict	String	District or Country
  tags	Array[]: LocationTag UUID	UUID's of the location tags
  parentLocation	Parent Location UUID	UUID of the target parent location
  childLocations	Array[]: Child Location UUID	UUID's of the target child locations
  attributes	Array[]: Attribute UUID	UUID's of location attributes

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 or Retire a target 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.

  Query Parameters

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

DELETE /location/:target_location_uuid?purge=true

List location attribute sub resources

• List all location attribute sub resources for a location.

  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.

GET /location/:target_location_uuid/attribute 

• List location attribute sub resources by own UUID and parent location 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.

GET /location/:target_location_uuid/attribute/:target_attribute_uuid

Create a location attribute sub resource with properties

• To Create an attribute sub resource for a specific location resource you need to specify below attributes in the request body. If the user not logged in to perform this action, a 401 Unauthorized status returned.

  Attributes

  Parameter	Type	Description
  attributeType	Attribute_Type UUID	Create Attribute from this Location Attribute_Type
  value	Depends on Attribute_Type Selected	Value for the attribute

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

Update a location attribute sub resource

• Updates a location attribute sub resource value with given uuid, this method will only modify value of the sub resource.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.

  Attributes

  Parameter	Type	Description
  attributeType	Attribute_Type UUID	Location Attribute_Type resource UUID
  updated value	Depends on Attribute_Type Selected	Updated value for the attribute

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

Delete a location attribute sub resource

• Delete or Retire a target location attribute sub resource by its 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.

  Query Parameters

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

DELETE /location/:target_location_uuid/attribute/:target_location_attribute_uuid

Location Tag Type

Location Tag Overview

• Tags are strings attached to an entity (like tagging of blog entries) to form a folksonomy and/or to categorize data.

• Location Tags are being used to tag locations, which enables the system to act based on the presence of tags on specific locations.

• You should not use locations to represent logical ideas like All-District Hospitals. They should be modeled using LocationTags.

• For example, location tags may be used to control which locations are included in a choice list or to define which locations included in a report.

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.

  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.

GET /locationtag?q="visit"

• List location tag by 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.

GET /locationtag/:target_location_tag_uuid

Create a location tag

• To Create a location tag you need to specify below attributes in the request body.If the user not logged in to perform this action, a 401 Unauthorized status returned.

  Attributes

  Parameter	Type	Description
  name	String	Name of the location tag (Required)
  description	String	Description (Required)
  retired	Boolean	Retired status of the location tag
  retiredReason	String	For location tags that are retired, this may contain an explanation of why the location tag was retired.

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

• Update a target location tag with given UUID, this method only modifies properties in the request. 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
  uuid	target_location_tag_uuid	Target location tag resource UUID

  Attributes

  Parameter	Type	Description
  name	String	Name of the location tag type (Required)
  description	String	Description (Required)
  retired	Boolean	Retired status of the location tag
  retiredReason	String	For location tags that are retired, this may contain an explanation of why the location tag was retired.

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 or Retire a target location tag type by its UUID. 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
  purge	Boolean	The resource will be voided/retired unless purge = ‘true’. Purging will attempt to irreversibly remove the tag from the system. Location tags types that have been used (i.e., are referenced from existing data) cannot be purged.

DELETE /locationtag/:target_location_tag_uuid?purge=true

Location Attribute Type

Location Attribute Overview

• If you wish to record extra information about locations, you can create Location Attributes and assign them to Location Types.

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.

  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.

GET /locationattributetype?q="humidity"

• List location attribute type by 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.

GET /locationattributetype/:target_location_attribute_type_uuid

Create a location attribute type

• To Create a location attribute type you need to specify below attributes in the request body. If the user not logged in to perform this action, a 401 Unauthorized status returned.

  Attributes

  Parameter	Type	Description
  name	String	Name of the location 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 location. Use 0 or 1 as the default value (Required)
  maxOccurs	Number	Maximum number of times this value can be specified for a single location (e.g., use 1 to prevent an attribute from being added to a location multiple times)
  preferredHandlerClassname	Handler	Handler sub resource for the Custom Data Type used. Can optionally define a specific handler class want to use (otherwise the framework will choose the best handler for the chosen datatype). To find which handlers to use for the Custom DataType please refer here
  datatypeConfig	String	Allow the data type have any name and config it wants/needs.
  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

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

• Update a target location attribute type with given UUID, this method only modifies properties in the request. Returns a 404 Not Found status if the location attribute not exists. If the user not logged in to perform this action, a 401 Unauthorized status returned.

  Query Parameters

  Parameter	Type	Description
  uuid	target_location_attribute_type_uuid	Target location attribute type resource UUID

  Attributes

  Parameter	Type	Description
  name	String	Name of the location 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 location. Use 0 or 1 as the default value (Required)
  maxOccurs	Number	Maximum number of times this value can be specified for a single location (e.g., use 1 to prevent an attribute from being added to a location multiple times)
  preferredHandlerClassname	Handler	Handler sub resource for the Custom Data Type used. Can optionally define a specific handler class want to use (otherwise the framework will choose the best handler for the chosen datatype). To find which handlers to use for the Custom DataType please refer here
  datatypeConfig	String	Allow the data type have any name and config it wants/needs.
  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

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 or Retire a target 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.

  Query Parameters

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

DELETE /locationattributetype/:target_location_attribute_type_uuid?purge=true

Encounters

Encounter Overview

• An encounter represents an interaction between a patient and the healthcare system at a single point in time. Common examples would be a patient seeing a doctor during a clinic visit, a patient going to the lab to have blood drawn for testing, or telephone call between a provider and the patient).

• Each encounter has an encounter type, date/time, location, and provider.

• Encounters are classified into Encounter Types, which describe the type of interaction the encounter represents – e.g., "HIV Initial", "Pediatric Follow Up", "Lab"). Implementations can define their own types of encounters.

• One or more encounters may be grouped within a Visit (e.g., an outpatient clinic visit or a hospitalization).

• Every encounter can have 0 to n Observations associated with it.

• Every encounter can have 0 to n Orders associated with it.

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

• A Provider is a person who provides care or services to patients.

• A provider may be a clinician like a doctor or nurse, a social worker, or a lab tech.

• Any healthcare worker that a patient can have an encounter with is a 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.

  Quickly filter encounters with given query parameters.Returns a 404 Not Found status if encounter not exists. If user 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)

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

• List encounter by 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.

GET /encounter/:target_encounter_uuid

Create an encounter

• To Create an encounter you need to specify below attributes in the request body.If you are not logged in to perform this action, a 401 Unauthorized status returned.

  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

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

Update an encounter

• Update a target encounter with given UUID, this method only modifies properties in the request. Returns a 404 Not Found status if encounter not exists. If user not logged in to perform this action, a 401 Unauthorized status returned.

  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

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

Delete an encounter

• Delete or Void a target 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.

  Query Parameters

  Parameter	Type	Description
  purge	Boolean	The resource will be voided unless purge = ‘true’

  DELETE /encounter/:target_encounter_uuid?purge=true

List encounter provider sub resources

• List all encounter provider sub resources for a visit.

  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.

GET /encounter/:target_encounter_uuid/encounterprovider 

• List encounter provider sub resources by it's UUID and parent encounter 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.

GET /encounter/:target_encounter_uuid/encounterprovider/:target_encounter_provider_uuid

Create an encounter provider sub resource with properties

• To Create an attribute sub resource for a specific visit resource you need to specify below attributes in the request body. If user not logged in to perform this action, a 401 Unauthorized status returned.

  Attributes

  Parameter	Type	Description
  provider	Provider_Type UUID	UUID of a provider currently registered in OpenMRS (required)
  encounterRole	Encounter_Role UUID	UUID of encounter role. This is the role provider will participate during this encounter (required)

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

Update encounter provider sub resource

• Updates an encounter provider sub resource value with given uuid, this method will only modify value of the sub resource. 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.

  Query Parameters

  Parameter	Type	Description
  parent_uuid	Encounter UUID	Target encounter resource UUID
  uuid	Encounter_Provider UUID	Target encounter provider resource UUID

  Attributes

  Parameter	Type	Description
  provider	Provider UUID	UUID of a provider currently registered in OpenMRS (required)
  encounterRole	Encounter_Role UUID	UUID of encounter role. This is the role provider will participate during this encounter (required)

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

Delete encounter provider sub resource

• Delete or Voided a target encounter provider sub resource by its UUID. Returns a 404 Not Found status if attribute 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 unless purge = ‘true’. Purging will attempt to irreversibly remove the encounter provider type from the system. Encounter provider types that have been used (i.e., are referenced from existing data) cannot be purged.

DELETE /encounter/:target_encounter_uuid/encounterprovider/:target_encounter_provider_uuid

Encounter Type

Encounter Type Overview

• Encounters represent an interaction between the patient and healthcare system. Since there are a wide variety of ways in which these interactions may occur, OpenMRS allows you categorize them by defining different types of encounter. For example, "Adult Primary Care Initial Visit" and "In-Between Visit Documentation" could be different types of encounters.

• You could define encounter type for locations such as Pharmacy, Lab, Consultation room or for actions such as admission or discharge.

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.

  Quickly filter encounter types with given query parameters.Returns a 404 Not Found status if encounter types not exists. If 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 /encountertype?
    q=Admission

• Get encounter type by UUID.

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

GET /encountertype/:target_encounter_type_uuid

Create an encounter type

• To Create an encounter type you need to specify below attributes in the request body. If you are not logged in to perform this action, a 401 Unauthorized status returned.

  Attributes

  Parameter	Type	Description
  name	String	Name for the encounter type (required)
  description	String	Description for the encounter type (required)

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

Update an encounter type

• Update a target encounter type with given UUID, this method only modifies properties in the request. Returns a 404 Not Found status if encounter type not exists. If user not logged in to perform this action, a 401 Unauthorized status returned.

  Attributes

  Parameter	Type	Description
  name	String	Name for the encounter type
  description	String	Description for the encounter type

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

Delete an encounter type

• Delete or retire a target encounter type by its UUID. Returns a 404 Not Found status if encounter type 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 retired unless purge = ‘true’

DELETE /encountertype/:target_encounter_type_uuid?purge=true

Encounter Role

Encounter Role Overview

• An Encounter role is specific to the encounter. While these could match up to existing organizational roles (e.g., “Nurse”), they don’t have to (e.g., “Lead Surgeon”).

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.

  Quickly filter encounter roles with given query parameters.Returns a 404 Not Found status if encounter roles not exists. If 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 role by its name

GET /encounterrole?
    q=Clinician
    ```

* ### Get encounter role by UUID.

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

```console
GET /encounter/:target_encounter_role_uuid

Create an encounter role

• To Create an encounter role you need to specify below attributes in the request body. If you are not logged in to perform this action, a 401 Unauthorized status returned.

  Attributes

  Parameter	Type	Description
  name	String	Name for the encounter role (required)
  description	`String	Description for the encounter role (required)

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

Update an encounter role

• Update a target encounter role with given UUID, this method only modifies properties in the request. 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.

  Attributes

  Parameter	Type	Description
  name	String	Name for the encounter role
  description	`String	Description for the encounter role

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

Delete an encounter role

• Delete or Void a target 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.

  Query Parameters

  Parameter	Type	Description
  purge	Boolean	The resource will be voided unless purge = ‘true’

DELETE /encounterrole/:target_encounter_role_uuid?purge=true

Providers

Provider Overview

• A Provider is a person who provides care or services to patients. A provider may be a clinician like a doctor or nurse, a social worker, or a lab tech. Generally speaking, any healthcare worker that a patient can have an encounter with is a provider.

• Providers may have full records in OpenMRS as persons, or they may just be a simple name and ID number.

Sub Resource types of Provider

Provider Attribute.

• If you wish to record extra information about providers, you can create Provider Attributes.

• Provider attributes exists specifically to allow implementations to extend the data model.

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

• List all non-retired providers.

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

  Query Parameters

  Parameter	Type	Description
  q	Search Query	Get provider by name

GET /provider?
q=clerk

• Query provider by UUID.

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

GET /provider/:target_provider_uuid

Create a provider

• To Create an provider you need to specify below attributes in the request body.If you are not logged in to perform this action, a 401 Unauthorized status returned.

  Attributes

  Parameter	Type	Description
  person	Person UUID	Target person who will be a provider for OpenMRS (required)
  identifier	String	Value of the identifier.Identifier is used to virtually group providers in to groups (required)
  attributes	Array[]: Attribute	List of provider attributes
  retired	Boolean	Retired status for the 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

• Update a target provider with given UUID, this method only modifies properties in the request. Returns a 404 Not Found status if provider not exists. If user not logged in to perform this action, a 401 Unauthorized status returned.

  Attributes

  Parameter	Type	Description
  person	Person UUID	Target person who will be a provider for OpenMRS (required)
  identifier	String	Value of the identifier.Identifier is used to virtually group providers in to groups (required)
  attributes	Array[]: Attribute	List of provider attributes
  retired	Boolean	Retired status for the 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 or retire a target provider by its UUID. Returns a 404 Not Found status if provider 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 retired unless purge = ‘true’

DELETE /provider/:target_provider_uuid?purge=true

List provider attribute sub resources

• List all provider attribute sub resources for a provider.

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

GET /provider/:target_provider_uuid/attribute 

• List provider attribute sub resources by it's UUID and parent provider UUID.

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

GET /provider/:target_provider_uuid/attribute/:target_provider_attribute_uuid

Create a provider attribute sub resource with properties

• To Create an attribute sub resource for a specific provider resource you need to specify below attributes in the request body. If user not logged in to perform this action, a 401 Unauthorized status returned.

  Attributes

  Parameter	Type	Description
  attributeType	Attribute_Type UUID	Create Attribute from this Attribute_Type (required)
  value	Depends on Attribute_Type Selected	Value for the attribute (required)

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

Update provider attribute sub resource

• Updates an provider attribute sub resource value with given uuid, this method will only modify value of the sub resource. Returns a 404 Not Found status if provider attribute not exists. If user not logged in to perform this action, a 401 Unauthorized status returned.

  Query Parameters

  Parameter	Type	Description
  parent_uuid	Provider UUID	Target provider resource UUID
  uuid	Provider_Attribute UUID	Target provider attribute resource UUID

  Attributes

  Parameter	Type	Description
  attributeType	Attribute_Type UUID	Create Attribute from this Attribute_Type
  value	Depends on Attribute_Type Selected	Value for the attribute

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

Delete provider attribute sub resource

• Delete or Retire a target provider attribute sub resource by its UUID. Returns a 404 Not Found status if attribute 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 retired unless purge = ‘true’. Purging will attempt to irreversibly remove the provider attribute type from the system. Provider attribute types that have been used (i.e., are referenced from existing data) cannot be purged.

DELETE /provider/:target_provider_uuid/attribute/:target_provider_attribute_uuid