Oystehr

https://docs.oystehr.com/
Admin
Oystehr is a comprehensive health tech developer platform that enables building robust clinical...
Tokens:141,194
Snippets:1,336
Trust Score:7.5
Update:5 months ago
Show doc for...
Tokens:
Raw
### Start Ottehr in Development Mode

Source: https://docs.oystehr.com/ottehr/development

Run this script from the project root after installing dependencies and setting up the project to start the Patient Portal and EHR applications.

```bash
npm run apps:start
```

--------------------------------

### User Invite Example

Source: https://docs.oystehr.com/oystehr/core-documentation/typescript-sdk

This example demonstrates how to use the SDK to invite a user to an application, abstracting away the `applicationId`.

```APIDOC
## Invite User to Application

### Description
Invites a user to a specific application, overriding the default application ID.

### Method
`oystehr.user.invite`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **input** (Omit<UserInviteParams, 'applicationId'>) - Required - An object containing user invitation details, excluding `applicationId`.
  - **email** (string) - Required - The email address of the user to invite.
  - **role** (string) - Required - The role to assign to the user.

### Request Example
```typescript
import Oystehr, { UserInviteParams } from '@oystehr/sdk';

const APP_ID = process.env.OYSTEHR_APP_ID;
const oystehr = new Oystehr({ accessToken: accessTokenFromAuthn });

async function inviteUserToMyApp(
  oystehr: Oystehr,
  input: Omit<UserInviteParams, 'applicationId'>
): Promise<UserInviteResponse> {
  return oystehr.user.invite({
    ...input,
    applicationId: APP_ID,
  });
}

// Example usage:
// inviteUserToMyApp(oystehr, { email: 'test@example.com', role: 'admin' });
```

### Response
#### Success Response (200)
- **UserInviteResponse** - An object confirming the user invitation.
```

--------------------------------

### Candid Contract Example

Source: https://docs.oystehr.com/ottehr/setup/claims-and-payments

Use this template to get started with configuring contracts, which connect providers, billers, charge masters, and fee schedules.

```json
{
  "data": [
    {
      "payer_id": "payer_123",
      "provider_id": "provider_456",
      "billing_code": "billing_789",
      "start_date": "2023-01-01",
      "end_date": "2023-12-31"
    }
  ]
}
```

--------------------------------

### Install the Oystehr SDK

Source: https://docs.oystehr.com/oystehr/core-documentation/typescript-sdk

Install the Oystehr SDK using npm. This command adds the SDK package to your project dependencies.

```bash
npm install @oystehr/sdk
```

--------------------------------

### Complete Async FHIR Workflow Example

Source: https://docs.oystehr.com/oystehr/services/fhir/async-fhir-interactions

Demonstrates the end-to-end asynchronous FHIR workflow using the Oystehr SDK. This includes starting an async search, waiting for the job to complete, and processing the results. Ensure you have the Oystehr SDK installed and an access token.

```typescript
import { Patient } from 'fhir/r4b';
import Oystehr from '@oystehr/sdk';

const oystehr = new Oystehr({
  accessToken: '<your_access_token>',
});

// 1. Start an async search
const handle = await oystehr.fhir.search<Patient>(
  {
    resourceType: 'Patient',
    params: [{ name: 'name', value: 'Jon' }],
  },
  { mode: 'async-bundle' }
);

console.log(`Async job started: ${handle.jobId}`);

// 2. Wait for the result (polls automatically)
const result = await oystehr.fhir.waitForAsyncJob<Patient>(handle.jobId, {
  pollIntervalMs: 2000,
  timeoutMs: 300000,
});

// 3. Process the result
if (result.status === 200 && result.mode === 'bundle') {
  console.log(`Interaction status: ${result.interactionStatus}`);
  console.log(`Result resource:`, result.resource);
}
```

--------------------------------

### Full Z3 File Upload and Download Example with Python

Source: https://docs.oystehr.com/oystehr/services/z3

This comprehensive example demonstrates creating a bucket, uploading a file, and then retrieving its download URL. It requires a valid token and the file to be uploaded.

```python
import requests
import json
 
token = "put_a_token_here"
 
create_request = requests.put("https://project-api.zapehr.com/v1/z3/fruit-vegetables",
  headers={
    "Authorization": f"Bearer {token}"
  }
)
 
print(create_request.json())
 
upload_request = requests.post("https://project-api.zapehr.com/v1/z3/fruit-vegetables/fruit-and-vegetable-consumption-in-california-residents-2012-2013-.csv",
  headers={
    "Authorization": f"Bearer {token}"
  },
  data=json.dumps({
    "action": "upload"
  })
)
print(upload_request.json())
upload_url = upload_request.json()["signedUrl"]
 
information = open("fruit-and-vegetable-consumption-in-california-residents-2012-2013-.csv", "rb").read()
requests.put(upload_url, data=information)
 
 download_request = requests.post("https://project-api.zapehr.com/v1/z3/fruit-vegetables/fruit-and-vegetable-consumption-in-california-residents-2012-2013-.csv",
  headers={
    "Authorization": f"Bearer {token}"
  },
  data=json.dumps({
    "action": "download"
  })
)
 
 download_url = download_request.json()["signedUrl"]
print(download_url)
 
 t = requests.get("https://project-api.zapehr.com/v1/z3/fruit-vegetables",
  headers={
    "Authorization": f"Bearer {token}"
  }
)
print(t.json())

```

--------------------------------

### Candid Fee Schedule Example

Source: https://docs.oystehr.com/ottehr/setup/claims-and-payments

Import your fee schedules in bulk for each payer using this example. This configures negotiated rates and can be updated later as needed.

```json
{
  "data": [
    {
      "payer_id": "payer_123",
      "price": "65.00",
      "procedure_code": "99213",
      "modifier": ""
    }
  ]
}
```

--------------------------------

### FHIR Resource Creation Example

Source: https://docs.oystehr.com/oystehr/core-documentation/typescript-sdk

This example shows how to create FHIR resources using the SDK, demonstrating type handling for R4B and R5 versions.

```APIDOC
## Create FHIR Resource

### Description
Creates a FHIR resource of a specified version (R4B or R5) using the Oystehr SDK.

### Method
`oystehr.fhir.create<T>`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **resourceType** (string) - Required - The type of FHIR resource to create (e.g., 'Encounter', 'Patient').
- **status** (string) - Required - The status of the resource.
- **class** (object or array) - Required - The class of the resource.
- Other resource-specific properties.

### Request Example
```typescript
import Oystehr from '@oystehr/sdk';
import { Encounter as EncounterR4B } from 'fhir/r4b';
import { Encounter as EncounterR5 } from 'fhir/r5';

const oystehr = new Oystehr({ accessToken: 'your_access_token' });

// Creating an R4B Encounter
const encounter4 = await oystehr.fhir.create<EncounterR4B>({
  resourceType: 'Encounter',
  status: 'arrived',
  class: {},
});

// Creating an R5 Encounter
const encounter5 = await oystehr.fhir.create<EncounterR5>({
  resourceType: 'Encounter',
  status: 'arrived', // Note: This might cause a type error depending on FHIR version enum values
  class: [],
});
```

### Response
#### Success Response (200)
- **T** - The created FHIR resource of the specified type.
```

--------------------------------

### Candid Charge Master Example

Source: https://docs.oystehr.com/ottehr/setup/claims-and-payments

Use this example for Candid's bulk import feature to set up your charge master, which outlines service prices based on procedure codes and modifiers.

```json
{
  "data": [
    {
      "procedure_code": "99213",
      "modifier": "",
      "description": "Office or other outpatient visit, est 15 minutes",
      "price": "75.00"
    }
  ]
}
```

--------------------------------

### Example Location Resource

Source: https://docs.oystehr.com/oystehr/services/lab/submit-an-order

Represents the office placing the order. The 'address' field must be populated.

```json
{
  "id": "b204fd19-f87f-4416-b00e-fc176fb7b3e2",
  "resourceType": "Location",
  "name": "Example Place",
  "address": {
    "line": [
      "12345 Location St"
    ],
    "city": "Alexandria",
    "state": "VA",
    "postalCode": "22222"
  },
  "meta": {
    "versionId": "f747eedc-812e-4e74-a5b3-33153b20258f",
    "lastUpdated": "2025-03-31T17:25:08.147Z"
  }
}
```

--------------------------------

### Example Organization Resource

Source: https://docs.oystehr.com/oystehr/services/lab/submit-an-order

Represents the lab. The 'labGuid' must be included as an 'identifier', and the 'name' field is required.

```json
{
  "id": "09518019-5e16-4982-9840-f01410d1673c",
  "resourceType": "Organization",
  "name": "AutoLab",
  "identifier": [
    {
      "system": "https://identifiers.fhir.oystehr.com/lab-guid",
      "value": "790b282d-77e9-4697-9f59-0cef8238033a"
    }
  ],
  "meta": {
    "versionId": "be7e78b2-4447-48e8-a323-340f32824936",
    "lastUpdated": "2025-03-31T17:25:07.786Z"
  }
}
```

--------------------------------

### Example Returned Route

Source: https://docs.oystehr.com/oystehr/services/lab/onboarding-a-lab

This is an example of a route object that is returned after a successful retrieval. It includes the unique identifiers for the route and the lab, along with the account number.

```json
{
  "routeGuid": "8dd926b3-fb96-4424-95d8-4e73368c2767",
  "labGuid": "790b282d-77e9-4697-9f59-0cef8238033a",
  "accountNumber": "Sample-Account-Number"
}
```

--------------------------------

### Example 200 Response for Pharmacy Search

Source: https://docs.oystehr.com/oystehr/services/erx/pharmacy-search

This is an example of a successful (200 OK) response when searching for pharmacies. It includes pharmacy details and pagination metadata.

```json
{
  "data": [
    {
      "id": 5285,
      "name": "CVS",
      "address1": "123 Main St",
      "city": "Anytown",
      "state": "MO",
      "zip": "12345",
      "phone": "555-123-4567",
      "specialties": ["retail"]
    }
  ],
  "metadata": {
    "hasNext": false,
    "hasPrevious": false,
    "total": 1,
    "currentPage": 1,
    "totalPages": 1,
    "pageSize": 10
  }
}
```

--------------------------------

### Combining Forward and Reverse Chaining Example

Source: https://docs.oystehr.com/oystehr/services/fhir/search

Shows how to combine forward and reverse chaining in a single query for more complex filtering.

```APIDOC
## Combining Forward and Reverse Chains

You can combine forward and reverse chaining in a single query.

### Example:
```javascript
import { RelatedPerson } from 'fhir/r4b';
import Oystehr from '@oystehr/sdk';

const oystehr = new Oystehr({
  accessToken: "<your_access_token>",
});

const bundle/*: Bundle<RelatedPerson>*/ = await oystehr.fhir.search<RelatedPerson>({
  resourceType: 'RelatedPerson',
  params: [
    {
      name: 'patient._has:Appointment:patient:location',
      value: 'Location/abc-123',
    },
  ],
});
const relatedPersons/*: RelatedPerson[]*/ = bundle.unbundle();
```
```

--------------------------------

### FHIR Search and Unbundle Example

Source: https://docs.oystehr.com/oystehr/core-documentation/typescript-sdk

Demonstrates how to search for FHIR resources and unwrap the resulting `Bundle` into a simple array.

```APIDOC
## Search FHIR Resources and Unbundle

### Description
Searches for FHIR resources based on provided parameters and provides a utility function to unwrap the `Bundle` response into an array of resources.

### Method
`oystehr.fhir.search<T>` and `bundle.unbundle()`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **resourceType** (string) - Required - The type of FHIR resource to search for.
- **params** (Array<object>) - Optional - An array of search parameters.
  - **name** (string) - Required - The name of the parameter.
  - **value** (string) - Required - The value of the parameter.

### Request Example
```typescript
import Oystehr from '@oystehr/sdk';
import { Patient } from 'fhir/r4b';

const oystehr = new Oystehr({ accessToken: 'your_access_token' });

const patientBundle = await oystehr.fhir.search<Patient>({
  resourceType: 'Patient',
  params: [
    {
      name: 'name',
      value: 'sam',
    },
  ],
});

const patients: Patient[] = patientBundle.unbundle();
```

### Response
#### Success Response (200)
- **Bundle<T>** - A FHIR Bundle containing the search results.
- **unbundle()** - A method on the Bundle object that returns an array of the base resource type `T[]`.
```

--------------------------------

### Example Practitioner Resource

Source: https://docs.oystehr.com/oystehr/services/lab/submit-an-order

A Practitioner resource including a valid NPI with the correct system and a name.

```json
{
  "id": "5f887104-99b0-4492-9a82-fa35bccf7e99",
  "resourceType": "Practitioner",
  "meta": {
    "versionId": "6e77c971-0391-4c41-9114-1edfe2317b8a",
    "lastUpdated": "2025-03-28T04:48:20.323Z"
  },
  "name": [
    {
      "use": "official",
      "given": [
        "Good"
      ],
      "family": "Doctor"
    }
  ],
  "identifier": [
    {
      "value": "1932929191",
      "system": "http://hl7.org/fhir/sid/us-npi"
    }
  ]
}
```

--------------------------------

### SDK v3 Search Example

Source: https://docs.oystehr.com/oystehr/services/fhir/search

Demonstrates how to search for Patient resources using the Oystehr TypeScript SDK.

```APIDOC
## SDK v3 Search Example

This example shows how to search for all patients named "Jon" using the Oystehr v3 SDK.

```typescript
import { Patient } from 'fhir/r4b'; // npm install @types/fhir
import Oystehr from '@oystehr/sdk'

const oystehr = new Oystehr({
  accessToken: "<your_access_token>",
});

const patientBundle/*: Bundle<Patient>*/ = await oystehr.fhir.search<Patient>({
  resourceType: 'Patient',
  params: [
    {
      name: 'given',
      value: 'Jon',
    },
  ],
});
const patients/*: Patient[]*/ = patientBundle.unbundle();
```
```

--------------------------------

### GET Request Example

Source: https://docs.oystehr.com/oystehr/services/fhir/search

Example of how to perform a FHIR search using a GET request with cURL.

```APIDOC
## GET Request Example

Search for all patients named "Jon" with a GET request:

```bash
curl --location 'https://fhir-api.zapehr.com/r4/Patient?given=Jon' \
--header 'Authorization: Bearer <your_access_token>' \
--header 'x-oystehr-project-id: <your_project_id>'
```
```

--------------------------------

### Create Application with v3 SDK

Source: https://docs.oystehr.com/oystehr/services/app/applications

Use this snippet to create a new application. Configure properties like name, redirect URIs, and login methods. Ensure you have your access token.

```javascript
import Oystehr from '@oystehr/sdk';

const oystehr = new Oystehr({
  accessToken: '<your_access_token>',
});

const app = await oystehr.application.create(
  {
    name: 'patient-portal',
    description:
      'Patients log into this Application to use the Patient Portal to schedule appointments and view lab results.',
    loginRedirectUri: 'https://patientportal.notarealpractice.com/',
    allowedCallbackUrls: ['https://patientportal.notarealpractice.com/'],
    allowedLogoutUrls: ['https://patientportal.notarealpractice.com/logout'],
    allowedWebOriginsUrls: [],
    allowedCORSOriginsUrls: [],
    logoUri: 'https://static.notarealpractice.com/logo_150_x_150.png',
    loginWithEmailEnabled: true,
    passwordlessSMS: false,
    shouldSendInviteEmail: true,
    mfaEnabled: false,
  }
);
```

--------------------------------

### Create Application

Source: https://docs.oystehr.com/oystehr/services/app/applications

This snippet demonstrates how to create a new application with various configurations, such as login redirect URIs, allowed callback URLs, and email login enablement. It also shows the structure of the response received upon successful creation.

```APIDOC
## Create Application

This operation allows you to create a new application within the Oystehr system. You can configure various settings related to authentication, redirects, and user login methods.

### Method

```javascript
await oystehr.application.create
```

### Parameters

#### Request Body

- **name** (string) - Required - The name of the application.
- **description** (string) - Optional - A description for the application.
- **loginRedirectUri** (string) - Required - The URI to redirect users to after login.
- **allowedCallbackUrls** (array of strings) - Required - A list of allowed URLs for callback after authentication.
- **allowedLogoutUrls** (array of strings) - Required - A list of allowed URLs for redirection after logout.
- **allowedWebOriginsUrls** (array of strings) - Optional - A list of allowed web origins.
- **allowedCORSOriginsUrls** (array of strings) - Optional - A list of allowed CORS origins.
- **logoUri** (string) - Optional - The URI for the application's logo.
- **loginWithEmailEnabled** (boolean) - Optional - Enables login with email and password.
- **passwordlessSMS** (boolean) - Optional - Enables passwordless SMS login.
- **shouldSendInviteEmail** (boolean) - Optional - Determines if an invite email should be sent to new users.
- **mfaEnabled** (boolean) - Optional - Enables multi-factor authentication.

### Request Example

```javascript
const app = await oystehr.application.create({
  name: 'patient-portal',
  description: 'Patients log into this Application to use the Patient Portal to schedule appointments and view lab results.',
  loginRedirectUri: 'https://patientportal.notarealpractice.com/',
  allowedCallbackUrls: ['https://patientportal.notarealpractice.com/'],
  allowedLogoutUrls: ['https://patientportal.notarealpractice.com/logout'],
  allowedWebOriginsUrls: [],
  allowedCORSOriginsUrls: [],
  logoUri: 'https://static.notarealpractice.com/logo_150_x_150.png',
  loginWithEmailEnabled: true,
  passwordlessSMS: false,
  shouldSendInviteEmail: true,
  mfaEnabled: false,
});
```

### Response

#### Success Response (200)

- **id** (string) - The unique identifier of the created application.
- **clientId** (string) - The OAuth 2.0 Client Identifier for the application.
- **name** (string) - The name of the application.
- **description** (string) - The description of the application.
- **loginRedirectUri** (string) - The login redirect URI.
- **allowedCallbackUrls** (array of strings) - The list of allowed callback URLs.
- **allowedLogoutUrls** (array of strings) - The list of allowed logout URLs.
- **allowedWebOriginsUrls** (array of strings) - The list of allowed web origins.
- **allowedCORSOriginsUrls** (array of strings) - The list of allowed CORS origins.
- **mfaEnabled** (boolean) - Indicates if MFA is enabled.
- **logoUri** (string) - The URI of the application's logo.
- **shouldSendInviteEmail** (boolean) - Indicates if invite emails are sent.
- **passwordlessSMS** (boolean) - Indicates if passwordless SMS is enabled.
- **loginWithEmailEnabled** (boolean) - Indicates if login with email is enabled.

#### Response Example

```json
{
  "id": "9d6df0c7-6d59-43b8-a74a-3cf2a8046608",
  "clientId": "i5ae3PnUKrWUZa3c3deQe91ML21eVU7w",
  "name": "patient-portal",
  "description": "Patients log into this Application to use the Patient Portal to schedule appointments and view lab results.",
  "loginRedirectUri": "https://patientportal.notarealpractice.com/",
  "allowedCallbackUrls": ["https://patientportal.notarealpractice.com/"] ,
  "allowedLogoutUrls": ["https://patientportal.notarealpractice.com/logout"],
  "allowedWebOriginsUrls": [],
  "allowedCORSOriginsUrls": [],
  "mfaEnabled": false,
  "logoUri": "https://static.notarealpractice.com/logo_150_x_150.png",
  "shouldSendInviteEmail": true,
  "passwordlessSMS": false,
  "loginWithEmailEnabled": true
}
```
```

--------------------------------

### Search Patients by Given Name with SDK v3

Source: https://docs.oystehr.com/oystehr/services/fhir/search

Use the Oystehr SDK to search for FHIR resources. This example demonstrates searching for patients by their given name. Ensure you have the necessary types installed.

```typescript
import { Patient } from 'fhir/r4b'; // npm install @types/fhir
import Oystehr from '@oystehr/sdk'

const oystehr = new Oystehr({
  accessToken: "<your_access_token>",
});

const patientBundle/*: Bundle<Patient>*/ = await oystehr.fhir.search<Patient>({
  resourceType: 'Patient',
  params: [
    {
      name: 'given',
      value: 'Jon',
    },
  ],
});
const patients/*: Patient[]*/ = patientBundle.unbundle();
```

--------------------------------

### API Request with x-oystehr-project-id Header

Source: https://docs.oystehr.com/oystehr/core-documentation/authenticating-api-requests

Example of making a GET request to the FHIR API, including the `Authorization` header with a bearer token and the `x-oystehr-project-id` header to specify the target project. This is required for Developers acting on multiple projects.

```javascript
const response = await fetch(`https://fhir-api.zapehr.com/r4/Practitioner`, {
  headers: {
    Authorization: `Bearer ${your_access_token}`,
    'x-oystehr-project-id': your_project_id,
  },
  method: 'GET',
});
```

--------------------------------

### Performing FHIR Transaction with Oystehr SDK

Source: https://docs.oystehr.com/oystehr/core-documentation/typescript-sdk

Example of a FHIR transaction request using the Oystehr SDK, including a PATCH operation to update an appointment and a GET request to retrieve appointments for the current day. Supports pre-encoded Binary resources or JSON Patch operations.

```typescript
import dayjs from 'dayjs';
import Oystehr, { BatchInputGetRequest, BatchInputPatchRequest } from '@oystehr/sdk';
const oystehr = new Oystehr({
  accessToken: '<your_access_token>',
});
const patchAppointment: BatchInputPatchRequest = {
  method: 'PATCH',
  url: '/Appointment/some_appointment_id',
  operations: [{
    op: 'replace',
    path: '/start',
    value: dayjs().format('YYYY-MM-DDTHH:mm:ss.SSSZ'),
  }],
};
const getAppointments: BatchInputGetRequest = {
  method: 'GET',
  url: `/Appointment?date=sa${dayjs().startOf('day').format('YYYY-MM-DDTHH:mm:ss.SSSZ')}`,
};
await oystehr.fhir.transaction<Appointment>({ requests: [patchAppointment, getAppointments ]});
```

--------------------------------

### Error Payload Example

Source: https://docs.oystehr.com/oystehr/core-documentation/working-with-large-data

This is an example of the error payload received when an API response exceeds the maximum allowed size.

```json
{
  "code": "4130",
  "message": "An internal response size (7,003,938) exceeds the maximum allowed size (6,291,456).  Please refine your query with pagination or use the _elements parameter for FHIR resources.  See: https://docs.zapehr.com/oystehr/core-documentation/working-with-large-data"
}
```

--------------------------------

### POST Request Example

Source: https://docs.oystehr.com/oystehr/services/fhir/search

Example of how to perform a FHIR search using a POST request with cURL, useful for long parameters.

```APIDOC
## POST Request Example

To perform a search with long parameters or many parameters, use a POST request to the `/:resource/_search` endpoint.

```bash
curl --location 'https://fhir-api.zapehr.com/r4/Patient/_search' \
--header 'Authorization: Bearer <your_access_token>' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'x-oystehr-project-id: <your_project_id>' \
--data-urlencode 'given=Jon'
```
```

--------------------------------

### Onboarding a Fax Number

Source: https://docs.oystehr.com/oystehr/services/fax/number

Onboard a fax number using the v3 SDK. This will purchase a fax number and associate it with your project. The Fax Service only supports registering one fax number per project.

```APIDOC
## Onboarding a Fax Number

### Description
Onboard a fax number using the v3 SDK. This will purchase a fax number and associate it with your project.

### Method
`POST` (implied by SDK method)

### Endpoint
`/fax/onboard` (implied by SDK method)

### Request Body
None

### Response
#### Success Response (200)
- **faxNumber** (string) - The newly provisioned fax number in E.164 format.

### Response Example
```json
{
  "faxNumber": "+12223334444"
}
```
```

--------------------------------

### FHIR Patient Resource Example

Source: https://docs.oystehr.com/oystehr/services/rcm/eligibility

An example of a Patient FHIR resource, containing demographic and contact information. This resource is referenced by the CoverageEligibilityRequest.

```json
{
  "id": "a5841e0d-8270-49ff-87e0-96520c283639",
  "meta": {
    "versionId": "27ea83d9-adc4-441f-ba7c-43b32eb25a92",
    "lastUpdated": "2024-07-01T17:00:46.690Z"
  },
  "name": [
    {
      "given": [
        "PETER"
      ],
      "family": "GRIFFIN"
    }
  ],
  "gender": "female",
  "address": [
    {
      "city": "QUAHOG",
      "line": [
        "31 SPOONER ST"
      ],
      "state": "RI",
      "postalCode": "11738"
    }
  ],
  "birthDate": "2022-05-14",
  "resourceType": "Patient"
}
```

--------------------------------

### Run Staging Environment Deployment Script

Source: https://docs.oystehr.com/ottehr/deploying/gcp

Execute the npm script to deploy Ottehr to the staging environment on GCP. This process typically takes around 15 minutes.

```bash
# From deploy/ directory
npm run apply-staging
```

--------------------------------

### FHIR CoverageEligibilityRequest Resource Example

Source: https://docs.oystehr.com/oystehr/services/rcm/eligibility

An example of a CoverageEligibilityRequest FHIR resource, used to initiate an eligibility check. Ensure all referenced resources are up to date.

```json
{
  "id": "92755430-5ea0-4927-a74d-5e3425efd9b4",
  "resourceType": "CoverageEligibilityRequest",
  "status": "active",
  "purpose": [
    "benefits"
  ],
  "created": "2024-06-13",
  "patient": {
    "reference": "Patient/a5841e0d-8270-49ff-87e0-96520c283639"
  },
  "insurer": {
    "reference": "Organization/0d03d037-af76-4813-b228-105336238317"
  },
  "provider": {
    "reference": "Organization/bea1bda2-e069-4f91-ac50-be5c8f1337b2"
  },
  "insurance": [
    {
      "coverage": {
        "reference": "Coverage/755a526a-0c78-4731-bac2-d6209fc30f36"
      }
    }
  ],
  "item": [
    {
      "category": {
        "coding": [
          {
            "system": "http://terminology.oystehr.com/CodeSystem/benefit-category",
            "code": "30",
          },
        ],
      },
      {
        "productOrService": {
          "coding": [
            {
              "system": "http://terminology.oystehr.com/CodeSystem/product-code",
              "code": "99213"
            }
          ]
        }
      }
    },
  ],
  "meta": {
    "versionId": "6dbae679-6800-4ee9-8726-c34a60ca34ef",
    "lastUpdated": "2024-07-18T13:21:53.649Z"
  }
}
```

--------------------------------

### Example FHIR MedicationRequest Resource

Source: https://docs.oystehr.com/oystehr/services/erx/create-prescriptions

This is an example of a MedicationRequest FHIR resource created when a medication is prescribed. It details the medication, dosage, patient, and requester.

```json
{
    "resourceType": "MedicationRequest",
    "identifier": [
        {
            "system": "https://identifiers.fhir.oystehr.com/erx-prescription-id",
            "value": "19421344"
        }
    ],
    "status": "active",
    "intent": "order",
    "subject": {
        "reference": "Patient/06d1cf3d-c33e-40d2-b6c2-191538e9bb8c"
    },
    "requester": {
        "reference": "Practitioner/3c9a43c1-00fe-432c-9782-ce876c2e5831"
    },
    "dispenseRequest": {
        "quantity": {
            "unit": "EA",
            "value": 20
        },
        "numberOfRepeatsAllowed": 2,
        "expectedSupplyDuration": {
            "code": "d",
            "system": "http://unitsofmeasure.org",
            "unit": "day",
            "value": 10
        },
        "validityPeriod": {
            "start": "2022-01-01",
            "end": "2023-01-01"
        }
    },
    "dosageInstruction": [
        {
            "patientInstruction": "Take twice daily"
        }
    ],
    "medicationCodeableConcept": {
        "coding": [
            {
                "system": "https://terminology.fhir.oystehr.com/CodeSystem/medispan-dispensable-drug-id",
                "code": "7124",
                "display": "Zestril (Lisinopril 2.5 mg) Oral tablet"
            }
        ]
    },
    "id": "1d9df545-8230-4913-a6be-90886a4abf4f",
    "meta": {
        "versionId": "a5de4dbb-e8ed-4965-806b-ffd9d8e47fe0",
        "lastUpdated": "2024-05-15T23:11:30.669Z"
    }
}
```

--------------------------------

### `name` Search Parameter Examples

Source: https://docs.oystehr.com/oystehr/services/fhir/search

Demonstrates various ways to use the `name` search parameter, including exact matches, contains, and prefix matching.

```APIDOC
## `name` Search Parameter

The `name` search parameter is used to match any of the string fields in a `HumanName` resource, including family, given, prefix, suffix, and/or text. A check on each field is performed separately, and a resource that has any matching field is added to the response.

#### Examples:
```javascript
import { Patient } from 'fhir/r4b';
import Oystehr from '@oystehr/sdk';

const oystehr = new Oystehr({
  accessToken: "<your access token>",
});

// corresponds to the SQL expression: LIKE "Anna Maria Juanita%"
const patients/*: Patient[]*/ = (await oystehr.fhir.search<Patient>({
  resourceType: 'Patient',
  params: [
    {
      name: 'name',
      value: 'Anna Maria Juanita',
    },
  ],
})).unbundle();

// corresponds to the SQL expression: = "Anna Maria Juanita"
const patients/*: Patient[]*/ = (await oystehr.fhir.search<Patient>({
  resourceType: 'Patient',
  params: [
    {
      name: 'name:exact',
      value: 'Anna Maria Juanita',
    },
  ],
})).unbundle();

// corresponds to the SQL expression: LIKE "%Anna Maria Juanita%"
const patients/*: Patient[]*/ = (await oystehr.fhir.search<Patient>({
  resourceType: 'Patient',
  params: [
    {
      name: 'name:contains',
      value: 'Anna Maria Juanita',
    },
  ],
})).unbundle();
```
```

--------------------------------

### Example FHIR Bundle Response

Source: https://docs.oystehr.com/oystehr/services/fhir/search

This is an example of a FHIR Bundle resource returned from a successful search query, containing matching resources and pagination links.

```json
{
  "resourceType": "Bundle",
  "type": "searchset",
  "entry": [
    {
      "fullUrl": "https://fhir-api.zapehr.com/Patient/6bbdbadf-4f60-4bdd-8c54-b37970c584b2",
      "resource": {
        "resourceType": "Patient",
        "active": true,
        "name": [
          {
            "given": ["Jon"],
            "family": "Snow"
          }
        ],
        "id": "6bbdbadf-4f60-4bdd-8c54-b37970c584b2",
        "meta": {
          "versionId": "ef4e3e20-4103-4df5-8f89-b4f49d6310b3",
          "lastUpdated": "2023-11-15T18:11:31.740Z"
        }
      },
      "search": {
        "mode": "match"
      }
    }
  ],
  "link": [
    {
      "relation": "self",
      "url": "https://testing.fhir-api.zapehr.com/Patient?_count=20&_elements=&given=Jon"
    },
    {
      "relation": "first",
      "url": "https://testing.fhir-api.zapehr.com/Patient?_count=20&_elements=&_offset=0&given=Jon"
    }
  ]
}
```

--------------------------------

### Oystehr SDK Initialization and Usage Comparison (v1, v2, v3)

Source: https://docs.oystehr.com/oystehr/core-documentation/typescript-sdk/migration-guide

Compares the initialization and usage patterns of the Oystehr SDK across versions v1, v2, and v3, highlighting the shift to a single class instance in v3.

```typescript
import { Patient } from 'fhir/r4b';

// v1
import { AppClient, FhirClient } from '@zapehr/sdk';
const fhirClient = new FhirClient({
  accessToken: '<your_access_token>',
});
const patient = await fhirClient.createResource<Patient>({ resourceType: 'Patient '});
const appClient = new AppClient({
  accessToken: '<your_access_token>',
});
const app = await appClient.getApplication('a7e25b8e-22fb-4ba2-ba9f-d0ec47825811');

// v2
import zapehr from '@zapehr/sdk';
zapehr.init({
  ZAPEHR_ACCESS_TOKEN: '<your_access_token>', // can also be provided from an environment variable
});
const patient = await zapehr.fhir.createResource<Patient>({ resourceType: 'Patient '});
const app = await zapehr.project.application.get('a7e25b8e-22fb-4ba2-ba9f-d0ec47825811');

// v3
import Oystehr from '@oystehr/sdk';
const oystehr = new Oystehr({
  accessToken: '<your_access_token>',
});
const patient = await oystehr.fhir.create<Patient>({ resourceType: 'Patient '});
const app = await oystehr.application.get('a7e25b8e-22fb-4ba2-ba9f-d0ec47825811');
```

--------------------------------

### Invite a User with the v3 SDK

Source: https://docs.oystehr.com/oystehr/services/app/users

Use this snippet to invite a new user to your project. It requires an email, application ID, and an access policy. The response includes an invitation URL that should be sent to the user.

```javascript
import Oystehr from '@oystehr/sdk';

const oystehr = new Oystehr({
  accessToken: "<your_access_token>",
});

const user = await oystehr.user.invite({
  email: 'jsnow@winterfell.com',
  applicationId: '36b974ef-e470-4f1b-9ceb-ccaf23b673bf',
  accessPolicy: {
    rule: [
      {
        resource: ['*'],
        action: ['*'],
        effect: 'Allow',
      },
    ],
  },
  resource: {
    resourceType: 'Practitioner',
  },
});
```

--------------------------------

### Onboard a Fax Number using SDK v3

Source: https://docs.oystehr.com/oystehr/services/fax/number

Use this snippet to purchase and associate a fax number with your project. Ensure you have your access token ready. The service supports only one fax number per project via this endpoint.

```javascript
import Oystehr from '@oystehr/sdk';

const oystehr = new Oystehr({
  accessToken: "<your_access_token>",
});

const response = await oystehr.fax.onboard();
```

```json
{
  "faxNumber": "+12223334444"
}
```

--------------------------------

### Initiate Async Bulk Output Search (SDK)

Source: https://docs.oystehr.com/oystehr/services/fhir/async-fhir-interactions

Initiate an asynchronous search request specifying 'async-bulk' mode. The SDK automatically handles the _outputFormat parameter. This is useful for large result sets.

```javascript
// The SDK handles the _outputFormat parameter automatically when mode is 'async-bulk'
const handle = await oystehr.fhir.search<Patient>(
  {
    resourceType: 'Patient',
    params: [{ name: 'name', value: 'Jon' }],
  },
  { mode: 'async-bulk' }
);

const status = await oystehr.fhir.waitForAsyncJob(handle.jobId, {
  pollIntervalMs: 1000,
  timeoutMs: 600000,
});

if (status.status === 200 && status.mode === 'bulk') {
  // Bulk manifest with NDJSON file URLs
  console.log(status.manifest.transactionTime);
  console.log(status.manifest.output);
  // [{ type: 'Patient', url: 'https://...' }]

  // Fetch and parse NDJSON output files.
  for (const file of status.manifest.output) {
    const response = await fetch(file.url, {
      headers: status.manifest.requiresAccessToken ? { Authorization: 'Bearer <your_access_token>' } : undefined,
    });

    if (!response.ok) {
      throw new Error(`Failed to download bulk output (${file.type}): HTTP ${response.status}`);
    }

    const ndjson = await response.text();
    const resources = ndjson
      .split('\n')
      .filter((line) => line.trim().length > 0)
      .map((line) => JSON.parse(line));

    console.log(file.type, resources.length);

    if (file.type === 'Patient') {
      const patient = resources.find((resource) => resource.resourceType === 'Patient');
      console.log('Found Patient:', patient?.id);
    }
  }
}
```

--------------------------------

### Payer (Organization) FHIR Resource Example

Source: https://docs.oystehr.com/oystehr/services/rcm/eligibility

Example of a FHIR Organization resource representing a payer. The identifier.value with a specific coding system and code is used for the Payer ID.

```json
{
  "resourceType": "Organization",
  "identifier": [
    {
      "type": {
        "coding": [
          {
            "code": "XX",
            "system": "http://terminology.hl7.org/CodeSystem/v2-0203"
          }
        ]
      },
      "value": "00803"
    }
  ],
  "name": "NY BCBS - EMPIRE",
  "id": "0d03d037-af76-4813-b228-105336238317",
  "meta": {
    "versionId": "cd116228-fcea-427e-9634-ddc6f8a77d6d",
    "lastUpdated": "2024-07-01T17:01:17.424Z"
  }
}
```

--------------------------------

### Search Medications by Name using SDK

Source: https://docs.oystehr.com/oystehr/services/erx/medication-search

Example of how to search for medications by name using the Oystehr SDK. Ensure you have your access token and the SDK is initialized.

```typescript
import Oystehr from '@oystehr/sdk';

const osytehr = new Oystehr({
  accessToken: "<your_access_token>",
});

const { medications } = await oystehr.erx.searchMedications({
  name: 'lisinopril',
});
```

--------------------------------

### Create Z3 Bucket with Python

Source: https://docs.oystehr.com/oystehr/services/z3

Use this snippet to create a new Z3 bucket. Ensure you have a valid authentication token.

```python
import requests
 
requests.put('https://project-api.zapehr.com/v1/z3/fruit-vegetables',
  headers={
    'Authorization': f"Bearer {token}"
  }
)
 
```

--------------------------------

### Example FHIR Communication Resource

Source: https://docs.oystehr.com/oystehr/services/messaging/transactional-sms

This is an example of a FHIR Communication resource automatically created when sending a Transactional SMS. It details the message content, recipient, and sending status.

```json
{
  "resourceType": "Communication",
  "status": "in-progress",
  "medium": [
    {
      "coding": [
        {
          "system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationMode",
          "code": "SMSWRIT"
        }
      ]
    }
  ],
  "sent": "2023-11-19T18:27:51.387+00:00",
  "payload": [
    {
      "contentString": "Your appointment is confirmed. We look forward to seeing you January 18, 2023 at 5:00PM EDT. To reschedule or cancel visit https://app.notarealpractice.com/visit/4xDzrJKXDOY"
    }
  ],
  "recipient": [
    {
      "reference": "Patient/51940f7e-7311-4006-b9aa-83bbc0c5b62c"
    }
  ],
  "note": [
    {
      "time": "2023-11-19T18:27:51.387+00:00",
      "text": "Message sent using Oystehr SMS"
    },
    {
      "time": "2023-11-19T18:27:51.387+00:00",
      "text": "Message sent to number: +12345678900"
    }
  ],
  "id": "d96634a9-082d-4e98-93d2-f514cde691fd",
  "meta": {
    "versionId": "1478e1d4-d4e2-49f0-a99c-8fae79e09584",
    "lastUpdated": "2023-11-19T18:27:52.121Z"
  }
}
```

--------------------------------

### Provider (Organization) FHIR Resource Example

Source: https://docs.oystehr.com/oystehr/services/rcm/eligibility

Example of a FHIR Organization resource representing a provider. Includes identifiers for NPI, Taxonomy, and Tax ID, along with address details.

```json
{
  "id": "bea1bda2-e069-4f91-ac50-be5c8f1337b2",
  "resourceType": "Organization",
  "name": "New York Care",
  "identifier": [
    {
      "type": {
        "coding": [
          {
            "code": "NPI",
            "system": "http://terminology.hl7.org/CodeSystem/v2-0203"
          }
        ]
      },
      "system": "http://hl7.org/fhir/sid/us-npi",
      "value": "1790914042"
    },
    {
      "type": {
        "coding": [
          {
            "code": "NE",
            "system": "http://terminology.hl7.org/CodeSystem/v2-0203"
          }
        ]
      },
      "value": "270309905"
    }
  ],
  "address": [
    {
      "line": [
        "16 SOME STR"
      ],
      "city": "NEW YORK",
      "state": "NY",
      "postalCode": "10087"
    }
  ],
  "telecom": [
    {
      "system": "phone",
      "value": "5168690650"
    }
  ],
  "meta": {
    "versionId": "01a7b180-7cb2-44a9-9f5e-e621440a167d",
    "lastUpdated": "2024-07-18T13:25:38.705Z"
  }
}
```

--------------------------------

### Initialize and Use Oystehr SDK

Source: https://docs.oystehr.com/oystehr/core-documentation/typescript-sdk

Import and initialize the Oystehr SDK with an access token. Then, use its functions to interact with Oystehr APIs, such as creating FHIR resources or uploading files for Zambdas. Error handling for API operations is demonstrated.

```typescript
import Oystehr from '@oystehr/sdk';
import { Patient } from 'fhir/r4b';
 
const oystehr = new Oystehr({
  accessToken: 'your_access_token',
});
 
// Create a Patient FHIR resource
const patient = await oystehr.fhir.create<Patient>({
  resourceType: 'Patient',
});
 
// Upload a zambda
try {
  const zambda = await oystehr.zambda.create({ name: 'new zambda', triggerMethod: 'http_open' });
  const fileHandle = await fs.open('./path/to/my/zambda.zip')
  const file = new Blob([await fileHandle.readFile()]);
  await oystehr.zambda.uploadFile({ id: createZambda.data.id, file, })
} catch (err) {
  // Handle error thrown by Oystehr or JS in some way
}
```
Tokens:
Raw