API_README.md

   1 # OpenEMR REST API Documentation
   2
   3 ## Overview
   4
   5 Easy-to-use JSON-based REST API for OpenEMR. All code is done in classes and separate from the view to help with codebase modernization efforts. FHIR is also supported, see FHIR API documentation [here](FHIR_README.md)
   6
   7 ## Implementation
   8
   9 REST API endpoints are defined in the [primary routes file](_rest_routes.inc.php). The routes file maps an external, addressable
  10 endpoint to the OpenEMR controller which handles the request, and also handles the JSON data conversions.
  11
  12 ```php
  13 "POST /api/patient" => function () {
  14     RestConfig::authorization_check("patients", "demo");
  15     $data = (array)(json_decode(file_get_contents("php://input")));
  16     return (new PatientRestController())->post($data);
  17 }
  18 ```
  19
  20 At a high level, the request processing flow consists of the following steps:
  21
  22 ```
  23 JSON Request -> Controller Component -> Validation -> Service Component -> Database
  24 ```
  25
  26 The logical response flow begins with the database result:
  27
  28 ```
  29 Database Result -> Service Component -> Controller Component -> RequestControllerHelper -> JSON Response
  30 ```
  31
  32 The [RequestControllerHelper class](./src/RestControllers/RestControllerHelper.php) evaluates the Service Component's
  33 result and maps it to a http response code and response payload. Existing APIs should be updated to utilize the
  34 `handleProcessingResult` method as it supports the [Validator](./src/Validators/BaseValidator.php) components.
  35
  36 The [PatientRestController](./src/RestControllers/PatientRestController.php) may be used as a reference to see how APIs are
  37 integrated with `RequestControllerHelper::handleProcessingResult` and the `Validator` components.
  38
  39 Finally, APIs which are integrated with the new `handleProcessingResult` method utilize a common response format.
  40
  41 ```json
  42 {
  43     "validationErrors": [],
  44     "internalErrors": [],
  45     "data": < data payload >
  46 }
  47 ```
  48
  49 -   `validationErrors` contain "client based" data validation errors
  50 -   `internalErrors` contain server related errors
  51 -   `data` is the response payload, represented as an object/`{}` for single results or an array/`[]` for multiple results
  52
  53 ### Sections
  54
  55 -   [Standard API Endpoints](API_README.md#api-endpoints)
  56     -   [Facility API](API_README.md#post-apifacility)
  57     -   [Provider API](API_README.md#get-apiprovider)
  58     -   [Patient API](API_README.md#post-apipatient)
  59     -   [Insurance API](API_README.md#get-apipatientpidinsurance)
  60     -   [Appointment API](API_README.md#get-apiappointment)
  61     -   [Document API](API_README.md#get-apipatientpiddocument)
  62     -   [Message API](API_README.md#post-apipatientpidmessage)
  63 -   [Portal API Endpoints](API_README.md#portal-Endpoints)
  64     -   [Patient API](API_README.md#get-portalpatient)
  65 -   [FHIR API Endpoints](FHIR_README.md#fhir-endpoints)
  66     -   [FHIR Patient API](FHIR_README.md#get-fhirpatient)
  67     -   [FHIR Encounter API](FHIR_README.md#get-fhirencounter)
  68     -   [FHIR Organization API](FHIR_README.md#get-fhirorganization)
  69     -   [FHIR AllergyIntolerance API](FHIR_README.md#get-fhirallergyintolerance)
  70     -   [FHIR Observation API](FHIR_README.md#get-fhirobservation)
  71     -   [FHIR QuestionnaireResponse API](FHIR_README.md#get-fhirquestionnaireresponse)
  72     -   [FHIR Immunization API](FHIR_README.md#get-fhirimmunization)
  73     -   [FHIR Condition API](FHIR_README.md#get-fhircondition)
  74     -   [FHIR Procedure API](FHIR_README.md#get-fhirprocedure)
  75     -   [FHIR MedicationStatement API](FHIR_README.md#get-fhirmedicationstatement)
  76     -   [FHIR Medication API](FHIR_README.md#get-fhirmedication)
  77 -   [Portal FHIR API Endpoints](FHIR_README.md#portalfhir-endpoints)
  78     -   [Patient API](FHIR_README.md#get-portalfhirpatient)
  79 -   [Dev notes](API_README.md#dev-notes)
  80 -   [Todos](API_README.md#project-management)
  81
  82 ### Prerequisite
  83
  84 Enable the Standard API service (/api/ endpoints) in OpenEMR menu: Administration->Globals->Connectors->"Enable OpenEMR Standard REST API"
  85 Enable the Patient Portal API service (/portal/ endpoints) in OpenEMR menu: Administration->Globals->Connectors->"Enable OpenEMR Patient Portal REST API"
  86
  87 ### Using API Internally
  88
  89 There are several ways to make API calls from an authorized session and maintain security:
  90
  91 -   See the script at tests/api/InternalApiTest.php for examples of internal API use cases.
  92
  93 ### /api/ Endpoints
  94
  95 OpenEMR standard endpoints Use `http://localhost:8300/apis/api as base URI.`
  96
  97 _Example:_ `http://localhost:8300/apis/api/patient` returns a resource of all Patients.
  98
  99 #### POST /api/auth
 100
 101 The OpenEMR API utilizes the OAuth2 password credential flow for authentication. To obtain an API token, submit your login credentials and requested scope. The scope must match a site that has been setup in OpenEMR, in the /sites/ directory. If additional sites have not been created, set the scope
 102 to 'default'.
 103
 104 Request:
 105
 106 ```sh
 107 curl -X POST -H 'Content-Type: application/json' 'http://localhost:8300/apis/api/auth' \
 108 -d '{
 109     "grant_type":"password",
 110     "username": "ServiceUser",
 111     "password": "password",
 112     "scope":"site id"
 113 }'
 114 ```
 115
 116 Response:
 117
 118 ```json
 119 {
 120     "token_type": "Bearer",
 121     "access_token": "eyJ0b2tlbiI6IjAwNmZ4TWpsNWhsZmNPelZicXBEdEZVUlNPQUY5KzdzR1Jjejc4WGZyeGFjUjY2QlhaaEs4eThkU3cxbTd5VXFBeTVyeEZpck9mVzBQNWc5dUlidERLZ0trUElCME5wRDVtTVk5bE9WaE5DTHF5RnRnT0Q0OHVuaHRvbXZ6OTEyNmZGUmVPUllSYVJORGoyZTkzTDA5OWZSb0ZRVGViTUtWUFd4ZW5cL1piSzhIWFpJZUxsV3VNcUdjQXR5dmlLQXRXNDAiLCJzaXRlX2lkIjoiZGVmYXVsdCIsImFwaSI6Im9lbXIifQ==",
 122     "expires_in": "3600",
 123     "user_data": {
 124         "user_id": "1"
 125     }
 126 }
 127 ```
 128
 129 The Bearer token is required for each OpenEMR API request, and is conveyed using an Authorization header.
 130
 131 Request:
 132
 133 ```sh
 134 curl -X GET 'http://localhost:8300/apis/api/patient/1/medical_problem' \
 135   -H 'Authorization: Bearer eyJ0b2tlbiI6IjAwNmZ4TWpsNWhsZmNPelZicXBEdEZVUlNPQUY5KzdzR1Jjejc4WGZyeGFjUjY2QlhaaEs4eThkU3cxbTd5VXFBeTVyeEZpck9mVzBQNWc5dUlidERLZ0trUElCME5wRDVtTVk5bE9WaE5DTHF5RnRnT0Q0OHVuaHRvbXZ6OTEyNmZGUmVPUllSYVJORGoyZTkzTDA5OWZSb0ZRVGViTUtWUFd4ZW5cL1piSzhIWFpJZUxsV3VNcUdjQXR5dmlLQXRXNDAiLCJzaXRlX2lkIjoiZGVmYXVsdCIsImFwaSI6Im9lbXIifQ=='
 136 ```
 137
 138 #### POST /api/facility
 139
 140 Request:
 141
 142 ```sh
 143 curl -X POST 'http://localhost:8300/apis/api/facility' -d \
 144 '{
 145     "name": "Aquaria",
 146     "phone": "808-606-3030",
 147     "fax": "808-606-3031",
 148     "street": "1337 Bit Shifter Ln",
 149     "city": "San Lorenzo",
 150     "state": "ZZ",
 151     "postal_code": "54321",
 152     "email": "foo@bar.com",
 153     "service_location": "1",
 154     "billing_location": "1",
 155     "color": "#FF69B4"
 156 }'
 157 ```
 158
 159 #### PUT /api/facility/:fid
 160
 161 Request:
 162
 163 ```sh
 164 curl -X PUT 'http://localhost:8300/apis/api/facility/1' -d \
 165 '{
 166     "name": "Aquaria",
 167     "phone": "808-606-3030",
 168     "fax": "808-606-3031",
 169     "street": "1337 Bit Shifter Ln",
 170     "city": "San Lorenzo",
 171     "state": "AZ",
 172     "postal_code": "54321",
 173     "email": "foo@bar.com",
 174     "service_location": "1",
 175     "billing_location": "1",
 176     "color": "#FF69B4"
 177 }'
 178 ```
 179
 180 #### GET /api/facility
 181
 182 Request:
 183
 184 ```sh
 185 curl -X GET 'http://localhost:8300/apis/api/facility'
 186 ```
 187
 188 #### GET /api/facility/:fid
 189
 190 Request:
 191
 192 ```sh
 193 curl -X GET 'http://localhost:8300/apis/api/facility/1'
 194 ```
 195
 196 #### GET /api/provider
 197
 198 Request:
 199
 200 ```sh
 201 curl -X GET 'http://localhost:8300/apis/api/provider'
 202 ```
 203
 204 #### GET /api/provider/:prid
 205
 206 Request:
 207
 208 ```sh
 209 curl -X GET 'http://localhost:8300/apis/api/provider/1'
 210 ```
 211
 212 #### POST /api/patient
 213
 214 Request:
 215
 216 ```sh
 217 curl -X POST 'http://localhost:8300/apis/api/patient' -d \
 218 '{
 219     "title": "Mr",
 220     "fname": "Foo",
 221     "mname": "",
 222     "lname": "Bar",
 223     "street": "456 Tree Lane",
 224     "postal_code": "08642",
 225     "city": "FooTown",
 226     "state": "FL",
 227     "country_code": "US",
 228     "phone_contact": "123-456-7890",
 229     "DOB": "1992-02-02",
 230     "sex": "Male",
 231     "race": "",
 232     "ethnicity": ""
 233 }'
 234 ```
 235
 236 Response:
 237
 238 ```json
 239 {
 240     "validationErrors": [],
 241     "internalErrors": [],
 242     "data": {
 243         "pid": 1
 244     }
 245 }
 246 ```
 247
 248 #### PUT /api/patient/:puuid
 249
 250 Request:
 251
 252 ```sh
 253 curl -X PUT 'http://localhost:8300/apis/api/patient/90a8923c-0b1c-4d0a-9981-994b143381a7' -d \
 254 '{
 255     "title": "Mr",
 256     "fname": "Baz",
 257     "mname": "",
 258     "lname": "Bop",
 259     "street": "456 Tree Lane",
 260     "postal_code": "08642",
 261     "city": "FooTown",
 262     "state": "FL",
 263     "country_code": "US",
 264     "phone_contact": "123-456-7890",
 265     "DOB": "1992-02-03",
 266     "sex": "Male",
 267     "race": "",
 268     "ethnicity": ""
 269 }'
 270 ```
 271
 272 Response:
 273
 274 ```json
 275 {
 276     "validationErrors": [],
 277     "internalErrors": [],
 278     "data": {
 279         "id": "193",
 280         "pid": "1",
 281         "pubpid": "",
 282         "title": "Mr",
 283         "fname": "Baz",
 284         "mname": "",
 285         "lname": "Bop",
 286         "ss": "",
 287         "street": "456 Tree Lane",
 288         "postal_code": "08642",
 289         "city": "FooTown",
 290         "state": "FL",
 291         "county": "",
 292         "country_code": "US",
 293         "drivers_license": "",
 294         "contact_relationship": "",
 295         "phone_contact": "123-456-7890",
 296         "phone_home": "",
 297         "phone_biz": "",
 298         "phone_cell": "",
 299         "email": "",
 300         "DOB": "1992-02-03",
 301         "sex": "Male",
 302         "race": "",
 303         "ethnicity": "",
 304         "status": ""
 305     }
 306 }
 307 ```
 308
 309 #### GET /api/patient
 310
 311 Request:
 312
 313 ```sh
 314 curl -X GET 'http://localhost:8300/apis/api/patient'
 315 ```
 316
 317 Response:
 318
 319 ```json
 320 {
 321     "validationErrors": [],
 322     "internalErrors": [],
 323     "data": [{ patientRecord }, { patientRecord }, etc]
 324 }
 325 ```
 326
 327 Request:
 328
 329 ```sh
 330 curl -X GET 'http://localhost:8300/apis/api/patient&fname=...&lname=...&dob=...'
 331 ```
 332
 333 Response:
 334
 335 ```json
 336 {
 337     "validationErrors": [],
 338     "internalErrors": [],
 339     "data": [{ patientRecord }, { patientRecord }, etc]
 340 }
 341 ```
 342
 343 #### GET /api/patient/:puuid
 344
 345 Request:
 346
 347 ```sh
 348 curl -X GET 'http://localhost:8300/apis/api/patient/90a8923c-0b1c-4d0a-9981-994b143381a7'
 349 ```
 350
 351 Response:
 352
 353 ```json
 354 {
 355     "validationErrors": [],
 356     "internalErrors": [],
 357     "data": {
 358         "id": "193",
 359         "pid": "1",
 360         "pubpid": "",
 361         "title": "Mr",
 362         "fname": "Baz",
 363         "mname": "",
 364         "lname": "Bop",
 365         "ss": "",
 366         "street": "456 Tree Lane",
 367         "postal_code": "08642",
 368         "city": "FooTown",
 369         "state": "FL",
 370         "county": "",
 371         "country_code": "US",
 372         "drivers_license": "",
 373         "contact_relationship": "",
 374         "phone_contact": "123-456-7890",
 375         "phone_home": "",
 376         "phone_biz": "",
 377         "phone_cell": "",
 378         "email": "",
 379         "DOB": "1992-02-03",
 380         "sex": "Male",
 381         "race": "",
 382         "ethnicity": "",
 383         "status": ""
 384     }
 385 }
 386 ```
 387
 388 #### POST /api/patient/:pid/encounter
 389
 390 Request:
 391
 392 ```sh
 393 curl -X POST 'http://localhost:8300/apis/api/patient/90a8923c-0b1c-4d0a-9981-994b143381a7/encounter' -d \
 394 '{
 395     "date":"2020-11-10",
 396     "onset_date": "",
 397     "reason": "Pregnancy Test",
 398     "facility": "Owerri General Hospital",
 399     "pc_catid": "5",
 400     "facility_id": "3",
 401     "billing_facility": "3",
 402     "sensitivity": "normal",
 403     "referral_source": "",
 404     "pos_code": "0",
 405     "external_id": "",
 406     "provider_id": "1",
 407     "class_code" : "AMB"
 408 }'
 409 ```
 410
 411 Response:
 412
 413 ```json
 414 {
 415     "validationErrors": [],
 416     "internalErrors": [],
 417     "data": {
 418         "encounter": 1,
 419         "uuid": "90c196f2-51cc-4655-8858-3a80aebff3ef"
 420     }
 421 }
 422 ```
 423
 424 #### PUT /api/patient/:pid/encounter/:eid
 425
 426 Request:
 427
 428 ```sh
 429 curl -X POST 'http://localhost:8300/apis/api/patient/90a8923c-0b1c-4d0a-9981-994b143381a7/encounter/90c196f2-51cc-4655-8858-3a80aebff3ef' -d \
 430 '{
 431     "date":"2019-09-14",
 432     "onset_date": "2019-04-20 00:00:00",
 433     "reason": "Pregnancy Test",
 434     "pc_catid": "5",
 435     "facility_id": "3",
 436     "billing_facility": "3",
 437     "sensitivity": "normal",
 438     "referral_source": "",
 439     "pos_code": "0"
 440 }'
 441 ```
 442
 443 Response:
 444
 445 ```json
 446 {
 447     "validationErrors": [],
 448     "internalErrors": [],
 449     "data": {
 450         "id": "1",
 451         "uuid": "90c196f2-51cc-4655-8858-3a80aebff3ef",
 452         "date": "2019-09-14 00:00:00",
 453         "reason": "Pregnancy Test",
 454         "facility": "Owerri General Hospital",
 455         "facility_id": "3",
 456         "pid": "1",
 457         "onset_date": "2019-04-20 00:00:00",
 458         "sensitivity": "normal",
 459         "billing_note": null,
 460         "pc_catid": "5",
 461         "last_level_billed": "0",
 462         "last_level_closed": "0",
 463         "last_stmt_date": null,
 464         "stmt_count": "0",
 465         "provider_id": "1",
 466         "supervisor_id": "0",
 467         "invoice_refno": "",
 468         "referral_source": "",
 469         "billing_facility": "3",
 470         "external_id": "",
 471         "pos_code": "0",
 472         "class_code": "AMB",
 473         "class_title": "ambulatory",
 474         "pc_catname": "Office Visit",
 475         "billing_facility_name": "Owerri General Hospital"
 476     }
 477 }
 478 ```
 479
 480 #### GET /api/patient/:pid/encounter
 481
 482 Request:
 483
 484 ```sh
 485 curl -X GET 'http://localhost:8300/apis/api/patient/90a8923c-0b1c-4d0a-9981-994b143381a7/encounter'
 486 ```
 487
 488 Response:
 489
 490 ```json
 491 {
 492     "validationErrors": [],
 493     "internalErrors": [],
 494     "data": [{ encounterRecord }, { encounterRecord }, etc]
 495 }
 496 ```
 497
 498 #### GET /api/patient/:pid/encounter/:eid
 499
 500 Request:
 501
 502 ```sh
 503 curl -X GET 'http://localhost:8300/apis/api/patient/90a8923c-0b1c-4d0a-9981-994b143381a7/encounter/90c196f2-51cc-4655-8858-3a80aebff3ef'
 504 ```
 505
 506 Response:
 507
 508 ```json
 509 {
 510     "validationErrors": [],
 511     "internalErrors": [],
 512     "data": {
 513         "id": "1",
 514         "uuid": "90c196f2-51cc-4655-8858-3a80aebff3ef",
 515         "date": "2019-09-14 00:00:00",
 516         "reason": "Pregnancy Test",
 517         "facility": "Owerri General Hospital",
 518         "facility_id": "3",
 519         "pid": "1",
 520         "onset_date": "2019-04-20 00:00:00",
 521         "sensitivity": "normal",
 522         "billing_note": null,
 523         "pc_catid": "5",
 524         "last_level_billed": "0",
 525         "last_level_closed": "0",
 526         "last_stmt_date": null,
 527         "stmt_count": "0",
 528         "provider_id": "1",
 529         "supervisor_id": "0",
 530         "invoice_refno": "",
 531         "referral_source": "",
 532         "billing_facility": "3",
 533         "external_id": "",
 534         "pos_code": "0",
 535         "class_code": "AMB",
 536         "class_title": "ambulatory",
 537         "pc_catname": "Office Visit",
 538         "billing_facility_name": "Owerri General Hospital"
 539     }
 540 }
 541 ```
 542
 543 #### POST /api/patient/:pid/encounter/:eid/vital
 544
 545 Request:
 546
 547 ```sh
 548 curl -X POST 'http://localhost:8300/apis/api/patient/1/encounter/1/vital' -d \
 549 '{
 550     "bps": "130",
 551     "bpd": "80",
 552     "weight": "220",
 553     "height": "70",
 554     "temperature": "98",
 555     "temp_method": "Oral",
 556     "pulse": "60",
 557     "respiration": "20",
 558     "note": "...",
 559     "waist_circ": "37",
 560     "head_circ": "22.2",
 561     "oxygen_saturation": "80"
 562 }'
 563 ```
 564
 565 #### PUT /api/patient/:pid/encounter/:eid/vital/:vid
 566
 567 Request:
 568
 569 ```sh
 570 curl -X PUT 'http://localhost:8300/apis/api/patient/1/encounter/1/vital/1' -d \
 571 '{
 572     "bps": "140",
 573     "bpd": "80",
 574     "weight": "220",
 575     "height": "70",
 576     "temperature": "98",
 577     "temp_method": "Oral",
 578     "pulse": "60",
 579     "respiration": "20",
 580     "note": "...",
 581     "waist_circ": "37",
 582     "head_circ": "22.2",
 583     "oxygen_saturation": "80"
 584 }'
 585 ```
 586
 587 #### GET /api/patient/:pid/encounter/:eid/vital
 588
 589 Request:
 590
 591 ```sh
 592 curl -X GET 'http://localhost:8300/apis/api/patient/1/encounter/1/vital'
 593 ```
 594
 595 #### GET /api/patient/:pid/encounter/:eid/vital/:vid
 596
 597 Request:
 598
 599 ```sh
 600 curl -X GET 'http://localhost:8300/apis/api/patient/1/encounter/1/vital/1'
 601 ```
 602
 603 #### POST /api/patient/:pid/encounter/:eid/soap_note
 604
 605 Request:
 606
 607 ```sh
 608 curl -X POST 'http://localhost:8300/apis/api/patient/1/encounter/1/soap_note' -d \
 609 '{
 610     "subjective": "...",
 611     "objective": "...",
 612     "assessment": "...",
 613     "plan": "..."
 614 }'
 615 ```
 616
 617 #### PUT /api/patient/:pid/encounter/:eid/soap_note/:sid
 618
 619 Request:
 620
 621 ```sh
 622 curl -X PUT 'http://localhost:8300/apis/api/patient/1/encounter/1/soap_note/1' -d \
 623 '{
 624     "subjective": "...",
 625     "objective": "...",
 626     "assessment": "...",
 627     "plan": "..."
 628 }'
 629 ```
 630
 631 #### GET /api/patient/:pid/encounter/:eid/soap_note
 632
 633 Request:
 634
 635 ```sh
 636 curl -X GET 'http://localhost:8300/apis/api/patient/1/encounter/1/soap_note'
 637 ```
 638
 639 #### GET /api/patient/:pid/encounter/:eid/soap_note/:sid
 640
 641 Request:
 642
 643 ```sh
 644 curl -X GET 'http://localhost:8300/apis/api/patient/1/encounter/1/soap_note/1'
 645 ```
 646
 647 #### POST /api/patient/:pid/medical_problem
 648
 649 Request:
 650
 651 ```sh
 652 curl -X POST 'http://localhost:8300/apis/api/patient/1/medical_problem' -d \
 653 '{
 654     "title": "Dermatochalasis",
 655     "begdate": "2010-04-13",
 656     "enddate": null,
 657     "diagnosis": "ICD10:H02.839"
 658 }'
 659 ```
 660
 661 #### PUT /api/patient/:pid/medical_problem/:mid
 662
 663 Request:
 664
 665 ```sh
 666 curl -X PUT 'http://localhost:8300/apis/api/patient/1/medical_problem/1' -d \
 667 '{
 668     "title": "Dermatochalasis",
 669     "begdate": "2010-04-13",
 670     "enddate": "2018-03-12",
 671     "diagnosis": "ICD10:H02.839"
 672 }'
 673 ```
 674
 675 #### GET /api/patient/:pid/medical_problem
 676
 677 Request:
 678
 679 ```sh
 680 curl -X GET 'http://localhost:8300/apis/api/patient/1/medical_problem'
 681 ```
 682
 683 #### GET /api/patient/:pid/medical_problem/:mid
 684
 685 Request:
 686
 687 ```sh
 688 curl -X GET 'http://localhost:8300/apis/api/patient/1/medical_problem/1'
 689 ```
 690
 691 #### DELETE /api/patient/:pid/medical_problem/:mid
 692
 693 Request:
 694
 695 ```sh
 696 curl -X DELETE 'http://localhost:8300/apis/api/patient/1/medical_problem/1'
 697 ```
 698
 699 #### POST /api/patient/:pid/allergy
 700
 701 Request:
 702
 703 ```sh
 704 curl -X POST 'http://localhost:8300/apis/api/patient/1/allergy' -d \
 705 '{
 706     "title": "Iodine",
 707     "begdate": "2010-10-13",
 708     "enddate": null
 709 }'
 710 ```
 711
 712 #### PUT /api/patient/:pid/allergy/:aid
 713
 714 Request:
 715
 716 ```sh
 717 curl -X PUT 'http://localhost:8300/apis/api/patient/1/allergy/1' -d \
 718 '{
 719     "title": "Iodine",
 720     "begdate": "2012-10-13",
 721     "enddate": null
 722 }'
 723 ```
 724
 725 #### GET /api/patient/:pid/allergy
 726
 727 Request:
 728
 729 ```sh
 730 curl -X GET 'http://localhost:8300/apis/api/patient/1/allergy'
 731 ```
 732
 733 #### GET /api/patient/:pid/allergy/:aid
 734
 735 Request:
 736
 737 ```sh
 738 curl -X GET 'http://localhost:8300/apis/api/patient/1/allergy/1'
 739 ```
 740
 741 #### DELETE /api/patient/:pid/allergy/:aid
 742
 743 Request:
 744
 745 ```sh
 746 curl -X DELETE 'http://localhost:8300/apis/api/patient/1/allergy/1'
 747 ```
 748
 749 #### POST /api/patient/:pid/medication
 750
 751 Request:
 752
 753 ```sh
 754 curl -X POST 'http://localhost:8300/apis/api/patient/1/medication' -d \
 755 '{
 756     "title": "Norvasc",
 757     "begdate": "2013-10-13",
 758     "enddate": null
 759 }'
 760 ```
 761
 762 #### PUT /api/patient/:pid/medication/:mid
 763
 764 Request:
 765
 766 ```sh
 767 curl -X PUT 'http://localhost:8300/apis/api/patient/1/medication/1' -d \
 768 '{
 769     "title": "Norvasc",
 770     "begdate": "2013-04-13",
 771     "enddate": null
 772 }'
 773 ```
 774
 775 #### GET /api/patient/:pid/medication
 776
 777 Request:
 778
 779 ```sh
 780 curl -X GET 'http://localhost:8300/apis/api/patient/1/medication'
 781 ```
 782
 783 #### GET /api/patient/:pid/medication/:mid
 784
 785 Request:
 786
 787 ```sh
 788 curl -X GET 'http://localhost:8300/apis/api/patient/1/medication/1'
 789 ```
 790
 791 #### DELETE /api/patient/:pid/medication/:mid
 792
 793 Request:
 794
 795 ```sh
 796 curl -X DELETE 'http://localhost:8300/apis/api/patient/1/medication/1'
 797 ```
 798
 799 #### POST /api/patient/:pid/surgery
 800
 801 Request:
 802
 803 ```sh
 804 curl -X POST 'http://localhost:8300/apis/api/patient/1/surgery' -d \
 805 '{
 806     "title": "Blepharoplasty",
 807     "begdate": "2013-10-13",
 808     "enddate": null,
 809     "diagnosis": "CPT4:15823-50"
 810 }'
 811 ```
 812
 813 #### PUT /api/patient/:pid/surgery/:sid
 814
 815 Request:
 816
 817 ```sh
 818 curl -X PUT 'http://localhost:8300/apis/api/patient/1/surgery/1' -d \
 819 '{
 820     "title": "Blepharoplasty",
 821     "begdate": "2013-10-14",
 822     "enddate": null,
 823     "diagnosis": "CPT4:15823-50"
 824 }'
 825 ```
 826
 827 #### GET /api/patient/:pid/surgery
 828
 829 Request:
 830
 831 ```sh
 832 curl -X GET 'http://localhost:8300/apis/api/patient/1/surgery'
 833 ```
 834
 835 #### GET /api/patient/:pid/surgery/:sid
 836
 837 Request:
 838
 839 ```sh
 840 curl -X GET 'http://localhost:8300/apis/api/patient/1/surgery/1'
 841 ```
 842
 843 #### DELETE /api/patient/:pid/surgery/:sid
 844
 845 Request:
 846
 847 ```sh
 848 curl -X DELETE 'http://localhost:8300/apis/api/patient/1/surgery/1'
 849 ```
 850
 851 #### POST /api/patient/:pid/dental_issue
 852
 853 Request:
 854
 855 ```sh
 856 curl -X POST 'http://localhost:8300/apis/api/patient/1/dental_issue' -d \
 857 '{
 858     "title": "Halitosis",
 859     "begdate": "2015-03-17",
 860     "enddate": null
 861 }'
 862 ```
 863
 864 #### PUT /api/patient/:pid/dental_issue/:did
 865
 866 Request:
 867
 868 ```sh
 869 curl -X PUT 'http://localhost:8300/apis/api/patient/1/dental_issue/1' -d \
 870 '{
 871     "title": "Halitosis",
 872     "begdate": "2015-03-17",
 873     "enddate": "2018-03-20"
 874 }'
 875 ```
 876
 877 #### GET /api/patient/:pid/dental_issue
 878
 879 Request:
 880
 881 ```sh
 882 curl -X GET 'http://localhost:8300/apis/api/patient/1/dental_issue'
 883 ```
 884
 885 #### GET /api/patient/:pid/dental_issue/:did
 886
 887 Request:
 888
 889 ```sh
 890 curl -X GET 'http://localhost:8300/apis/api/patient/1/dental_issue/1'
 891 ```
 892
 893 #### DELETE /api/patient/:pid/dental_issue/:did
 894
 895 Request:
 896
 897 ```sh
 898 curl -X DELETE 'http://localhost:8300/apis/api/patient/1/dental_issue/1'
 899 ```
 900
 901 #### GET /api/patient/:pid/insurance
 902
 903 Request:
 904
 905 ```sh
 906 curl -X GET 'http://localhost:8300/apis/api/patient/1/insurance'
 907 ```
 908
 909 #### GET /api/patient/:pid/insurance/:type
 910
 911 Request:
 912
 913 ```sh
 914 curl -X GET 'http://localhost:8300/apis/api/patient/1/insurance/secondary'
 915 ```
 916
 917 #### POST /api/patient/:pid/insurance/:type
 918
 919 Request:
 920
 921 ```sh
 922 curl -X POST 'http://localhost:8300/apis/api/patient/10/insurance/primary' -d \
 923 '{
 924     "type": "primary",
 925     "provider": "33",
 926     "plan_name": "Some Plan",
 927     "policy_number": "12345",
 928     "group_number": "252412",
 929     "subscriber_lname": "Tester",
 930     "subscriber_mname": "Xi",
 931     "subscriber_fname": "Foo",
 932     "subscriber_relationship": "other",
 933     "subscriber_ss": "234231234",
 934     "subscriber_DOB": "2018-10-03",
 935     "subscriber_street": "183 Cool St",
 936     "subscriber_postal_code": "23418",
 937     "subscriber_city": "Cooltown",
 938     "subscriber_state": "AZ",
 939     "subscriber_country": "USA",
 940     "subscriber_phone": "234-598-2123",
 941     "subscriber_employer": "Some Employer",
 942     "subscriber_employer_street": "123 Heather Lane",
 943     "subscriber_employer_postal_code": "23415",
 944     "subscriber_employer_state": "AZ",
 945     "subscriber_employer_country": "USA",
 946     "subscriber_employer_city": "Cooltown",
 947     "copay": "35",
 948     "date": "2018-10-15",
 949     "subscriber_sex": "Female",
 950     "accept_assignment": "TRUE",
 951     "policy_type": "a"
 952 }'
 953 ```
 954
 955 Notes:
 956
 957 -   `provider` is the insurance company id
 958 -   `state` can be found by querying `resource=/api/list/state`
 959 -   `country` can be found by querying `resource=/api/list/country`
 960
 961 #### PUT /api/patient/:pid/insurance/:type
 962
 963 Request:
 964
 965 ```sh
 966 curl -X PUT 'http://localhost:8300/apis/api/patient/10/insurance/primary' -d \
 967 '{
 968     "type": "primary",
 969     "provider": "33",
 970     "plan_name": "Some Plan",
 971     "policy_number": "12345",
 972     "group_number": "252412",
 973     "subscriber_lname": "Tester",
 974     "subscriber_mname": "Xi",
 975     "subscriber_fname": "Foo",
 976     "subscriber_relationship": "other",
 977     "subscriber_ss": "234231234",
 978     "subscriber_DOB": "2018-10-03",
 979     "subscriber_street": "183 Cool St",
 980     "subscriber_postal_code": "23418",
 981     "subscriber_city": "Cooltown",
 982     "subscriber_state": "AZ",
 983     "subscriber_country": "USA",
 984     "subscriber_phone": "234-598-2123",
 985     "subscriber_employer": "Some Employer",
 986     "subscriber_employer_street": "123 Heather Lane",
 987     "subscriber_employer_postal_code": "23415",
 988     "subscriber_employer_state": "AZ",
 989     "subscriber_employer_country": "USA",
 990     "subscriber_employer_city": "Cooltown",
 991     "copay": "35",
 992     "date": "2018-10-15",
 993     "subscriber_sex": "Female",
 994     "accept_assignment": "TRUE",
 995     "policy_type": "a"
 996 }'
 997 ```
 998
 999 Notes:
1000
1001 -   `provider` is the insurance company id
1002 -   `state` can be found by querying `resource=/api/list/state`
1003 -   `country` can be found by querying `resource=/api/list/country`
1004
1005 #### GET /api/list/:list_name
1006
1007 Request:
1008
1009 ```sh
1010 curl -X GET 'http://localhost:8300/apis/api/list/medical_problem_issue_list'
1011 ```
1012
1013 #### GET /api/version
1014
1015 Request:
1016
1017 ```sh
1018 curl -X GET 'http://localhost:8300/apis/api/version'
1019 ```
1020
1021 #### GET /api/product
1022
1023 Request:
1024
1025 ```sh
1026 curl -X GET 'http://localhost:8300/apis/api/product'
1027 ```
1028
1029 #### GET /api/insurance_company
1030
1031 Request:
1032
1033 ```sh
1034 curl -X GET 'http://localhost:8300/apis/api/insurance_company'
1035 ```
1036
1037 #### GET /api/insurance_type
1038
1039 Request:
1040
1041 ```sh
1042 curl -X GET 'http://localhost:8300/apis/api/insurance_type'
1043 ```
1044
1045 #### POST /api/insurance_company
1046
1047 Request:
1048
1049 ```sh
1050 curl -X POST 'http://localhost:8300/apis/api/insurance_company' -d \
1051 '{
1052     "name": "Cool Insurance Company",
1053     "attn": null,
1054     "cms_id": null,
1055     "ins_type_code": "2",
1056     "x12_receiver_id": null,
1057     "x12_default_partner_id": null,
1058     "alt_cms_id": "",
1059     "line1": "123 Cool Lane",
1060     "line2": "Suite 123",
1061     "city": "Cooltown",
1062     "state": "CA",
1063     "zip": "12245",
1064     "country": "USA"
1065 }'
1066 ```
1067
1068 Notes: `ins_type_code` can be found by inspecting the above route (/api/insurance_type).
1069
1070 #### PUT /api/insurance_company/:iid
1071
1072 Request:
1073
1074 ```sh
1075 curl -X PUT 'http://localhost:8300/apis/api/insurance_company/1' -d \
1076 '{
1077     "name": "Super Insurance Company",
1078     "attn": null,
1079     "cms_id": null,
1080     "ins_type_code": "2",
1081     "x12_receiver_id": null,
1082     "x12_default_partner_id": null,
1083     "alt_cms_id": "",
1084     "line1": "123 Cool Lane",
1085     "line2": "Suite 123",
1086     "city": "Cooltown",
1087     "state": "CA",
1088     "zip": "12245",
1089     "country": "USA"
1090 }'
1091 ```
1092
1093 Notes: `ins_type_code` can be found by inspecting the above route (/api/insurance_type).
1094
1095 #### GET /api/appointment
1096
1097 Request:
1098
1099 ```sh
1100 curl -X GET 'http://localhost:8300/apis/api/appointment'
1101 ```
1102
1103 #### GET /api/appointment/:eid
1104
1105 Request:
1106
1107 ```sh
1108 curl -X GET 'http://localhost:8300/apis/api/appointment/1'
1109 ```
1110
1111 #### GET /api/patient/:pid/appointment
1112
1113 Request:
1114
1115 ```sh
1116 curl -X GET 'http://localhost:8300/apis/api/patient/1/appointment'
1117 ```
1118
1119 #### GET /api/patient/:pid/appointment/:eid
1120
1121 Request:
1122
1123 ```sh
1124 curl -X GET 'http://localhost:8300/apis/api/patient/1/appointment/1'
1125 ```
1126
1127 #### POST /api/patient/:pid/appointment
1128
1129 Request:
1130
1131 ```sh
1132 curl -X POST 'http://localhost:8300/apis/api/patient/1/appointment' -d \
1133 '{
1134     "pc_eid":"1",
1135     "pc_catid": "5",
1136     "pc_title": "Office Visit",
1137     "pc_duration": "900",
1138     "pc_hometext": "Test",
1139     "pc_apptstatus": "-",
1140     "pc_eventDate": "2018-10-19",
1141     "pc_startTime": "09:00",
1142     "pc_facility": "9",
1143     "pc_billing_location": "10"
1144 }'
1145 ```
1146
1147 #### DELETE /api/patient/:pid/appointment/:eid
1148
1149 Request:
1150
1151 ```sh
1152 curl -X DELETE 'http://localhost:8300/apis/api/patient/1/appointment/1' -d \
1153 ```
1154
1155 #### GET /api/patient/:pid/document
1156
1157 Request:
1158
1159 ```sh
1160 curl -X GET 'http://localhost:8300/apis/api/patient/1/document&path=/eye_module/imaging-eye/drawings-eye'
1161 ```
1162
1163 Note: The `path` query string represents the OpenEMR documents paths with two exceptions:
1164
1165 -   Spaces are represented with `_`
1166 -   All characters are lowercase
1167
1168 #### POST /api/patient/:pid/document
1169
1170 Request:
1171
1172 ```sh
1173 curl -X POST 'http://localhost:8300/apis/api/patient/1/document&path=/eye_module/imaging-eye/drawings-eye' \
1174  -F document=@/home/someone/Desktop/drawing.jpg
1175 ```
1176
1177 Note: The `path` query string represents the OpenEMR documents paths with two exceptions:
1178
1179 -   Spaces are represented with `_`
1180 -   All characters are lowercase
1181
1182 #### GET /api/patient/:pid/document/:did
1183
1184 Request:
1185
1186 ```sh
1187 curl -X GET 'http://localhost:8300/apis/api/patient/1/document/1'
1188 ```
1189
1190 #### POST /api/patient/:pid/message
1191
1192 Request:
1193
1194 ```sh
1195 curl -X POST 'http://localhost:8300/apis/api/patient/1/message' -d \
1196 '{
1197     "body": "Test 123",
1198     "groupname": "Default",
1199     "from": "admin",
1200     "to": "Matthew",
1201     "title": "Other",
1202     "message_status": "New"
1203 }'
1204 ```
1205
1206 Notes:
1207
1208 -   For `title`, use `resource=/api/list/note_type`
1209 -   For `message_type`, use `resource=/api/list/message_status`
1210
1211 #### PUT /api/patient/:pid/message/:mid
1212
1213 Request:
1214
1215 ```sh
1216 curl -X PUT 'http://localhost:8300/apis/api/patient/1/message/1' -d \
1217 '{
1218     "body": "Test 456",
1219     "groupname": "Default",
1220     "from": "Matthew",
1221     "to": "admin",
1222     "title": "Other",
1223     "message_status": "New"
1224 }'
1225 ```
1226
1227 Notes:
1228
1229 -   For `title`, use `resource=/api/list/note_type`
1230 -   For `message_type`, use `resource=/api/list/message_status`
1231
1232 #### DELETE /api/patient/:pid/message/:mid
1233
1234 Request:
1235
1236 ```sh
1237 curl -X DELETE 'http://localhost:8300/apis/api/patient/1/message/1'
1238 ```
1239
1240 ### /portal/ Endpoints
1241
1242 OpenEMR patient portal endpoints Use `http://localhost:8300/apis/portal as base URI.`
1243
1244 _Example:_ `http://localhost:8300/apis/portal/patient` returns a resource of the patient.
1245
1246 #### POST /portal/auth
1247
1248 The OpenEMR Patient Portal API utilizes the OAuth2 password credential flow for authentication. To obtain an API token, submit your login credentials and requested scope. The scope must match a site that has been setup in OpenEMR, in the /sites/ directory. If additional sites have not been created, set the scope
1249 to 'default'. If the patient portal is set to require email address on authenticate, then need to also include an `email` field in the request.
1250
1251 Request:
1252
1253 ```sh
1254 curl -X POST -H 'Content-Type: application/json' 'http://localhost:8300/apis/portal/auth' \
1255 -d '{
1256     "grant_type":"password",
1257     "username": "ServiceUser",
1258     "password": "password",
1259     "scope":"site id"
1260 }'
1261 ```
1262
1263 Response:
1264
1265 ```json
1266 {
1267     "token_type": "Bearer",
1268     "access_token": "eyJ0b2tlbiI6IjAwNmZ4TWpsNWhsZmNPelZicXBEdEZVUlNPQUY5KzdzR1Jjejc4WGZyeGFjUjY2QlhaaEs4eThkU3cxbTd5VXFBeTVyeEZpck9mVzBQNWc5dUlidERLZ0trUElCME5wRDVtTVk5bE9WaE5DTHF5RnRnT0Q0OHVuaHRvbXZ6OTEyNmZGUmVPUllSYVJORGoyZTkzTDA5OWZSb0ZRVGViTUtWUFd4ZW5cL1piSzhIWFpJZUxsV3VNcUdjQXR5dmlLQXRXNDAiLCJzaXRlX2lkIjoiZGVmYXVsdCIsImFwaSI6Im9lbXIifQ==",
1269     "expires_in": "3600",
1270     "user_data": {
1271         "user_id": "1"
1272     }
1273 }
1274 ```
1275
1276 The Bearer token is required for each OpenEMR Patient Portal API request, and is conveyed using an Authorization header.
1277
1278 Request:
1279
1280 ```sh
1281 curl -X GET 'http://localhost:8300/apis/portal/patient' \
1282   -H 'Authorization: Bearer eyJ0b2tlbiI6IjAwNmZ4TWpsNWhsZmNPelZicXBEdEZVUlNPQUY5KzdzR1Jjejc4WGZyeGFjUjY2QlhaaEs4eThkU3cxbTd5VXFBeTVyeEZpck9mVzBQNWc5dUlidERLZ0trUElCME5wRDVtTVk5bE9WaE5DTHF5RnRnT0Q0OHVuaHRvbXZ6OTEyNmZGUmVPUllSYVJORGoyZTkzTDA5OWZSb0ZRVGViTUtWUFd4ZW5cL1piSzhIWFpJZUxsV3VNcUdjQXR5dmlLQXRXNDAiLCJzaXRlX2lkIjoiZGVmYXVsdCIsImFwaSI6Im9lbXIifQ=='
1283 ```
1284
1285 #### GET /portal/patient
1286
1287 Request:
1288
1289 ```sh
1290 curl -X GET 'http://localhost:8300/apis/portal/patient'
1291 ```
1292
1293 Response:
1294
1295 ```json
1296 {
1297     "validationErrors": [],
1298     "internalErrors": [],
1299     "data": {
1300         "id": "193",
1301         "pid": "1",
1302         "pubpid": "",
1303         "title": "Mr",
1304         "fname": "Baz",
1305         "mname": "",
1306         "lname": "Bop",
1307         "ss": "",
1308         "street": "456 Tree Lane",
1309         "postal_code": "08642",
1310         "city": "FooTown",
1311         "state": "FL",
1312         "county": "",
1313         "country_code": "US",
1314         "drivers_license": "",
1315         "contact_relationship": "",
1316         "phone_contact": "123-456-7890",
1317         "phone_home": "",
1318         "phone_biz": "",
1319         "phone_cell": "",
1320         "email": "",
1321         "DOB": "1992-02-03",
1322         "sex": "Male",
1323         "race": "",
1324         "ethnicity": "",
1325         "status": ""
1326     }
1327 }
1328 ```
1329
1330 ### Dev Notes
1331
1332 -   For business logic, make or use the services [here](src/Services)
1333 -   For controller logic, make or use the classes [here](src/RestControllers)
1334 -   For routing declarations, use the class [here](_rest_routes.inc.php).
1335
1336 ### Project Management
1337
1338 #### General API
1339
1340 -   TODO(?): Prevent `ListService` from using `enddate` of `0000-00-00` by default
1341 -   TODO(?): API for fee sheets
1342 -   TODO(?): API for pharmacies
1343 -   TODO(?): API for immunizations
1344 -   TODO(?): API for prescriptions
1345 -   TODO(?): Drug search API
1346 -   TODO(?): API for onotes