Prescriptions and Medications

Hint models a patient's drug data as two different things, and partners have to pick the right one:

• A medication is a row on the patient's medication list. It has a lifecycle: it starts, it can be edited, it ends.
• A prescription is the event of a drug being prescribed. It is a point in time that lands on the patient's chart timeline and never changes.

Creating a prescription also creates the medication for you. That is the most important rule on this page: never write the same drug through both endpoints.

flowchart LR
    Rx["POST /prescriptions<br/>one call"] --> Int["ERX interaction<br/>chart timeline event"]
    Rx --> Med1["Medication<br/>on the medication list"]
    Direct["POST /medications<br/>one call"] --> Med2["Medication<br/>on the medication list"]
    classDef node fill:#ffffff,stroke:#dc2626,stroke-width:1px,color:#0f172a,font-size:12px
    class Rx,Int,Med1,Direct,Med2 node

Which endpoint should I call?

Create a prescription

POST /api/provider/patients/{patient_id}/prescriptions

One call creates two things: an ERX interaction on the chart timeline, and the medication row that goes with it.

{
  "prescription": {
    "rx_id": "your-rx-4482",
    "quantity": 30,
    "refills": 2,
    "event_timestamp": "2026-03-17T21:17:35Z",
    "integration_record_id": "your-rx-4482",
    "medication": {
      "product_name": "Lisinopril",
      "ndc": "00071015523",
      "strength": "10",
      "strength_uom": "mg",
      "dosage_form": "tablet",
      "sig_text": "Take 1 tablet by mouth daily",
      "start_date": "2018-03-12",
      "status": "Active"
    }
  }
}

The response is the interaction, with the medication it created nested inside it:

{
  "id": "inter-ab12C345DeF6GhI7",
  "type": "erx",
  "patient": { "id": "pat-ab12C345DeF6" },
  "created_at": "2026-03-17T21:17:35.607Z",
  "medication": {
    "id": "med-ab12C3",
    "product_name": "Lisinopril",
    "status": "Active",
    "start_date": "2018-03-12"
  },
  "integration_record_id": "your-rx-4482",
  "integration_sync_status": "enabled"
}

Things to know before you build against it:

• rx_id is required. It is your identifier for the prescription in your own system. It is distinct from integration_record_id, the general partner identifier that lets you address a record by your own id later; using the same value for both is fine.
• Write once. A prescription cannot be updated or deleted. You can read it back with Show Prescription.
• A user-scoped API key is required. A key that is not tied to a user is rejected.
• The nested medication object takes the same fields as Create Medication, minus the integration record fields. Those belong on the prescription, not on the drug.
• Store the returned medication.id, then link it. To make the medication addressable by your own identifier, follow the create with Update Medication setting integration_record_id - from then on, the medication endpoints accept your id anywhere they take an {id}.

Reading prescriptions back

To fetch one prescription you wrote, call Show Prescription - the response is the same shape as the create response, medication included.

To see prescription events on the chart timeline, call List All Interactions with type=erx:

GET /api/provider/interactions?type=erx&patient_id=pat-ab12C345DeF6

{
  "id": "inter-ab12C345DeF6GhI7",
  "type": "erx",
  "status": "active",
  "title": "Lisinopril 10mg tablet - Take 1 tablet by mouth daily",
  "body": "Lisinopril 10mg tablet - Take 1 tablet by mouth daily",
  "patient_id": "pat-ab12C345DeF6",
  "event_timestamp": "2026-03-17T21:17:35Z",
  "patient_access": false,
  "files": []
}

• Interaction rows are the same shape for every interaction type - no nested medication and no rx_id. Use Show Prescription for the full details.
• The filter returns every e-prescription on the chart, including ones the practice wrote in Hint itself - not only prescriptions your integration created.

Create and maintain medications

POST /api/provider/patients/{patient_id}/medications

Use this when you know the drug but not a prescribing event.

{
  "medication": {
    "product_name": "Metformin",
    "ndc": "00093104801",
    "strength": "500",
    "strength_uom": "mg",
    "dosage_form": "tablet",
    "sig_text": "Take 1 tablet by mouth twice daily with meals",
    "start_date": "2024-01-08",
    "status": "Active",
    "integration_record_id": "your-med-991"
  }
}

product_name is the only required field. status is Active or Complete, and defaults to Active.

The rest of the lifecycle:

End a course, do not delete it. Set status to Complete when a patient stops a drug - deletion removes the clinical history.

List All Patient Medications accepts limit, offset, and status (Active or Complete), and returns X-Count and X-Total-Count headers so you can page through the full list.

Avoiding duplicates

The medication list is where a bad integration becomes visible to the practice, so both paths rely on the same safeguards.

You can address a medication by your own identifier. Anywhere the medication endpoints take an {id} path parameter, you may pass the integration_record_id you sent.

Do not follow a prescription with a medication create. The prescription already produced the medication row. Posting the drug again gives the practice two entries for one prescription.

Field reference

Both endpoints describe a drug with the same vocabulary.

Prescription-only fields: rx_id (required), quantity, refills, and event_timestamp - the time the prescription was written, which is what places it correctly on the chart timeline.