Skip to content

Intake API (2024-12-10)

This API allows prescribers to send new prescriptions to Gifthealth to be filled. This API is intended only for use by prescribers and their software vendors.

In order to use this API, you must have an active agreement and/or attestation with Gifthealth. If you are interested in using this API, please contact Gifthealth.

Download OpenAPI description
openapi.json
openapi.yaml
Languages
Servers
https://{defaultHost}/intake_api/2024-12-10/

Events

Events allow you to receive updates about prescriptions as they move through the dispensing process.

When an important part of the dispensing process happens for a prescription, we publish an Event to the event feed if there is a Subscription record with matching demographic and prescription information (termed PrescriptionIdentity). You don't need to worry about creating subscriptions if you use our Intake API to send prescriptions to Gifthealth. We automatically create subscriptions for you.

The events endpoint is stateless, and assumes a single consumer. Events are not removed from the events endpoint when they are read.

Events currently remain visible in the events endpoint indefinitely, but this may change in the future. Design your system with the understanding that event availability has a limited timeframe.

You are responsible for tracking the iterator value as you process items from the queue. You can replay events as needed by resetting the iterator value to an earlier value.

Operations

Subscriptions

Events are published to your events endpoint when they match a Subscription. Subscriptions are created in one of two ways:

  1. Subscriptions are automatically created for prescriptions sent to Gifthealth through the Intake API.
  2. Subscriptions can be created for prescriptions received via fax or eRx using these endpoints. You are responsible for matching Gifthealth events to your own prescription records using the prescription's PrescriptionIdentity attributes.
Operations

Create a subscription

Request

Security
BearerAuth
Bodyapplication/json
subscriptionobjectrequired
subscription.​backfill_previous_eventsboolean or null

Setting this to true will publish any historic events for the prescription if the Subscription is created after the prescription already has events logged.

Default true
subscription.​prescription_identityobject(PrescriptionIdentityInput)required

Details are used to match your prescriptions to Gifthealth prescriptions. This information will be included and sent back to you for all events so you can match up the events to scripts in your system.

subscription.​prescription_identity.​patient_first_namestringrequired
subscription.​prescription_identity.​patient_last_namestringrequired
subscription.​prescription_identity.​patient_statestringrequired
subscription.​prescription_identity.​patient_dobstring(date)required
subscription.​prescription_identity.​erx_message_idstring or null

Unique identifier for the eRx sent to Gifthealth. Although optional, including this value allows for a more exact match between Gifthealth events and your prescriptions.

subscription.​prescription_identity.​prescriber_npistringrequired

10-digit National Provider Identifier (NPI) for the prescriber.

subscription.​prescription_identity.​written_datestring(date)required
subscription.​prescription_identity.​drug_ndcstringrequired
curl -i -X POST \
  'https://{defaulthost}/intake_api/2024-12-10/subscriptions' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "subscription": {
      "backfill_previous_events": true,
      "prescription_identity": {
        "erx_message_id": "123456789",
        "patient_first_name": "Todd",
        "patient_last_name": "Smith",
        "patient_state": "CA",
        "patient_dob": "1980-01-01",
        "prescriber_npi": "123231321",
        "written_date": "2025-02-25",
        "drug_ndc": "1234567890"
      }
    }
  }'

Responses

Created

Bodyapplication/json
subscriptionobject(Subscription)
Response
application/json
{
  "subscription": {
    "id": "ca101492-50c0-4c2f-9014-2dd926183f75",
    "api_version": "2024-12-10",
    "backfill_previous_events": true,
    "cancelled_at": null,
    "prescription_identity": { … }
  }
}

Get a subscription

Request

Security
BearerAuth
Path
idstringrequired
curl -i -X GET \
  'https://{defaulthost}/intake_api/2024-12-10/subscriptions/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Success

Bodyapplication/json
subscriptionobject(Subscription)
Response
application/json
{
  "subscription": {
    "id": "3d839a57-ce1d-47f3-b8f3-3ebfc74601c2",
    "api_version": "2024-12-10",
    "backfill_previous_events": true,
    "cancelled_at": null,
    "prescription_identity": { … }
  }
}

Cancel a subscription

Request

Security
BearerAuth
Path
idstringrequired
curl -i -X DELETE \
  'https://{defaulthost}/intake_api/2024-12-10/subscriptions/{id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Responses

Success

Bodyapplication/json
subscriptionobject(Subscription)
Response
application/json
{
  "subscription": {
    "id": "3d839a57-ce1d-47f3-b8f3-3ebfc74601c2",
    "api_version": "2024-12-10",
    "backfill_previous_events": true,
    "cancelled_at": "2024-12-09T00:00:00Z",
    "prescription_identity": { … }
  }
}

Prescriptions

Operations
© Gifthealth. All rights reserved.