Skip to main content

​
Prerequisites

  • Valid partner credentials (partner_id, partner_secret, organization_id, organization_secret)
  • Parchment SSO Integration: You must first set up Parchment SSO before implementing iframe embedding
  • Your domain needs to be whitelisted in Parchment’s environments

​
Implementation Steps

​
1. Generate SSO Token with Embed Path

When generating an SSO token for iframe embedding, use the /embed/ prefix in your redirect path:
🚀 API Endpoint 
POST /v1/sso
Headers:
  • x-partner-id: Your partner ID
  • x-partner-secret: Your partner secret
  • x-organization-id: Target organization ID
  • x-organization-secret: Organization secret
  • x-user-id: Parchment user ID to authenticate
  • Content-Type: application/json
Request Body: 
{
  "redirect_path": "/embed/patients/f03b972b-53ea-452d-ae48-024817f6c3b0/prescriptions"
}
Important: The /embed/ prefix in the redirect_path tells Parchment to render the page in iframe-optimized mode, removing navigation elements and adjusting the layout for embedded display.

​
Available Embed Paths

PathDescription
/embed/patients/{patient_id}/prescriptionsPrescription form for a specific patient. Main entry point for creating new prescriptions.
/embed/patients/{patient_id}/prescriptions/{prescription_id}View or manage an existing prescription for a patient.
/embed/prescriptions/approvalApproval dashboard for reviewing, approving, amending, or rejecting queued prescriptions.
Response: 
{
  "success": true,
  "data": {
    "sso_token": "eyJ...",
    "redirect_url": "https://portal.parchment.health/auth/sso?token=eyJ...&redirect=%2Fembed%2Fpatients%2F...",
    "expires_in": 300
  }
}

​
Query Parameters

The prescription form (/embed/patients/{patient_id}/prescriptions) accepts query parameters to pre-fill fields and to pass partner data through to webhooks. Append them to the redirect_path when generating the SSO token — they are preserved through the SSO redirect onto the embedded page: 
{
  "redirect_path": "/embed/patients/f03b972b-53ea-452d-ae48-024817f6c3b0/prescriptions?custom_drug_id=DRUG%2342&quantity=2&reserved_1=ORDER-9087"
}
URL-encode all values (e.g. a space becomes %20, # becomes %23).

​
Pre-fill parameters

ParameterTypeConstraintsDescription
custom_drug_idstringnon-emptySelects a custom drug from the organization catalog as the medication.
quantityinteger1–99Quantity to dispense.
repeatsinteger0–99Number of repeats.
repeats_intervalinteger1–365Minimum interval (days) between repeats.
patient_instructionsstring≤ 250 charsDirections for the patient. Longer values are truncated.
doctor_instructionsstring≤ 50 charsNote for the dispenser. Longer values are truncated.
Invalid numeric values are ignored (a warning is shown in the form); over-length text is truncated.

​
Reserved parameters

Opaque pass-through values for partner use. They are shown read-only on the form and delivered on the resulting webhook in the top-level metadata object (see Webhook Events).
ParameterTypeConstraintsDescription
reserved_1string≤ 30 charsReserved partner data. Longer values are truncated.
reserved_2string≤ 30 charsReserved partner data. Longer values are truncated.
reserved_3string≤ 30 charsReserved partner data. Longer values are truncated.
Each reserved field is independent of the pre-fill precedence above. A field only appears on the form (and is forwarded to the webhook) when it is present and non-empty; absent fields are delivered as null.

​
2. Embed in Your Application

Use the returned redirect_url as the iframe source: 
<iframe
  src={iframeUrl}
  className="absolute inset-0 size-full border-0"
  allow="clipboard-write; publickey-credentials-get *; publickey-credentials-create *"
  referrerPolicy="strict-origin-when-cross-origin"
  title="Parchment Portal"
/>

​
Result

Parchment embedded iframe example