1 ![img](./public/images/openemr-rest-api.png)
5 This project aims to provide an easy-to-use JSON-based REST API for OpenEMR's most common functions. All code will be done in classes and separate from the view to help with codebase modernization efforts.
9 - [@matthewvita](https://github.com/matthewvita)
10 - [@sjpadgett](https://github.com/sjpadgett)
11 - [@juggernautsei](https://github.com/juggernautsei)
12 - [@kofiav](https://github.com/kofiav)
13 - [@bradymiller](https://github.com/bradymiller)
16 Enable this API service in OpenEMR menu: Administration->Globals->Connectors->"Enable OpenEMR REST API"
18 ### Using API Internally
19 There are several ways to make API calls from an authorized session and maintain security:
20 * cURL or Guzzle requests
21 * oeHttp OpenEMR Http Rest Client
24 Note: FHIR endpoints follow normal FHIR REST endpoints. Use `https://domain/apis/fhir as base URI.`
26 _Example:_ `https://domain/apis/fhir/Patient` returns a Patients bundle resource and etc..
30 Obtain an API token with your login (returns an API token). For FHIR replace Uri component 'api' with 'fhir':
33 curl -X POST -H 'Content-Type: application/json' 'https://localhost:8300/apis/api/auth' \
35 "grant_type":"password",
36 "username": "ServiceUser",
37 "password": "password",
44 "token_type":"Bearer",
45 "access_token":"d2870cb522230dbb8946b2f47d2c7e6664656661756c74",
49 Each call must include the token:
52 curl -X GET 'http://localhost:8300/apis/api/patient/1/medical_problem' \
53 -H 'Authorization: Bearer d2870cb522230dbb8946b2f47d2c7e6664656661756c74'
56 #### POST /api/facility
59 curl -X POST 'http://localhost:8300/apis/api/facility' -d \
62 "phone": "808-606-3030",
63 "fax": "808-606-3031",
64 "street": "1337 Bit Shifter Ln",
65 "city": "San Lorenzo",
67 "postal_code": "54321",
68 "email": "foo@bar.com",
69 "service_location": "1",
70 "billing_location": "1",
75 #### PUT /api/facility/:fid
78 curl -X PUT 'http://localhost:8300/apis/api/facility/1' -d \
81 "phone": "808-606-3030",
82 "fax": "808-606-3031",
83 "street": "1337 Bit Shifter Ln",
84 "city": "San Lorenzo",
86 "postal_code": "54321",
87 "email": "foo@bar.com",
88 "service_location": "1",
89 "billing_location": "1",
94 #### GET /api/facility
97 curl -X GET 'http://localhost:8300/apis/api/facility'
100 #### GET /api/facility/:fid
103 curl -X GET 'http://localhost:8300/apis/api/facility/1'
106 #### GET /api/provider
109 curl -X GET 'http://localhost:8300/apis/api/provider'
112 #### GET /api/provider/:prid
115 curl -X GET 'http://localhost:8300/apis/api/provider/1'
118 #### POST /api/patient
121 curl -X POST 'http://localhost:8300/apis/api/patient' -d \
127 "street": "456 Tree Lane",
128 "postal_code": "08642",
131 "country_code": "US",
132 "phone_contact": "123-456-7890",
140 #### PUT /api/patient/:pid
143 curl -X PUT 'http://localhost:8300/apis/api/patient/1' -d \
149 "street": "456 Tree Lane",
150 "postal_code": "08642",
153 "country_code": "US",
154 "phone_contact": "123-456-7890",
162 #### GET /api/patient
165 curl -X GET 'http://localhost:8300/apis/api/patient'
169 curl -X GET 'http://localhost:8300/apis/api/patient&fname=...&lname=...&dob=...'
172 #### GET /api/patient/:pid
175 curl -X GET 'http://localhost:8300/apis/api/patient/1'
178 #### GET /api/patient/:pid/encounter
181 curl -X GET 'http://localhost:8300/apis/api/patient/1/encounter'
184 #### GET /api/patient/:pid/encounter/:eid
187 curl -X GET 'http://localhost:8300/apis/api/patient/1/encounter/1'
190 #### POST /api/patient/:pid/encounter/:eid/vital
193 curl -X POST 'http://localhost:8300/apis/api/patient/1/encounter/1/vital' -d \
200 "temp_method": "Oral",
206 "oxygen_saturation": "80"
210 #### PUT /api/patient/:pid/encounter/:eid/vital/:vid
213 curl -X PUT 'http://localhost:8300/apis/api/patient/1/encounter/1/vital/1' -d \
220 "temp_method": "Oral",
226 "oxygen_saturation": "80"
230 #### GET /api/patient/:pid/encounter/:eid/vital
233 curl -X GET 'http://localhost:8300/apis/api/patient/1/encounter/1/vital'
236 #### GET /api/patient/:pid/encounter/:eid/vital/:vid
239 curl -X GET 'http://localhost:8300/apis/api/patient/1/encounter/1/vital/1'
242 #### POST /api/patient/:pid/encounter/:eid/soap_note
245 curl -X POST 'http://localhost:8300/apis/api/patient/1/encounter/1/soap_note' -d \
254 #### PUT /api/patient/:pid/encounter/:eid/soap_note/:sid
257 curl -X PUT 'http://localhost:8300/apis/api/patient/1/encounter/1/soap_note/1' -d \
266 #### GET /api/patient/:pid/encounter/:eid/soap_note
269 curl -X GET 'http://localhost:8300/apis/api/patient/1/encounter/1/soap_note'
272 #### GET /api/patient/:pid/encounter/:eid/soap_note/:sid
275 curl -X GET 'http://localhost:8300/apis/api/patient/1/encounter/1/soap_note/1'
278 #### POST /api/patient/:pid/medical_problem
281 curl -X POST 'http://localhost:8300/apis/api/patient/1/medical_problem' -d \
283 "title": "Dermatochalasis",
284 "begdate": "2010-04-13",
286 "diagnosis": "ICD10:H02.839"
290 #### PUT /api/patient/:pid/medical_problem/:mid
293 curl -X PUT 'http://localhost:8300/apis/api/patient/1/medical_problem/1' -d \
295 "title": "Dermatochalasis",
296 "begdate": "2010-04-13",
297 "enddate": "2018-03-12",
298 "diagnosis": "ICD10:H02.839"
302 #### GET /api/patient/:pid/medical_problem
305 curl -X GET 'http://localhost:8300/apis/api/patient/1/medical_problem'
308 #### GET /api/patient/:pid/medical_problem/:mid
311 curl -X GET 'http://localhost:8300/apis/api/patient/1/medical_problem/1'
314 #### DELETE /api/patient/:pid/medical_problem/:mid
317 curl -X DELETE 'http://localhost:8300/apis/api/patient/1/medical_problem/1'
320 #### POST /api/patient/:pid/allergy
323 curl -X POST 'http://localhost:8300/apis/api/patient/1/allergy' -d \
326 "begdate": "2010-10-13",
331 #### PUT /api/patient/:pid/allergy/:aid
334 curl -X PUT 'http://localhost:8300/apis/api/patient/1/allergy/1' -d \
337 "begdate": "2012-10-13",
342 #### GET /api/patient/:pid/allergy
345 curl -X GET 'http://localhost:8300/apis/api/patient/1/allergy'
348 #### GET /api/patient/:pid/allergy/:aid
351 curl -X GET 'http://localhost:8300/apis/api/patient/1/allergy/1'
354 #### DELETE /api/patient/:pid/allergy/:aid
357 curl -X DELETE 'http://localhost:8300/apis/api/patient/1/allergy/1'
360 #### POST /api/patient/:pid/medication
363 curl -X POST 'http://localhost:8300/apis/api/patient/1/medication' -d \
366 "begdate": "2013-10-13",
371 #### PUT /api/patient/:pid/medication/:mid
374 curl -X PUT 'http://localhost:8300/apis/api/patient/1/medication/1' -d \
377 "begdate": "2013-04-13",
382 #### GET /api/patient/:pid/medication
385 curl -X GET 'http://localhost:8300/apis/api/patient/1/medication'
388 #### GET /api/patient/:pid/medication/:mid
391 curl -X GET 'http://localhost:8300/apis/api/patient/1/medication/1'
394 #### DELETE /api/patient/:pid/medication/:mid
397 curl -X DELETE 'http://localhost:8300/apis/api/patient/1/medication/1'
400 #### POST /api/patient/:pid/surgery
403 curl -X POST 'http://localhost:8300/apis/api/patient/1/surgery' -d \
405 "title": "Blepharoplasty",
406 "begdate": "2013-10-13",
408 "diagnosis": "CPT4:15823-50"
412 #### PUT /api/patient/:pid/surgery/:sid
415 curl -X PUT 'http://localhost:8300/apis/api/patient/1/surgery/1' -d \
417 "title": "Blepharoplasty",
418 "begdate": "2013-10-14",
420 "diagnosis": "CPT4:15823-50"
424 #### GET /api/patient/:pid/surgery
427 curl -X GET 'http://localhost:8300/apis/api/patient/1/surgery'
430 #### GET /api/patient/:pid/surgery/:sid
433 curl -X GET 'http://localhost:8300/apis/api/patient/1/surgery/1'
436 #### DELETE /api/patient/:pid/surgery/:sid
439 curl -X DELETE 'http://localhost:8300/apis/api/patient/1/surgery/1'
442 #### POST /api/patient/:pid/dental_issue
445 curl -X POST 'http://localhost:8300/apis/api/patient/1/dental_issue' -d \
447 "title": "Halitosis",
448 "begdate": "2015-03-17",
453 #### PUT /api/patient/:pid/dental_issue/:did
456 curl -X PUT 'http://localhost:8300/apis/api/patient/1/dental_issue/1' -d \
458 "title": "Halitosis",
459 "begdate": "2015-03-17",
460 "enddate": "2018-03-20"
464 #### GET /api/patient/:pid/dental_issue
467 curl -X GET 'http://localhost:8300/apis/api/patient/1/dental_issue'
470 #### GET /api/patient/:pid/dental_issue/:did
473 curl -X GET 'http://localhost:8300/apis/api/patient/1/dental_issue/1'
476 #### DELETE /api/patient/:pid/dental_issue/:did
479 curl -X DELETE 'http://localhost:8300/apis/api/patient/1/dental_issue/1'
482 #### GET /api/patient/:pid/insurance
485 curl -X GET 'http://localhost:8300/apis/api/patient/1/insurance'
488 #### GET /api/patient/:pid/insurance/:type
491 curl -X GET 'http://localhost:8300/apis/api/patient/1/insurance/secondary'
494 #### POST /api/patient/:pid/insurance/:type
497 curl -X POST 'http://localhost:8300/apis/api/patient/10/insurance/primary' -d \
501 "plan_name": "Some Plan",
502 "policy_number": "12345",
503 "group_number": "252412",
504 "subscriber_lname": "Tester",
505 "subscriber_mname": "Xi",
506 "subscriber_fname": "Foo",
507 "subscriber_relationship": "other",
508 "subscriber_ss": "234231234",
509 "subscriber_DOB": "2018-10-03",
510 "subscriber_street": "183 Cool St",
511 "subscriber_postal_code": "23418",
512 "subscriber_city": "Cooltown",
513 "subscriber_state": "AZ",
514 "subscriber_country": "USA",
515 "subscriber_phone": "234-598-2123",
516 "subscriber_employer": "Some Employer",
517 "subscriber_employer_street": "123 Heather Lane",
518 "subscriber_employer_postal_code": "23415",
519 "subscriber_employer_state": "AZ",
520 "subscriber_employer_country": "USA",
521 "subscriber_employer_city": "Cooltown",
523 "date": "2018-10-15",
524 "subscriber_sex": "Female",
525 "accept_assignment": "TRUE",
531 - `provider` is the insurance company id
532 - `state` can be found by querying `resource=/api/list/state`
533 - `country` can be found by querying `resource=/api/list/country`
536 #### PUT /api/patient/:pid/insurance/:type
539 curl -X PUT 'http://localhost:8300/apis/api/patient/10/insurance/primary' -d \
543 "plan_name": "Some Plan",
544 "policy_number": "12345",
545 "group_number": "252412",
546 "subscriber_lname": "Tester",
547 "subscriber_mname": "Xi",
548 "subscriber_fname": "Foo",
549 "subscriber_relationship": "other",
550 "subscriber_ss": "234231234",
551 "subscriber_DOB": "2018-10-03",
552 "subscriber_street": "183 Cool St",
553 "subscriber_postal_code": "23418",
554 "subscriber_city": "Cooltown",
555 "subscriber_state": "AZ",
556 "subscriber_country": "USA",
557 "subscriber_phone": "234-598-2123",
558 "subscriber_employer": "Some Employer",
559 "subscriber_employer_street": "123 Heather Lane",
560 "subscriber_employer_postal_code": "23415",
561 "subscriber_employer_state": "AZ",
562 "subscriber_employer_country": "USA",
563 "subscriber_employer_city": "Cooltown",
565 "date": "2018-10-15",
566 "subscriber_sex": "Female",
567 "accept_assignment": "TRUE",
573 - `provider` is the insurance company id
574 - `state` can be found by querying `resource=/api/list/state`
575 - `country` can be found by querying `resource=/api/list/country`
577 #### GET /api/list/:list_name
580 curl -X GET 'http://localhost:8300/apis/api/list/medical_problem_issue_list'
583 #### GET /api/version
586 curl -X GET 'http://localhost:8300/apis/api/version'
589 #### GET /api/product
592 curl -X GET 'http://localhost:8300/apis/api/product'
595 #### GET /api/insurance_company
598 curl -X GET 'http://localhost:8300/apis/api/insurance_company'
601 #### GET /api/insurance_type
604 curl -X GET 'http://localhost:8300/apis/api/insurance_type'
607 #### POST /api/insurance_company
610 curl -X POST 'http://localhost:8300/apis/api/insurance_company' -d \
612 "name": "Cool Insurance Company",
615 "ins_type_code": "2",
616 "x12_receiver_id": null,
617 "x12_default_partner_id": null,
619 "line1": "123 Cool Lane",
620 "line2": "Suite 123",
628 Notes: `ins_type_code` can be found by inspecting the above route (/api/insurance_type).
630 #### PUT /api/insurance_company/:iid
633 curl -X PUT 'http://localhost:8300/apis/api/insurance_company/1' -d \
635 "name": "Super Insurance Company",
638 "ins_type_code": "2",
639 "x12_receiver_id": null,
640 "x12_default_partner_id": null,
642 "line1": "123 Cool Lane",
643 "line2": "Suite 123",
651 Notes: `ins_type_code` can be found by inspecting the above route (/api/insurance_type).
653 #### GET /api/appointment
656 curl -X GET 'http://localhost:8300/apis/api/appointment'
659 #### GET /api/appointment/:eid
662 curl -X GET 'http://localhost:8300/apis/api/appointment/1'
665 #### GET /api/patient/:pid/appointment
668 curl -X GET 'http://localhost:8300/apis/api/patient/1/appointment'
671 #### GET /api/patient/:pid/appointment/:eid
674 curl -X GET 'http://localhost:8300/apis/api/patient/1/appointment/1'
677 #### POST /api/patient/:pid/appointment
680 curl -X POST 'http://localhost:8300/apis/api/patient/1/appointment' -d \
684 "pc_title": "Office Visit",
685 "pc_duration": "900",
686 "pc_hometext": "Test",
687 "pc_apptstatus": "-",
688 "pc_eventDate": "2018-10-19",
689 "pc_startTime": "09:00",
691 "pc_billing_location": "10"
695 #### DELETE /api/patient/:pid/appointment/:eid
698 curl -X DELETE 'http://localhost:8300/apis/api/patient/1/appointment/1' -d \
701 #### GET /api/patient/:pid/document
704 curl -X GET 'http://localhost:8300/apis/api/patient/1/document&path=/eye_module/imaging-eye/drawings-eye'
707 Note: The `path` query string represents the OpenEMR documents paths with two exceptions:
709 - Spaces are represented with `_`
710 - All characters are lowercase
712 #### POST /api/patient/:pid/document
715 curl -X POST 'http://localhost:8300/apis/api/patient/1/document&path=/eye_module/imaging-eye/drawings-eye' \
716 -F document=@/home/someone/Desktop/drawing.jpg
719 Note: The `path` query string represents the OpenEMR documents paths with two exceptions:
721 - Spaces are represented with `_`
722 - All characters are lowercase
724 #### GET /api/patient/:pid/document/:did
727 wget 'http://localhost:8300/apis/api/patient/1/document/1'
730 #### POST /api/patient/:pid/message
733 curl -X POST 'http://localhost:8300/apis/api/patient/1/message' -d \
736 "groupname": "Default",
740 "message_status": "New"
745 - For `title`, use `resource=/api/list/note_type`
746 - For `message_type`, use `resource=/api/list/message_status`
748 #### PUT /api/patient/:pid/message/:mid
751 curl -X PUT 'http://localhost:8300/apis/api/patient/1/message/1' -d \
754 "groupname": "Default",
758 "message_status": "New"
763 - For `title`, use `resource=/api/list/note_type`
764 - For `message_type`, use `resource=/api/list/message_status`
766 #### DELETE /api/patient/:pid/message/:mid
769 curl -X DELETE 'http://localhost:8300/apis/api/patient/1/message/1'
774 - For business logic, make or use the services [here](https://github.com/openemr/openemr/tree/master/services)
775 - For controller logic, make or use the classes [here](https://github.com/openemr/openemr/tree/master/rest_controllers)
776 - For routing declarations, use the class [here](https://github.com/openemr/openemr/blob/master/_rest_routes.inc.php).
779 ### Project Management
781 - TODO(team): Consider using Symfony's router
782 - TODO(sherwin): Encounter POST
783 - TODO(matthew): Fix authorization piece
784 - TODO(?): Support CouchDB with document API
785 - TODO(?): Prevent `ListService` from using `enddate` of `0000-00-00` by default
786 - TODO(?): API for fee sheets
787 - TODO(?): API for pharmacies
788 - TODO(?): API for immunizations
789 - TODO(?): API for prescriptions
790 - TODO(?): Drug search API
791 - TODO(?): API for onotes
794 ### What is that dog drawing?
796 That is Peppy, an old OpenEMR mascot. Long live Peppy!
801 [GNU GPL](../LICENSE)