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':
31 Scope must match a site that has been setup in OpenEMR in the /sites/ directory. If you haven't created additional sites
32 then 'default' should be the scope.
35 curl -X POST -H 'Content-Type: application/json' 'https://localhost:8300/apis/api/auth' \
37 "grant_type":"password",
38 "username": "ServiceUser",
39 "password": "password",
46 "token_type":"Bearer",
47 "access_token":"d2870cb522230dbb8946b2f47d2c7e6664656661756c74",
51 Each call must include the token:
54 curl -X GET 'http://localhost:8300/apis/api/patient/1/medical_problem' \
55 -H 'Authorization: Bearer d2870cb522230dbb8946b2f47d2c7e6664656661756c74'
58 #### POST /api/facility
61 curl -X POST 'http://localhost:8300/apis/api/facility' -d \
64 "phone": "808-606-3030",
65 "fax": "808-606-3031",
66 "street": "1337 Bit Shifter Ln",
67 "city": "San Lorenzo",
69 "postal_code": "54321",
70 "email": "foo@bar.com",
71 "service_location": "1",
72 "billing_location": "1",
77 #### PUT /api/facility/:fid
80 curl -X PUT 'http://localhost:8300/apis/api/facility/1' -d \
83 "phone": "808-606-3030",
84 "fax": "808-606-3031",
85 "street": "1337 Bit Shifter Ln",
86 "city": "San Lorenzo",
88 "postal_code": "54321",
89 "email": "foo@bar.com",
90 "service_location": "1",
91 "billing_location": "1",
96 #### GET /api/facility
99 curl -X GET 'http://localhost:8300/apis/api/facility'
102 #### GET /api/facility/:fid
105 curl -X GET 'http://localhost:8300/apis/api/facility/1'
108 #### GET /api/provider
111 curl -X GET 'http://localhost:8300/apis/api/provider'
114 #### GET /api/provider/:prid
117 curl -X GET 'http://localhost:8300/apis/api/provider/1'
120 #### POST /api/patient
123 curl -X POST 'http://localhost:8300/apis/api/patient' -d \
129 "street": "456 Tree Lane",
130 "postal_code": "08642",
133 "country_code": "US",
134 "phone_contact": "123-456-7890",
142 #### PUT /api/patient/:pid
145 curl -X PUT 'http://localhost:8300/apis/api/patient/1' -d \
151 "street": "456 Tree Lane",
152 "postal_code": "08642",
155 "country_code": "US",
156 "phone_contact": "123-456-7890",
164 #### GET /api/patient
167 curl -X GET 'http://localhost:8300/apis/api/patient'
171 curl -X GET 'http://localhost:8300/apis/api/patient&fname=...&lname=...&dob=...'
174 #### GET /api/patient/:pid
177 curl -X GET 'http://localhost:8300/apis/api/patient/1'
180 #### GET /api/patient/:pid/encounter
183 curl -X GET 'http://localhost:8300/apis/api/patient/1/encounter'
186 #### GET /api/patient/:pid/encounter/:eid
189 curl -X GET 'http://localhost:8300/apis/api/patient/1/encounter/1'
192 #### POST /api/patient/:pid/encounter/:eid/vital
195 curl -X POST 'http://localhost:8300/apis/api/patient/1/encounter/1/vital' -d \
202 "temp_method": "Oral",
208 "oxygen_saturation": "80"
212 #### PUT /api/patient/:pid/encounter/:eid/vital/:vid
215 curl -X PUT 'http://localhost:8300/apis/api/patient/1/encounter/1/vital/1' -d \
222 "temp_method": "Oral",
228 "oxygen_saturation": "80"
232 #### GET /api/patient/:pid/encounter/:eid/vital
235 curl -X GET 'http://localhost:8300/apis/api/patient/1/encounter/1/vital'
238 #### GET /api/patient/:pid/encounter/:eid/vital/:vid
241 curl -X GET 'http://localhost:8300/apis/api/patient/1/encounter/1/vital/1'
244 #### POST /api/patient/:pid/encounter/:eid/soap_note
247 curl -X POST 'http://localhost:8300/apis/api/patient/1/encounter/1/soap_note' -d \
256 #### PUT /api/patient/:pid/encounter/:eid/soap_note/:sid
259 curl -X PUT 'http://localhost:8300/apis/api/patient/1/encounter/1/soap_note/1' -d \
268 #### GET /api/patient/:pid/encounter/:eid/soap_note
271 curl -X GET 'http://localhost:8300/apis/api/patient/1/encounter/1/soap_note'
274 #### GET /api/patient/:pid/encounter/:eid/soap_note/:sid
277 curl -X GET 'http://localhost:8300/apis/api/patient/1/encounter/1/soap_note/1'
280 #### POST /api/patient/:pid/medical_problem
283 curl -X POST 'http://localhost:8300/apis/api/patient/1/medical_problem' -d \
285 "title": "Dermatochalasis",
286 "begdate": "2010-04-13",
288 "diagnosis": "ICD10:H02.839"
292 #### PUT /api/patient/:pid/medical_problem/:mid
295 curl -X PUT 'http://localhost:8300/apis/api/patient/1/medical_problem/1' -d \
297 "title": "Dermatochalasis",
298 "begdate": "2010-04-13",
299 "enddate": "2018-03-12",
300 "diagnosis": "ICD10:H02.839"
304 #### GET /api/patient/:pid/medical_problem
307 curl -X GET 'http://localhost:8300/apis/api/patient/1/medical_problem'
310 #### GET /api/patient/:pid/medical_problem/:mid
313 curl -X GET 'http://localhost:8300/apis/api/patient/1/medical_problem/1'
316 #### DELETE /api/patient/:pid/medical_problem/:mid
319 curl -X DELETE 'http://localhost:8300/apis/api/patient/1/medical_problem/1'
322 #### POST /api/patient/:pid/allergy
325 curl -X POST 'http://localhost:8300/apis/api/patient/1/allergy' -d \
328 "begdate": "2010-10-13",
333 #### PUT /api/patient/:pid/allergy/:aid
336 curl -X PUT 'http://localhost:8300/apis/api/patient/1/allergy/1' -d \
339 "begdate": "2012-10-13",
344 #### GET /api/patient/:pid/allergy
347 curl -X GET 'http://localhost:8300/apis/api/patient/1/allergy'
350 #### GET /api/patient/:pid/allergy/:aid
353 curl -X GET 'http://localhost:8300/apis/api/patient/1/allergy/1'
356 #### DELETE /api/patient/:pid/allergy/:aid
359 curl -X DELETE 'http://localhost:8300/apis/api/patient/1/allergy/1'
362 #### POST /api/patient/:pid/medication
365 curl -X POST 'http://localhost:8300/apis/api/patient/1/medication' -d \
368 "begdate": "2013-10-13",
373 #### PUT /api/patient/:pid/medication/:mid
376 curl -X PUT 'http://localhost:8300/apis/api/patient/1/medication/1' -d \
379 "begdate": "2013-04-13",
384 #### GET /api/patient/:pid/medication
387 curl -X GET 'http://localhost:8300/apis/api/patient/1/medication'
390 #### GET /api/patient/:pid/medication/:mid
393 curl -X GET 'http://localhost:8300/apis/api/patient/1/medication/1'
396 #### DELETE /api/patient/:pid/medication/:mid
399 curl -X DELETE 'http://localhost:8300/apis/api/patient/1/medication/1'
402 #### POST /api/patient/:pid/surgery
405 curl -X POST 'http://localhost:8300/apis/api/patient/1/surgery' -d \
407 "title": "Blepharoplasty",
408 "begdate": "2013-10-13",
410 "diagnosis": "CPT4:15823-50"
414 #### PUT /api/patient/:pid/surgery/:sid
417 curl -X PUT 'http://localhost:8300/apis/api/patient/1/surgery/1' -d \
419 "title": "Blepharoplasty",
420 "begdate": "2013-10-14",
422 "diagnosis": "CPT4:15823-50"
426 #### GET /api/patient/:pid/surgery
429 curl -X GET 'http://localhost:8300/apis/api/patient/1/surgery'
432 #### GET /api/patient/:pid/surgery/:sid
435 curl -X GET 'http://localhost:8300/apis/api/patient/1/surgery/1'
438 #### DELETE /api/patient/:pid/surgery/:sid
441 curl -X DELETE 'http://localhost:8300/apis/api/patient/1/surgery/1'
444 #### POST /api/patient/:pid/dental_issue
447 curl -X POST 'http://localhost:8300/apis/api/patient/1/dental_issue' -d \
449 "title": "Halitosis",
450 "begdate": "2015-03-17",
455 #### PUT /api/patient/:pid/dental_issue/:did
458 curl -X PUT 'http://localhost:8300/apis/api/patient/1/dental_issue/1' -d \
460 "title": "Halitosis",
461 "begdate": "2015-03-17",
462 "enddate": "2018-03-20"
466 #### GET /api/patient/:pid/dental_issue
469 curl -X GET 'http://localhost:8300/apis/api/patient/1/dental_issue'
472 #### GET /api/patient/:pid/dental_issue/:did
475 curl -X GET 'http://localhost:8300/apis/api/patient/1/dental_issue/1'
478 #### DELETE /api/patient/:pid/dental_issue/:did
481 curl -X DELETE 'http://localhost:8300/apis/api/patient/1/dental_issue/1'
484 #### GET /api/patient/:pid/insurance
487 curl -X GET 'http://localhost:8300/apis/api/patient/1/insurance'
490 #### GET /api/patient/:pid/insurance/:type
493 curl -X GET 'http://localhost:8300/apis/api/patient/1/insurance/secondary'
496 #### POST /api/patient/:pid/insurance/:type
499 curl -X POST 'http://localhost:8300/apis/api/patient/10/insurance/primary' -d \
503 "plan_name": "Some Plan",
504 "policy_number": "12345",
505 "group_number": "252412",
506 "subscriber_lname": "Tester",
507 "subscriber_mname": "Xi",
508 "subscriber_fname": "Foo",
509 "subscriber_relationship": "other",
510 "subscriber_ss": "234231234",
511 "subscriber_DOB": "2018-10-03",
512 "subscriber_street": "183 Cool St",
513 "subscriber_postal_code": "23418",
514 "subscriber_city": "Cooltown",
515 "subscriber_state": "AZ",
516 "subscriber_country": "USA",
517 "subscriber_phone": "234-598-2123",
518 "subscriber_employer": "Some Employer",
519 "subscriber_employer_street": "123 Heather Lane",
520 "subscriber_employer_postal_code": "23415",
521 "subscriber_employer_state": "AZ",
522 "subscriber_employer_country": "USA",
523 "subscriber_employer_city": "Cooltown",
525 "date": "2018-10-15",
526 "subscriber_sex": "Female",
527 "accept_assignment": "TRUE",
533 - `provider` is the insurance company id
534 - `state` can be found by querying `resource=/api/list/state`
535 - `country` can be found by querying `resource=/api/list/country`
538 #### PUT /api/patient/:pid/insurance/:type
541 curl -X PUT 'http://localhost:8300/apis/api/patient/10/insurance/primary' -d \
545 "plan_name": "Some Plan",
546 "policy_number": "12345",
547 "group_number": "252412",
548 "subscriber_lname": "Tester",
549 "subscriber_mname": "Xi",
550 "subscriber_fname": "Foo",
551 "subscriber_relationship": "other",
552 "subscriber_ss": "234231234",
553 "subscriber_DOB": "2018-10-03",
554 "subscriber_street": "183 Cool St",
555 "subscriber_postal_code": "23418",
556 "subscriber_city": "Cooltown",
557 "subscriber_state": "AZ",
558 "subscriber_country": "USA",
559 "subscriber_phone": "234-598-2123",
560 "subscriber_employer": "Some Employer",
561 "subscriber_employer_street": "123 Heather Lane",
562 "subscriber_employer_postal_code": "23415",
563 "subscriber_employer_state": "AZ",
564 "subscriber_employer_country": "USA",
565 "subscriber_employer_city": "Cooltown",
567 "date": "2018-10-15",
568 "subscriber_sex": "Female",
569 "accept_assignment": "TRUE",
575 - `provider` is the insurance company id
576 - `state` can be found by querying `resource=/api/list/state`
577 - `country` can be found by querying `resource=/api/list/country`
579 #### GET /api/list/:list_name
582 curl -X GET 'http://localhost:8300/apis/api/list/medical_problem_issue_list'
585 #### GET /api/version
588 curl -X GET 'http://localhost:8300/apis/api/version'
591 #### GET /api/product
594 curl -X GET 'http://localhost:8300/apis/api/product'
597 #### GET /api/insurance_company
600 curl -X GET 'http://localhost:8300/apis/api/insurance_company'
603 #### GET /api/insurance_type
606 curl -X GET 'http://localhost:8300/apis/api/insurance_type'
609 #### POST /api/insurance_company
612 curl -X POST 'http://localhost:8300/apis/api/insurance_company' -d \
614 "name": "Cool Insurance Company",
617 "ins_type_code": "2",
618 "x12_receiver_id": null,
619 "x12_default_partner_id": null,
621 "line1": "123 Cool Lane",
622 "line2": "Suite 123",
630 Notes: `ins_type_code` can be found by inspecting the above route (/api/insurance_type).
632 #### PUT /api/insurance_company/:iid
635 curl -X PUT 'http://localhost:8300/apis/api/insurance_company/1' -d \
637 "name": "Super Insurance Company",
640 "ins_type_code": "2",
641 "x12_receiver_id": null,
642 "x12_default_partner_id": null,
644 "line1": "123 Cool Lane",
645 "line2": "Suite 123",
653 Notes: `ins_type_code` can be found by inspecting the above route (/api/insurance_type).
655 #### GET /api/appointment
658 curl -X GET 'http://localhost:8300/apis/api/appointment'
661 #### GET /api/appointment/:eid
664 curl -X GET 'http://localhost:8300/apis/api/appointment/1'
667 #### GET /api/patient/:pid/appointment
670 curl -X GET 'http://localhost:8300/apis/api/patient/1/appointment'
673 #### GET /api/patient/:pid/appointment/:eid
676 curl -X GET 'http://localhost:8300/apis/api/patient/1/appointment/1'
679 #### POST /api/patient/:pid/appointment
682 curl -X POST 'http://localhost:8300/apis/api/patient/1/appointment' -d \
686 "pc_title": "Office Visit",
687 "pc_duration": "900",
688 "pc_hometext": "Test",
689 "pc_apptstatus": "-",
690 "pc_eventDate": "2018-10-19",
691 "pc_startTime": "09:00",
693 "pc_billing_location": "10"
697 #### DELETE /api/patient/:pid/appointment/:eid
700 curl -X DELETE 'http://localhost:8300/apis/api/patient/1/appointment/1' -d \
703 #### GET /api/patient/:pid/document
706 curl -X GET 'http://localhost:8300/apis/api/patient/1/document&path=/eye_module/imaging-eye/drawings-eye'
709 Note: The `path` query string represents the OpenEMR documents paths with two exceptions:
711 - Spaces are represented with `_`
712 - All characters are lowercase
714 #### POST /api/patient/:pid/document
717 curl -X POST 'http://localhost:8300/apis/api/patient/1/document&path=/eye_module/imaging-eye/drawings-eye' \
718 -F document=@/home/someone/Desktop/drawing.jpg
721 Note: The `path` query string represents the OpenEMR documents paths with two exceptions:
723 - Spaces are represented with `_`
724 - All characters are lowercase
726 #### GET /api/patient/:pid/document/:did
729 curl -X GET 'http://localhost:8300/apis/api/patient/1/document/1'
732 #### POST /api/patient/:pid/message
735 curl -X POST 'http://localhost:8300/apis/api/patient/1/message' -d \
738 "groupname": "Default",
742 "message_status": "New"
747 - For `title`, use `resource=/api/list/note_type`
748 - For `message_type`, use `resource=/api/list/message_status`
750 #### PUT /api/patient/:pid/message/:mid
753 curl -X PUT 'http://localhost:8300/apis/api/patient/1/message/1' -d \
756 "groupname": "Default",
760 "message_status": "New"
765 - For `title`, use `resource=/api/list/note_type`
766 - For `message_type`, use `resource=/api/list/message_status`
768 #### DELETE /api/patient/:pid/message/:mid
771 curl -X DELETE 'http://localhost:8300/apis/api/patient/1/message/1'
776 - For business logic, make or use the services [here](https://github.com/openemr/openemr/tree/master/services)
777 - For controller logic, make or use the classes [here](https://github.com/openemr/openemr/tree/master/rest_controllers)
778 - For routing declarations, use the class [here](https://github.com/openemr/openemr/blob/master/_rest_routes.inc.php).
781 ### Project Management
783 - TODO(team): Consider using Symfony's router
784 - TODO(sherwin): Encounter POST
785 - TODO(matthew): Fix authorization piece
786 - TODO(?): Support CouchDB with document API
787 - TODO(?): Prevent `ListService` from using `enddate` of `0000-00-00` by default
788 - TODO(?): API for fee sheets
789 - TODO(?): API for pharmacies
790 - TODO(?): API for immunizations
791 - TODO(?): API for prescriptions
792 - TODO(?): Drug search API
793 - TODO(?): API for onotes
796 ### What is that dog drawing?
798 That is Peppy, an old OpenEMR mascot. Long live Peppy!
803 [GNU GPL](../LICENSE)