Create a Patient

ENDPOINT: POST /v1/patients/invite

Partners can use this API to create a patient object in the RxWare system and/or initiate the patient’s participation in a patient journey flow.

Create patient results in the creation of a patient object on the RxWare database, signified by generating an RxWare system ID (patientId).

Once a user is created in the RxWare system, actions related to each program can be initiated.

For example, an SMS text message may be sent to the patient to invite them to sign a HIPAA consent form, complete a program enrollment, share shipment tracking information, or provide missing information to a hub.

Once a patient starts performing events, such as registering within the platform, a partner can receive status updates via the webhooks mechanism described in another section of this documentation.

In response to creating a patient object via the API, a partner will receive the patientId to be used for correlation to update patient statuses immediately after creation. It is important to note that a combination of patientId and supportProgramId, as well as the partner’s provided externalId (see table below) will serve as the basis for future actions after initial creation.

Default values:

  • requiredConsent – true
  • isCaregiver – false
FieldDescriptionFormat & LengthExampleRequired?
externalIdThe field that the partner uses in their system to identify the user.String 100 characterstest-user-external-user-id23✅ YES
phoneNumberMobile phone number of userall country codes and number length per E.164+12565551221✅ YES
supportProgramIdFixed program ID number used by both Partner and RxWare to properly identify the patient journey for the user.String 100 charactersb1mTa000dsa54rt✅ YES
firstNameFirst name of patient associated with the phoneNumberString, max 100 ASCII 128John✅ YES
lastNameLast name of patient associated with the phoneNumberString, max 100 ASCII 128Doe✅ YES
requiredConsentFlag for consent collection by RxWare :
False - Partner has consent and RxWare will not collect it
True - Partner does not have consent and RxWare will collect it.		BooleantrueNo
isCaregiverFlags the user as a Caregiver, not a patient
True - User is a caregiver
False - User is a patient

Note: If true, key values in additionalData with “Depends*” in required column become required		BooleanfalseNo
skipOnboardingFlag for completing enrollment
True - Partner has all the required enrollment information and no additional information is desired from the user. All enrollment screens will be skipped.
False - any required enrollment information missing will be collected during the RxWare enrollment process.
Any enrollment information present will be prefilled in the screen, or, if all information on a screen is present, the screen will be skipped.		BooleanfalseNo
additionalDataThis field contains the remainder of the enrollment data fields, obtained either through an RxWare experience or a Partner experience.

Format:
“additionalData”:[“key”:“Name of Field”, “value”: “{{Format Example}}]

key is part of the standard format for every enrollment item

Name of Field corresponds to the field in the enrollment process of the same name

value is part of the standard format for every enrollment item
{{Format Example}} as provided in this table		array“additionalData”:[“key”:”patient.first.name”,”John”:]No
key.patient.first.nameString, max 100,
ASCII 128, the same as firstName.		JohnNo
key.patient.last.nameString, max 100,
ASCII 128, the same as lastName.		DoeNo
key.patient.dobyyyy-mm-ddT00:00:00+00:001987-08-13T00:00:00+00:00No
key.patient.genderString, case insensitive, and only
"male" or "female". If unsure, don't specify this field at all.		"male"No
key.patient.phone.numberE.164 format+12565551212No
key.patient.contact.methodString, case insensitive"phone" or "email"No
key.patient.prefLanguageString, max 50,
ASCII 128		"english"No
key.patient.emailString, max 50,
ASCII 128		test@gmail.comNo
key.patient.callTimeCommunication preference as selected by user, if offered in UXString, case insensitive"morning" or "afternoon"No
key.caregiver.first.nameString, max 100,
ASCII 128		JaneDepends*
key.caregiver.last.nameString, max 100,
ASCII 128		DoeDepends*
key.caregiver.relationshipString, case insensitive"Parent"
"Legal Guardian"
"Power of Attorney"
"Spouse"		Depends*
key.caregiver.phone.numberMobile phone number of caregiverE.164 format+12567771313No
key.caregiver.emailEmail of caregiverString, max 50,
ASCII 128		test@gmail.comNo
key.address.streetString, max 50,
ASCII 128		512 Oak St.No
key.address.aptString, max 50,
ASCII 128		#15No
key.address.cityString, max 50,
ASCII 128		HunstvilleNo
key.address.stateString, max 2ALNo
key.address.zipString, max 535803No
key.insurance.carrierName of primary payer or insurance company of patientString, max 100,
ASCII 128		AetnaNo
key.insurance.memberIdPrimary Insurance Member IDString, max 100,
ASCII 128		5029375829No
key.insurance.groupNumPrimary Insurance Group NumberString, max 100,
ASCII 128		H3569No
key.insurance.cardnamePrimary Insurance Name of Patient As Printed on CardString, max 100,
ASCII 128		Jackie DoeNo
key.insurance.DobPrimary Insurance DOB for Cardholderyyyy-mm-ddT00:00:00+00:001987-08-13T00:00:00+00:00No
key.insurance.secondary.statusSecondary Insurance StatusString, max 100,
ASCII 128		"active" or "inactive"No
key.insurance.secondary.carrierProvide only if insurance.secondary.status is activeString, max 100,
ASCII 128		Blue CrossNo
key.insurance.secondary.memberidProvide only if insurance.secondary.status is activeString, max 100,
ASCII 128		78933678No
key.insurance.secondary.groupNumProvide only if insurance.secondary.status is activeString, max 100,
ASCII 128		K8967No
key.insurance.secondary.cardnameProvide only if insurance.secondary.status is activeString, max 100,
ASCII 128		Jackie DoeNo
key.insurance.secondary.cardDobProvide only if insurance.secondary.status is activeString, max 100,
ASCII 128		1987-08-13T00:00:00+00:00No

Standard HTTP Response Codes

StatusCodeMessageDescription
200N/A{
"data": {
"supportProgramId": "{{support_program_id}}",
"phoneNumber": "{{patient_phone_number}}",
"patientId": "{{patientId}}"
},
"status": 200
}		Patient successfully created in the RxWare system and responds with a patientId
4001004Support program with id: {{support_program_id}} not foundInvalid Support Program ID was submitted.
4001008The property supportProgramId is requiredInvalid Support Program ID was submitted.
4000The given data was invalid. Can't invite patients less than 18 independently.Patient is under 18, must include a Caregiver in the request.
4000The given data was invalid. Caregiver name and relationship are required in this case.Please include the Caregiver name and their relationship to the patient.
4000The given data was invalid. The phone number in the invite request is not aligned with the caregiver's phone number and the patient is less than 18 years.
4001008patient.phoneNumber is not valid format.Please resubmit the patient.phoneNumber using the E.164 format
4001008Does not match the regex pattern (^\+\d{11}$)|(^\+\d{12}$)Please resubmit the patient.phoneNumber using the E.164 format
4001002patient.dob is not valid format.Please resubmit the patient.dob using a valid format.
Example: 1988-08-23T00:00:00+00:00
4001005JWT is not valid for this programCheck your bearer token and resubmit the request.
4001006Token disabledPlease reach out to support@rxware.io to request a new token.
4001010The given data was invalid. The phone number in the invite request is not aligned with the caregiver's phone number and the patient is less than 18 years.The caregiver's phone number does not match what was submitted in the request and the patient is less than 18 years of age.
4010UnauthorizedIncorrect credentials. Check your auth token and bearer token.
403N/AForbiddenIncorrect credentials. Check your auth token and bearer token.
4221015{
"error": {
"message": "patient already created\\/invited.",
"code": 1015,
"data": {
"externalId": "externaltest001",
"phoneNumber": "{{patient_phone_number}}",
"_id": "{{patientId}}"
}
},
"status": 422
}		Patient already invited/created in the RxWare system.

NEXT: ➡️ EXAMPLE: Create Patient

Create a Patient
Skip to content