MedRev API Reference
Introduction
The MedRev API can be used to send surveys or social review requests, either individually or in bulk. This way you can automate your survey sends and social review requests. For example, you may use the API to send surveys just after a patient interaction or at the end of the business day.
Note that you will need to use the MedRev web application (https://app.medrevup.com) to set up your Company and Location information, as well as to configure the location to send out surveys, social review prompts, or a mix of both. This setting determines whether these endpoints will send out surveys or social review requests. The questions your patients see on their surveys are also set up in the MedRev web application.
The survey/social review request endpoints require the team number and location number to be provided in the URL. These variables are indicated within curly brackets in the URLs below. MedRev staff will provide you with the team number and location number(s) associated with your account. If you have a multi-location MedRev account, you can vary the location number depending on the location from which you wish to send the survey or social review request. You can find your survey definition number(s) via the MedRev web application, by navigating to the Edit Survey Questions page and hovering over the survey title(s). The survey definition number will allow the MedRev API to know which of your surveys you wish to send out.
This API accepts multipart/form-data request bodies. It returns JSON-encoded responses and uses standard HTTP response codes.
Authentication
The MedRev API uses API keys to authenticate requests. MedRev staff will provide you with an API key via Zoho Vault. Please keep your API key secure. Remember not to share it in areas that the public could access, such as a GitHub repo or client-side code.
HTTP Basic Auth is used for authentication to the API. Use your API key as the basic auth username. A password value is not required.
Endpoints
Ping
Returns a timestamp. Use this endpoint to verify successful authentication with the MedRev API.
GET https://api.medrevup.com/api/integration/ping
Arguments
None
Response
{
“timestamp”: 1570038682
}
Survey/Social Review Request Send
Sends a single survey or social review request (whichever the location is configured to send).
POST https://api.medrevup.com/api/integration/teams/{team_number}/locations/{location_number}/surveys/{survey_definition_number}
Arguments
name (optional)
This is the name of the patient to whom the survey or social review request is being sent.
(either email or phone is required, and both are recommended if available)
This is the email address of the patient to whom the survey or social review request is being sent. If no mobile phone number is supplied, or if the phone number supplied is determined to be a landline, the survey or social review request will be sent to the patient’s email address. Even if a mobile phone number is supplied, survey reminders and automated thank you emails will be sent to this email address.
phone
(either email or phone is required, and both are recommended if available)
This is the mobile phone number of the patient to whom the survey or social review request is being sent. Surveys and social review requests will be sent to the mobile phone number, unless it is determined to be a landline.
department (optional)
This is the name of the department in which the patient was seen.
provider (optional)
This is the name of the provider who saw the patient (e.g., “Dr. John Smith”).
no_send (optional)
If this parameter is missing or set to “0”, the survey or social review request will be sent by MedRev to the patient. If this parameter is present and set to “1”, MedRev will not send the survey or social review request to the patient. Instead, the endpoint will return a link and shortened link to the survey or social review request. This option is for teams who wish to send out the requests themselves. Note that MedRev will still send out survey reminders, thank you and response emails, even if the no_send parameter is set to “1”.
Note that if you are a team that uses MedRev to interact with patients, you alone are responsible for ensuring that the manner in which you send survey or social review request links to patients is HIPAA compliant. If you wish for MedRev to perform identity validation (i.e., verifying the mobile number of the patient before allowing them to see the survey or social review request web page), you will need to provide the patient’s phone number in the request arguments.
Response (if no_send is missing or “0”)
{
“status”: true,
“message”: null
}
Response (if no_send is “1”)
{
“status”: true,
“message”: null,
“link”: “http://api.medrevup.local/survey/take/373c7410d2ad11ea930d0785a901b81d”,
“short_link”: “https://medq.me/eICt”
}
Batch Survey/Social Review Request Send
Sends a group of surveys or social review requests (whichever the location is configured to send).
POST https://api.medrevup.com/api/integration/teams/{team_number}/locations/{location_number}/surveys/batch/{survey_definition_number}
Arguments
file (required)
This is a CSV file containing a group of patients to whom surveys or social review requests (whichever the location is configured to send) will be sent. The CSV should be formatted as follows:
Patient Name 1, Email 1, Mobile Phone 1, Department (Optional), Provider (Optional)
Patient Name 2, Email 2, Mobile Phone 2, Department (Optional), Provider (Optional)
And so on, with one patient per row…
Mobile phone numbers should be 10 digits, with no spaces or punctuation.
Response
Here is a response for a request that supplied a CSV file with 8 patients. This response illustrates how errors are conveyed, as 3 of the patients were unable to be sent surveys/social review requests for differing reasons.
{
“count”: 8,
“jobs_count”: 5,
“errors”:[
{
“line”: 2,
“error”: “We can’t send this survey or social review request via text or email because the patient has opted out”,
“params”: {
“location_id”: 3,
“name”: “Nancy NoPhone”,
“email”: “NoPhone@mailsac.com”
}
},
{
“line”: 3,
“error”: “We can’t send this survey or social review request via text or email because the patient has opted out”,
“params”: {
“location_id”: 3,
“name”: “Another NoPhone”,
“email”: “AnotherNoPhone@mailsac.com”,
“department”: “Emergency Department”
}
},
{
“line”: 5,
“error”: ” The email field is required when phone is not present. The phone field is required when email is not present.”,
“params”: {
“location_id”: 3,
“name”: “Norbet NoEmail”,
“department”: “Cardiology”
}
}
],
“message”: “5 surveys queued for sending. 3 rows contain errors. You will receive an email with the results of the batch process.”
}
Survey Results
Gets all the surveys that have been sent, whether they have been completed or not. This endpoint returns objects representing the same surveys that can be found in the Surveys Table (https://app.medrevup.com/surveys). Note that this endpoint is only available to teams that are using MedRev for non-patient customer satisfaction surveys. This endpoint will return an error message if called upon by teams that use MedRev for patient interactions.
GET https://api.medrevup.com/api/integration/teams/{team_number}/locations/{location_number}/surveys/{survey_definition_number}
Arguments
N/A
Response
Here is a sample response with just one survey object, representing a completed survey. Of particular note are the “contact”, “history”, and “answers” child objects, which will convey who the survey was sent to, the interactions of the survey taker with the survey, and the answers the survey taker provided to each question on the survey.
[
{
“id”: 9999,
“contact_id”: 999,
“location_id”: 99,
“department”: “Department Name”,
“results”: “5”,
“opinion”: 100,
“started”: “2020-07-24 16:34:49”,
“completed”: “2020-07-24 16:35:00”,
“dismissed”: 0,
“comments”: null,
“sentiment_score”: null,
“ip”: “IP_ADDRESS_HERE”,
“device”: “iPhone”,
“sent_by”: “text”,
“created_at”: “2020-07-24 16:04:29”,
“updated_at”: “2020-07-24 16:35:00”,
“deleted_at”: null,
“created_by”: 900,
“updated_by”: 0,
“pretty_times”: {
“sent”: {
“formatted”: “Friday at 4:04 PM”,
“full”: “July 24th, 2020 at 4:04 PM”
},
“started”: {
“formatted”: “Friday at 4:34 PM”,
“full”: “July 24th, 2020 at 4:34 PM”
},
“completed”: {
“formatted”: “Friday at 4:35 PM”,
“full”: “July 24th, 2020 at 4:35 PM”
}
},
“contact”: {
“id”: 999,
“name”: “Michelle Cobb”,
“phone”: “5556667777”,
“email”: “michelle@medrevup.com”,
“team_id”: 99,
“ris_id”: null,
“created_at”: “2020-07-13 14:57:47”,
“updated_at”: “2020-07-13 14:57:47”,
“deleted_at”: null,
“created_by”: 900,
“updated_by”: 900,
“optOutEmail”: false,
“optOutEmailDateTime”: null,
“optOutText”: false,
“optOutTextDateTime”: null
},
“history”: [
{
“id”: 99990,
“contact_id”: 999,
“survey_id”: 9999,
“action”: “SURVEY_SENT”,
“details”: {
“smssent”: true,
“phone”: “5556667777”,
“email”: “michelle@medrevup.com”,
“responder”: 900,
“mail_content”: “Thanks for attending your visit with us. Please let us know how satisfied you were with your visit.”,
“user_id”: 900
},
“created_at”: “2020-07-24 16:04:29”,
“updated_at”: “2020-07-24 16:04:29”,
“pretty_action”: “Survey sent to patient”
},
{
“id”: 99991,
“contact_id”: 999,
“survey_id”: 9999,
“action”: “SURVEY_OPENED”,
“details”: {
“user_id”: 900
},
“created_at”: “2020-07-24 16:34:50”,
“updated_at”: “2020-07-24 16:34:50”,
“pretty_action”: “Survey opened”
},
{
“id”: 99992,
“contact_id”: 999,
“survey_id”: 9999,
“action”: “SURVEY_COMPLETED”,
“details”: {
“user_id”: 900
},
“created_at”: “2020-07-24 16:35:01”,
“updated_at”: “2020-07-24 16:35:01”,
“pretty_action”: “Survey completed”
},
{
“id”: 99993,
“contact_id”: 999,
“survey_id”: 9999,
“action”: “SURVEY_THANKYOU_SENT”,
“details”: {
“smssent”: null,
“phone”: “5556667777”,
“email”: “michelle@medrevup.com”,
“mail_content”: “Thank you for your feedback! We appreciate the time you took to fill out our survey.”,
“user_id”: 900
},
“created_at”: “2020-07-24 16:35:01”,
“updated_at”: “2020-07-24 16:35:01”,
“pretty_action”: “Thank You email sent to patient”
}
],
“answers”: [
{
“id”: 999,
“survey_id”: 9999,
“question_id”: 99,
“question”: “How satisfied are you with your recent visit?”,
“question_type”: 1,
“multi_answer”: 0,
“question_order”: 1,
“answer”: “5”,
“answer_type”: null,
“created_at”: “2020-07-24 16:35:00”,
“updated_at”: “2020-07-24 16:35:00”
}
]
}
]