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 tab.
19 Note: FHIR endpoints follow normal FHIR REST endpoints. Use `https://domain/apis/fhir as base URL.`
21 _Example:_ `https://domain/apis/fhir/Patient` returns a Patients bundle resource and etc..
25 Obtain an API token with your login (returns an API token). For FHIR replace Uri component 'api' with 'fhir':
28 curl -X POST 'https://localhost:8300/apis/api/auth' \
30 "grant_type":"password",
31 "username": "ServiceUser",
32 "password": "password",
39 "token_type":"Bearer",
40 "access_token":"d2870cb522230dbb8946b2f47d2c7e6664656661756c74",
44 Each call must include the token:
47 curl -X GET 'http://localhost:8300/apis/api/patient/1/medical_problem' \
48 -H 'Authorization: Bearer d2870cb522230dbb8946b2f47d2c7e6664656661756c74'
51 #### POST /api/facility
54 curl -X POST 'http://localhost:8300/apis/api/facility' -d \
57 "phone": "808-606-3030",
58 "fax": "808-606-3031",
59 "street": "1337 Bit Shifter Ln",
60 "city": "San Lorenzo",
62 "postal_code": "54321",
63 "email": "foo@bar.com",
64 "service_location": "1",
65 "billing_location": "1",
70 #### PUT /api/facility/:fid
73 curl -X PUT 'http://localhost:8300/apis/api/facility/1' -d \
76 "phone": "808-606-3030",
77 "fax": "808-606-3031",
78 "street": "1337 Bit Shifter Ln",
79 "city": "San Lorenzo",
81 "postal_code": "54321",
82 "email": "foo@bar.com",
83 "service_location": "1",
84 "billing_location": "1",
89 #### GET /api/facility
92 curl -X GET 'http://localhost:8300/apis/api/facility'
95 #### GET /api/facility/:fid
98 curl -X GET 'http://localhost:8300/apis/api/facility/1'
101 #### GET /api/provider
104 curl -X GET 'http://localhost:8300/apis/api/provider'
107 #### GET /api/provider/:prid
110 curl -X GET 'http://localhost:8300/apis/api/provider/1'
113 #### POST /api/patient
116 curl -X POST 'http://localhost:8300/apis/api/patient' -d \
122 "street": "456 Tree Lane",
123 "postal_code": "08642",
126 "country_code": "US",
127 "phone_contact": "123-456-7890",
135 #### PUT /api/patient/:pid
138 curl -X PUT 'http://localhost:8300/apis/api/patient/1' -d \
144 "street": "456 Tree Lane",
145 "postal_code": "08642",
148 "country_code": "US",
149 "phone_contact": "123-456-7890",
157 #### GET /api/patient
160 curl -X GET 'http://localhost:8300/apis/api/patient'
164 curl -X GET 'http://localhost:8300/apis/api/patient&fname=...&lname=...&dob=...'
167 #### GET /api/patient/:pid
170 curl -X GET 'http://localhost:8300/apis/api/patient/1'
173 #### GET /api/patient/:pid/encounter
176 curl -X GET 'http://localhost:8300/apis/api/patient/1/encounter'
179 #### GET /api/patient/:pid/encounter/:eid
182 curl -X GET 'http://localhost:8300/apis/api/patient/1/encounter/1'
185 #### POST /api/patient/:pid/encounter/:eid/vital
188 curl -X POST 'http://localhost:8300/apis/api/patient/1/encounter/1/vital' -d \
195 "temp_method": "Oral",
201 "oxygen_saturation": "80"
205 #### PUT /api/patient/:pid/encounter/:eid/vital/:vid
208 curl -X PUT 'http://localhost:8300/apis/api/patient/1/encounter/1/vital/1' -d \
215 "temp_method": "Oral",
221 "oxygen_saturation": "80"
225 #### GET /api/patient/:pid/encounter/:eid/vital
228 curl -X GET 'http://localhost:8300/apis/api/patient/1/encounter/1/vital'
231 #### GET /api/patient/:pid/encounter/:eid/vital/:vid
234 curl -X GET 'http://localhost:8300/apis/api/patient/1/encounter/1/vital/1'
237 #### POST /api/patient/:pid/encounter/:eid/soap_note
240 curl -X POST 'http://localhost:8300/apis/api/patient/1/encounter/1/soap_note' -d \
249 #### PUT /api/patient/:pid/encounter/:eid/soap_note/:sid
252 curl -X PUT 'http://localhost:8300/apis/api/patient/1/encounter/1/soap_note/1' -d \
261 #### GET /api/patient/:pid/encounter/:eid/soap_note
264 curl -X GET 'http://localhost:8300/apis/api/patient/1/encounter/1/soap_note'
267 #### GET /api/patient/:pid/encounter/:eid/soap_note/:sid
270 curl -X GET 'http://localhost:8300/apis/api/patient/1/encounter/1/soap_note/1'
273 #### POST /api/patient/:pid/medical_problem
276 curl -X POST 'http://localhost:8300/apis/api/patient/1/medical_problem' -d \
278 "title": "Dermatochalasis",
279 "begdate": "2010-04-13",
281 "diagnosis": "ICD10:H02.839"
285 #### PUT /api/patient/:pid/medical_problem/:mid
288 curl -X PUT 'http://localhost:8300/apis/api/patient/1/medical_problem/1' -d \
290 "title": "Dermatochalasis",
291 "begdate": "2010-04-13",
292 "enddate": "2018-03-12",
293 "diagnosis": "ICD10:H02.839"
297 #### GET /api/patient/:pid/medical_problem
300 curl -X GET 'http://localhost:8300/apis/api/patient/1/medical_problem'
303 #### GET /api/patient/:pid/medical_problem/:mid
306 curl -X GET 'http://localhost:8300/apis/api/patient/1/medical_problem/1'
309 #### DELETE /api/patient/:pid/medical_problem/:mid
312 curl -X DELETE 'http://localhost:8300/apis/api/patient/1/medical_problem/1'
315 #### POST /api/patient/:pid/allergy
318 curl -X POST 'http://localhost:8300/apis/api/patient/1/allergy' -d \
321 "begdate": "2010-10-13",
326 #### PUT /api/patient/:pid/allergy/:aid
329 curl -X PUT 'http://localhost:8300/apis/api/patient/1/allergy/1' -d \
332 "begdate": "2012-10-13",
337 #### GET /api/patient/:pid/allergy
340 curl -X GET 'http://localhost:8300/apis/api/patient/1/allergy'
343 #### GET /api/patient/:pid/allergy/:aid
346 curl -X GET 'http://localhost:8300/apis/api/patient/1/allergy/1'
349 #### DELETE /api/patient/:pid/allergy/:aid
352 curl -X DELETE 'http://localhost:8300/apis/api/patient/1/allergy/1'
355 #### POST /api/patient/:pid/medication
358 curl -X POST 'http://localhost:8300/apis/api/patient/1/medication' -d \
361 "begdate": "2013-10-13",
366 #### PUT /api/patient/:pid/medication/:mid
369 curl -X PUT 'http://localhost:8300/apis/api/patient/1/medication/1' -d \
372 "begdate": "2013-04-13",
377 #### GET /api/patient/:pid/medication
380 curl -X GET 'http://localhost:8300/apis/api/patient/1/medication'
383 #### GET /api/patient/:pid/medication/:mid
386 curl -X GET 'http://localhost:8300/apis/api/patient/1/medication/1'
389 #### DELETE /api/patient/:pid/medication/:mid
392 curl -X DELETE 'http://localhost:8300/apis/api/patient/1/medication/1'
395 #### POST /api/patient/:pid/surgery
398 curl -X POST 'http://localhost:8300/apis/api/patient/1/surgery' -d \
400 "title": "Blepharoplasty",
401 "begdate": "2013-10-13",
403 "diagnosis": "CPT4:15823-50"
407 #### PUT /api/patient/:pid/surgery/:sid
410 curl -X PUT 'http://localhost:8300/apis/api/patient/1/surgery/1' -d \
412 "title": "Blepharoplasty",
413 "begdate": "2013-10-14",
415 "diagnosis": "CPT4:15823-50"
419 #### GET /api/patient/:pid/surgery
422 curl -X GET 'http://localhost:8300/apis/api/patient/1/surgery'
425 #### GET /api/patient/:pid/surgery/:sid
428 curl -X GET 'http://localhost:8300/apis/api/patient/1/surgery/1'
431 #### DELETE /api/patient/:pid/surgery/:sid
434 curl -X DELETE 'http://localhost:8300/apis/api/patient/1/surgery/1'
437 #### POST /api/patient/:pid/dental_issue
440 curl -X POST 'http://localhost:8300/apis/api/patient/1/dental_issue' -d \
442 "title": "Halitosis",
443 "begdate": "2015-03-17",
448 #### PUT /api/patient/:pid/dental_issue/:did
451 curl -X PUT 'http://localhost:8300/apis/api/patient/1/dental_issue/1' -d \
453 "title": "Halitosis",
454 "begdate": "2015-03-17",
455 "enddate": "2018-03-20"
459 #### GET /api/patient/:pid/dental_issue
462 curl -X GET 'http://localhost:8300/apis/api/patient/1/dental_issue'
465 #### GET /api/patient/:pid/dental_issue/:did
468 curl -X GET 'http://localhost:8300/apis/api/patient/1/dental_issue/1'
471 #### DELETE /api/patient/:pid/dental_issue/:did
474 curl -X DELETE 'http://localhost:8300/apis/api/patient/1/dental_issue/1'
477 #### GET /api/patient/:pid/insurance
480 curl -X GET 'http://localhost:8300/apis/api/patient/1/insurance'
483 #### GET /api/patient/:pid/insurance/:type
486 curl -X GET 'http://localhost:8300/apis/api/patient/1/insurance/secondary'
489 #### POST /api/patient/:pid/insurance/:type
492 curl -X POST 'http://localhost:8300/apis/api/patient/10/insurance/primary' -d \
496 "plan_name": "Some Plan",
497 "policy_number": "12345",
498 "group_number": "252412",
499 "subscriber_lname": "Tester",
500 "subscriber_mname": "Xi",
501 "subscriber_fname": "Foo",
502 "subscriber_relationship": "other",
503 "subscriber_ss": "234231234",
504 "subscriber_DOB": "2018-10-03",
505 "subscriber_street": "183 Cool St",
506 "subscriber_postal_code": "23418",
507 "subscriber_city": "Cooltown",
508 "subscriber_state": "AZ",
509 "subscriber_country": "USA",
510 "subscriber_phone": "234-598-2123",
511 "subscriber_employer": "Some Employer",
512 "subscriber_employer_street": "123 Heather Lane",
513 "subscriber_employer_postal_code": "23415",
514 "subscriber_employer_state": "AZ",
515 "subscriber_employer_country": "USA",
516 "subscriber_employer_city": "Cooltown",
518 "date": "2018-10-15",
519 "subscriber_sex": "Female",
520 "accept_assignment": "TRUE",
526 - `provider` is the insurance company id
527 - `state` can be found by querying `resource=/api/list/state`
528 - `country` can be found by querying `resource=/api/list/country`
531 #### PUT /api/patient/:pid/insurance/:type
534 curl -X PUT 'http://localhost:8300/apis/api/patient/10/insurance/primary' -d \
538 "plan_name": "Some Plan",
539 "policy_number": "12345",
540 "group_number": "252412",
541 "subscriber_lname": "Tester",
542 "subscriber_mname": "Xi",
543 "subscriber_fname": "Foo",
544 "subscriber_relationship": "other",
545 "subscriber_ss": "234231234",
546 "subscriber_DOB": "2018-10-03",
547 "subscriber_street": "183 Cool St",
548 "subscriber_postal_code": "23418",
549 "subscriber_city": "Cooltown",
550 "subscriber_state": "AZ",
551 "subscriber_country": "USA",
552 "subscriber_phone": "234-598-2123",
553 "subscriber_employer": "Some Employer",
554 "subscriber_employer_street": "123 Heather Lane",
555 "subscriber_employer_postal_code": "23415",
556 "subscriber_employer_state": "AZ",
557 "subscriber_employer_country": "USA",
558 "subscriber_employer_city": "Cooltown",
560 "date": "2018-10-15",
561 "subscriber_sex": "Female",
562 "accept_assignment": "TRUE",
568 - `provider` is the insurance company id
569 - `state` can be found by querying `resource=/api/list/state`
570 - `country` can be found by querying `resource=/api/list/country`
572 #### GET /api/list/:list_name
575 curl -X GET 'http://localhost:8300/apis/api/list/medical_problem_issue_list'
578 #### GET /api/version
581 curl -X GET 'http://localhost:8300/apis/api/version'
584 #### GET /api/product
587 curl -X GET 'http://localhost:8300/apis/api/product'
590 #### GET /api/insurance_company
593 curl -X GET 'http://localhost:8300/apis/api/insurance_company'
596 #### GET /api/insurance_type
599 curl -X GET 'http://localhost:8300/apis/api/insurance_type'
602 #### POST /api/insurance_company
605 curl -X POST 'http://localhost:8300/apis/api/insurance_company' -d \
607 "name": "Cool Insurance Company",
610 "ins_type_code": "2",
611 "x12_receiver_id": null,
612 "x12_default_partner_id": null,
614 "line1": "123 Cool Lane",
615 "line2": "Suite 123",
623 Notes: `ins_type_code` can be found by inspecting the above route (/api/insurance_type).
625 #### PUT /api/insurance_company/:iid
628 curl -X PUT 'http://localhost:8300/apis/api/insurance_company/1' -d \
630 "name": "Super Insurance Company",
633 "ins_type_code": "2",
634 "x12_receiver_id": null,
635 "x12_default_partner_id": null,
637 "line1": "123 Cool Lane",
638 "line2": "Suite 123",
646 Notes: `ins_type_code` can be found by inspecting the above route (/api/insurance_type).
648 #### GET /api/appointment
651 curl -X GET 'http://localhost:8300/apis/api/appointment'
654 #### GET /api/appointment/:eid
657 curl -X GET 'http://localhost:8300/apis/api/appointment/1'
660 #### GET /api/patient/:pid/appointment
663 curl -X GET 'http://localhost:8300/apis/api/patient/1/appointment'
666 #### GET /api/patient/:pid/appointment/:eid
669 curl -X GET 'http://localhost:8300/apis/api/patient/1/appointment/1'
672 #### POST /api/patient/:pid/appointment
675 curl -X POST 'http://localhost:8300/apis/api/patient/1/appointment' -d \
679 "pc_title": "Office Visit",
680 "pc_duration": "900",
681 "pc_hometext": "Test",
682 "pc_apptstatus": "-",
683 "pc_eventDate": "2018-10-19",
684 "pc_startTime": "09:00",
686 "pc_billing_location": "10"
690 #### DELETE /api/patient/:pid/appointment/:eid
693 curl -X DELETE 'http://localhost:8300/apis/api/patient/1/appointment/1' -d \
696 #### GET /api/patient/:pid/document
699 curl -X GET 'http://localhost:8300/apis/api/patient/1/document&path=/eye_module/imaging-eye/drawings-eye'
702 Note: The `path` query string represents the OpenEMR documents paths with two exceptions:
704 - Spaces are represented with `_`
705 - All characters are lowercase
707 #### POST /api/patient/:pid/document
710 curl -X POST 'http://localhost:8300/apis/api/patient/1/document&path=/eye_module/imaging-eye/drawings-eye' \
711 -F document=@/home/someone/Desktop/drawing.jpg
714 Note: The `path` query string represents the OpenEMR documents paths with two exceptions:
716 - Spaces are represented with `_`
717 - All characters are lowercase
719 #### GET /api/patient/:pid/document/:did
722 wget 'http://localhost:8300/apis/api/patient/1/document/1'
725 #### POST /api/patient/:pid/message
728 curl -X POST 'http://localhost:8300/apis/api/patient/1/message' -d \
731 "groupname": "Default",
735 "message_status": "New"
740 - For `title`, use `resource=/api/list/note_type`
741 - For `message_type`, use `resource=/api/list/message_status`
743 #### PUT /api/patient/:pid/message/:mid
746 curl -X PUT 'http://localhost:8300/apis/api/patient/1/message/1' -d \
749 "groupname": "Default",
753 "message_status": "New"
758 - For `title`, use `resource=/api/list/note_type`
759 - For `message_type`, use `resource=/api/list/message_status`
761 #### DELETE /api/patient/:pid/message/:mid
764 curl -X DELETE 'http://localhost:8300/apis/api/patient/1/message/1'
769 - For business logic, make or use the services [here](https://github.com/openemr/openemr/tree/master/services)
770 - For controller logic, make or use the classes [here](https://github.com/openemr/openemr/tree/master/rest_controllers)
771 - For routing declarations, use the class [here](https://github.com/openemr/openemr/blob/master/_rest_routes.inc.php).
774 ### Project Management
776 - TODO(team): Consider using Symfony's router
777 - TODO(sherwin): Encounter POST
778 - TODO(matthew): Fix authorization piece
779 - TODO(?): Support CouchDB with document API
780 - TODO(?): Prevent `ListService` from using `enddate` of `0000-00-00` by default
781 - TODO(?): API for fee sheets
782 - TODO(?): API for pharmacies
783 - TODO(?): API for immunizations
784 - TODO(?): API for prescriptions
785 - TODO(?): Drug search API
786 - TODO(?): API for onotes
789 ### What is that dog drawing?
791 That is Peppy, an old OpenEMR mascot. Long live Peppy!
796 [GNU GPL](../LICENSE)