Skip to content

Sandbox Test Patients ​

The sandbox runs at:

https://demo-api.vivliohealth.io/ext/latest

Vivlio Health issues sandbox keys for this environment. Keys issued for any other environment do not work here. Every example on this page uses this base URL.

Your sandbox holds three sets of test patients. Each set does a different job:

SetIn GET /patients?RecordsUse it to test
Pre-seeded patients (4)YesAlready parsedResponse shapes
Retrieval patients (5)YesNone until you queryRecord retrieval end to end
EMPI matching patients (6)NoNonePatient matching (not working right now)

GET /patients lists nine patients: the four pre-seeded patients and the five retrieval patients. Their names carry Synthea's number suffixes. The suffixes are part of the name as loaded.

Each patient answers one query

Read One query per patient before you start a query. There is no reset.


Pre-seeded Patients ​

Four patients come with records that are already parsed. You can read their records right away, with no query.

First NameLast NameSexDOBAddressCityStateZip
Alton320Beatty507M1958-05-16929 Abbott View Suite 60AgawamMassachusetts01030
David908Gleichner915M1968-10-30602 Rosenbaum PassageLexingtonMassachusetts02421
Grady603Dach178M1961-05-18461 Koss Center Suite 87MontereyMassachusetts00000
Ruben688Schimmel440M1972-06-15184 D'Amore Path Apt 43Buzzards BayMassachusetts02532

List your sandbox patients:

http
GET https://demo-api.vivliohealth.io/ext/latest/patients
Authorization: Bearer {token}

The response includes a patientId for each patient. Find a pre-seeded patient by name and use their patientId to read records:

http
GET https://demo-api.vivliohealth.io/ext/latest/patients/{patientId}/records/medications
Authorization: Bearer {token}

Replace medications with any supported record type: allergies, encounters, labs, problemList, vitals, and others. See Medical Records for the full list.

These four patients show you what a response looks like. They do not go through record retrieval.

Start here

To see a patient record response, list your patients, take the patientId of a pre-seeded patient, and call any records endpoint. You don't need to create any test data.

Synthetic data limitations

Sandbox patients come from synthetic CCDA documents, so many fields are empty or hold placeholder values.

  • A medication has a name, a startDate and an endDate. sig, doseUnit, doseCount, status, refills, lastFill, note and dispensed come back null.
  • A problem-list entry carries a SNOMED code in metadata.code, for example "http://snomed.info/sct 314529007".
  • A patient may have no allergies, and an address may not be a real place.

Use these patients to check response shape and your integration logic. Don't use them to test rules that need fully populated records.


Retrieval Patients ​

These five patients are in GET /patients, but they have no records yet. Their records sit with another Vivlio Health client. When you query one of these patients, Vivlio Health fetches the records over its internal network and parses them. This is the set that tests record retrieval end to end.

First NameLast NameSexDOBAddressCityStateZip
Dean966Roob72M1986-08-02395 Leffler Ville Unit 14WorcesterMassachusetts01610
Eartha927 Delsie188Leuschke194F1997-12-11558 Kunde TunnelHanoverMassachusetts00000
Latashia561 Librada521Mills423F1978-04-23318 Macejkovic ClubLeominsterMassachusetts01420
Nohemi878Romaguera67F2007-11-29648 Bosco Harbor Unit 82MashpeeMassachusetts00000
Stanton715O'Reilly797M1998-09-07383 McKenzie DaleTauntonMassachusetts02767

Start a query ​

Create an appointment for the patient with autoQuery: true. The targetDate must fall within the next 14 days, or the query does not start.

http
POST https://demo-api.vivliohealth.io/ext/latest/appointments
Content-Type: application/json
Authorization: Bearer {token}
json
{
  "patientId": "{patientId}",
  "targetDate": "YYYY-MM-DD",
  "autoQuery": true
}

In the response, "autoQuery": { "queued": 1 } means the query started. See HIE Auto-Query for the other fields.

When the query completes, read the records:

http
GET https://demo-api.vivliohealth.io/ext/latest/patients/{patientId}/records/{recordType}
Authorization: Bearer {token}

Client-level accounts: poll for records

Webhooks are set up on partner accounts. If your sandbox key belongs to a client-level account, the parsed-data.created webhook may not reach you yet. Until your Vivlio contact tells you the webhook fix has shipped, poll the records endpoint to see when records arrive.


One Query per Patient ​

Each sandbox patient returns records on its first query only.

  • A second query for the same patient returns no new records. Vivlio Health marks the files it fetches again as duplicates and does not parse them.
  • A second query sends no parsed-data.created webhook, because the webhook only fires when a query returns new files. See Webhooks.
  • From outside, a patient who has used up their query looks the same as a patient with no medical history.

There is no reset. When you need fresh patients, ask your Vivlio contact, Steve Lambert or Kurt Davis.

Plan your queries

You have five retrieval patients. Decide what each query will test before you send it.


Rate Limits ​

The sandbox applies no rate limits today, and it does not require an X-Api-Key header. Vivlio Health will give you written notice before either one changes. See Rate Limiting.


EMPI Matching Test Patients ​

Not working right now

These six patients currently fail to match. Don't use them until your Vivlio contact tells you they work.

These patients are not in GET /patients. They are pre-loaded in a test EMPI (Enterprise Master Patient Index) so that you can test patient matching. To test a match, create the patient with POST /patients, using the demographics below, and then query their Medical Records. See Patients for the create request.

Distinct Patient IDs Required

Give every test patient you create a distinct external/patient identifier. If two of your sandbox patients share the same identifier, matching happens on that identifier instead of the demographics below, and you won't get a meaningful Exact/Probable match result.

Patients for Exact Match ​

Create these patients exactly as listed to get an Exact match result.

Last NameFirst NameSexSSNDOBAddress Line 1Address Line 2CityStateZipPhone
CraneTestTracyF—1936-12-26458 Streich Street—LunenburgMA014622223601564
CarinTestConnieF1098878781945-01-12681 Schumm View—WinchesterMA01890—
LopezQQQMaryF—1937-07-12647 Tromp Path—BostonMA02113—
EdmundoXXXRichardM—1957-10-251065 Hackett VilleSuite 4GloucesterMA01930—
LangTestRobertM—1952-12-22930 Rolfson HollowApt 15RevereMA02151—
DouglasTestShirleyF—1984-03-20296 Feest EsplanadeSuite 93LynnMA019402227465988

Example create request using LangTest:

http
POST https://demo-api.vivliohealth.io/ext/latest/patients
Content-Type: application/json
Authorization: Bearer {token}
json
{
  "firstName": "Robert",
  "lastName": "LangTest",
  "dob": "1952-12-22",
  "gender": "Male",
  "externalId": "SANDBOX-LANGTEST-01",
  "altAddresses": [
    {
      "address1": "930 Rolfson Hollow",
      "address2": "Apt 15",
      "city": "Revere",
      "state": "MA",
      "zip": "02151"
    }
  ]
}

Field Mapping Notes ​

  • DOB — maps to dob. The table and the API both use YYYY-MM-DD.
  • Sex — maps to the patient gender field: F → Female, M → Male. See Patient Object Fields.
  • Address Line 1/2 — map to altAddresses[].address1 / address2.
  • Phone — maps to phone, or to altTelecoms[].value with type: "HP".

Vivlio Health API Documentation