Forms, Payments & Notes Workflow

This guide chains the Forms, Notes, and Billing APIs into one intake-to-checkout integration. A patient fills out a form (which saves a card on file), that form becomes a note template, a provider’s note pre-fills from the patient’s answers, and you collect payment on an itemized charge through the embedded payment component.

Overview

Create a form and convert it into a note template so the note layout matches the form.
Save a payment method for the patient (or collect one through the form’s Payment Methods block).
Submit the form for the patient — answers flow into the patient record.
Create a note pre-filled with the patient’s submitted answers.
Create a charge with itemized line items that reference catalog items.
Collect payment through the embedded payment component.

All amounts are in cents. Every request needs the TENANT and API-KEY headers.

Step 1: Create a form and its note template

Create the form the patient will fill out with Create Form, then convert it into a note template with Create Note Template From Form. The conversion flattens the form’s blocks and questions into template fields (signature, payment, disclaimer, statement, and document questions are skipped).

# Create the form
curl -X POST "https://api.decodahealth.com/forms" \
     -H "API-KEY: YOUR_API_KEY" \
     -H "TENANT: YOUR_TENANT" \
     -H "Content-Type: application/json" \
     -d '{ "name": "New Patient Intake", "blocks": [] }'

# Convert it into a note template (form_id from the response above)
curl -X POST "https://api.decodahealth.com/notes/templates/from-form/form_xxx" \
     -H "API-KEY: YOUR_API_KEY" \
     -H "TENANT: YOUR_TENANT" \
     -H "Content-Type: application/json" \
     -d '{ "includeBlockNames": true }'

import requests

BASE_URL = "https://api.decodahealth.com"
headers = {
    "API-KEY": "YOUR_API_KEY",
    "TENANT": "YOUR_TENANT",
    "Content-Type": "application/json",
}

form = requests.post(
    f"{BASE_URL}/forms",
    headers=headers,
    json={"name": "New Patient Intake", "blocks": []},
).json()
form_id = form["id"]

template = requests.post(
    f"{BASE_URL}/notes/templates/from-form/{form_id}",
    headers=headers,
    json={"includeBlockNames": True},
).json()
template_id = template["id"]

import ky from "ky";

const BASE_URL = "https://api.decodahealth.com";
const headers = { "API-KEY": "YOUR_API_KEY", TENANT: "YOUR_TENANT" };

const form = await ky.post(`${BASE_URL}/forms`, {
  headers,
  json: { name: "New Patient Intake", blocks: [] },
}).json<any>();
const formId = form.id;

const template = await ky.post(`${BASE_URL}/notes/templates/from-form/${formId}`, {
  headers,
  json: { includeBlockNames: true },
}).json<any>();
const templateId = template.id;

Build the form’s blocks with Demographics, Medical History, and Measurement fields where you want answers to flow into the patient record — those are the fields that pre-fill the note later. See Form Structure Reference for block and question types, and the Form Editor if you’d rather build the form in the console and just reference its ID here.

Step 2: Save a payment method

Collect a card for the patient with Create Payment Method. The patient_id goes in the query string. You can also collect the card inside the form itself by adding a Payment Methods block — see Payment Method Collection.

curl -X POST "https://api.decodahealth.com/user/patient/payment-methods/create?patient_id=pat_xxx" \
     -H "API-KEY: YOUR_API_KEY" \
     -H "TENANT: YOUR_TENANT" \
     -H "Content-Type: application/json" \
     -d '{ "token": "PAYMENT_PROCESSOR_TOKEN" }'

payment_method = requests.post(
    f"{BASE_URL}/user/patient/payment-methods/create",
    headers=headers,
    params={"patient_id": "pat_xxx"},
    json={"token": "PAYMENT_PROCESSOR_TOKEN"},
).json()

const paymentMethod = await ky.post(
  `${BASE_URL}/user/patient/payment-methods/create`,
  {
    headers,
    searchParams: { patient_id: "pat_xxx" },
    json: { token: "PAYMENT_PROCESSOR_TOKEN" },
  },
).json<any>();

See the Create Payment Method reference for the exact request body your processor integration expects.

Step 3: Submit the form

Submit the patient’s answers with Patient Form Submission. Each entry in blocks carries a blockType (DEMOGRAPHICS, MEDICAL_HISTORY, PAYMENT_METHODS, INSURANCE, or DYNAMIC). Set isCompleteSubmission to true for a finished submission. Answers mapped to patient-record fields save to the chart automatically.

curl -X PUT "https://api.decodahealth.com/forms/form_xxx/submit" \
     -H "API-KEY: YOUR_API_KEY" \
     -H "TENANT: YOUR_TENANT" \
     -H "Content-Type: application/json" \
     -d '{
       "patientId": "pat_xxx",
       "isCompleteSubmission": true,
       "blocks": []
     }'

requests.put(
    f"{BASE_URL}/forms/{form_id}/submit",
    headers=headers,
    json={
        "patientId": "pat_xxx",
        "isCompleteSubmission": True,
        "blocks": [],  # SubmittedDemographicsBlock, SubmittedDynamicBlock, etc.
    },
)

await ky.put(`${BASE_URL}/forms/${formId}/submit`, {
  headers,
  json: {
    patientId: "pat_xxx",
    isCompleteSubmission: true,
    blocks: [], // SubmittedDemographicsBlock, SubmittedDynamicBlock, etc.
  },
});

Step 4: Create a pre-filled note

Fetch the patient’s pre-filled answers for the template with Get Prefilled Answers, then pass them straight into Create Note. The prefill response returns each answer keyed by questionId, in the exact shape answers expects.

# Fetch pre-filled answers
curl -X GET "https://api.decodahealth.com/notes/templates/tpl_xxx/prefill/pat_xxx" \
     -H "API-KEY: YOUR_API_KEY" \
     -H "TENANT: YOUR_TENANT"

# Create the note with those answers
curl -X POST "https://api.decodahealth.com/notes/create" \
     -H "API-KEY: YOUR_API_KEY" \
     -H "TENANT: YOUR_TENANT" \
     -H "Content-Type: application/json" \
     -d '{
       "patientId": "pat_xxx",
       "providerId": "prov_xxx",
       "answers": [
         { "questionId": "q_xxx", "data": { "value": "..." } }
       ]
     }'

prefill = requests.get(
    f"{BASE_URL}/notes/templates/{template_id}/prefill/pat_xxx",
    headers=headers,
).json()

answers = [
    {"questionId": a["questionId"], "data": a["data"]}
    for a in prefill["prefilledAnswers"]
]

note = requests.post(
    f"{BASE_URL}/notes/create",
    headers=headers,
    json={
        "patientId": "pat_xxx",
        "providerId": "prov_xxx",
        "template": template,   # from Step 1
        "answers": answers,
    },
).json()

const prefill = await ky.get(
  `${BASE_URL}/notes/templates/${templateId}/prefill/pat_xxx`,
  { headers },
).json<any>();

const answers = prefill.prefilledAnswers.map((a: any) => ({
  questionId: a.questionId,
  data: a.data,
}));

const note = await ky.post(`${BASE_URL}/notes/create`, {
  headers,
  json: {
    patientId: "pat_xxx",
    providerId: "prov_xxx",
    template, // from Step 1
    answers,
  },
}).json<any>();

Prefill response:

{
  "templateId": "tpl_xxx",
  "patientId": "pat_xxx",
  "prefilledAnswers": [
    { "questionId": "q_weight", "data": { "value": 165 }, "source": "Today's Measurement" },
    { "questionId": "q_allergies", "data": { "values": ["Penicillin"] }, "source": "Patient Record" }
  ]
}

Only questions mapped to the patient chart (demographics, medical history, and same-day measurements) come back pre-filled. Weight and height only pre-fill when a measurement was recorded the same day. Custom free-text questions convert to empty note fields — fill those in the note itself or with AI Scribe.

Step 5: Create an itemized charge

Create your catalog items once with Create Item, then reference each item’s id as itemId on the charge’s line items. Build the charge with Create Charge — set totalOutstanding to the sum of the line items minus any discounts.

# Create a catalog item (reusable across charges)
curl -X POST "https://api.decodahealth.com/inventory/items/create" \
     -H "API-KEY: YOUR_API_KEY" \
     -H "TENANT: YOUR_TENANT" \
     -H "Content-Type: application/json" \
     -d '{ "name": "Consultation", "price": 10000 }'

# Create the charge, linking line items to the catalog item
curl -X POST "https://api.decodahealth.com/billing/payment-terminal/charge/create" \
     -H "API-KEY: YOUR_API_KEY" \
     -H "TENANT: YOUR_TENANT" \
     -H "Content-Type: application/json" \
     -d '{
       "patientId": "pat_xxx",
       "totalOutstanding": 8500,
       "items": [
         {
           "itemId": "item_xxx",
           "name": "Consultation",
           "quantity": 1,
           "price": 10000,
           "discountAmount": 1500
         }
       ]
     }'

item = requests.post(
    f"{BASE_URL}/inventory/items/create",
    headers=headers,
    json={"name": "Consultation", "price": 10000},
).json()

charge = requests.post(
    f"{BASE_URL}/billing/payment-terminal/charge/create",
    headers=headers,
    json={
        "patientId": "pat_xxx",
        "totalOutstanding": 8500,
        "items": [
            {
                "itemId": item["id"],
                "name": "Consultation",
                "quantity": 1,
                "price": 10000,
                "discountAmount": 1500,
            }
        ],
    },
).json()
charge_id = charge["id"]

const item = await ky.post(`${BASE_URL}/inventory/items/create`, {
  headers,
  json: { name: "Consultation", price: 10000 },
}).json<any>();

const charge = await ky.post(
  `${BASE_URL}/billing/payment-terminal/charge/create`,
  {
    headers,
    json: {
      patientId: "pat_xxx",
      totalOutstanding: 8500,
      items: [
        {
          itemId: item.id,
          name: "Consultation",
          quantity: 1,
          price: 10000,
          discountAmount: 1500,
        },
      ],
    },
  },
).json<any>();
const chargeId = charge.id;

Already have a cart? Convert Cart to Charge is an alternative that carries the cart’s items and discounts onto the charge. See Payment Embed: Itemized Charges for that path.

Step 6: Collect payment in the embedded component

Point the embedded payment component at the charge. The embed calls Create Embed Payment Config with the charge_id, shows the full itemized breakdown, and applies the payment to the existing charge — no duplicate charge is created.

<iframe
  src="https://app.decodahealth.com/your-tenant/embed/pay/pat_xxx?charge_id=chg_xxx&allowedMethods=CARD"
  width="100%"
  height="500"
  allow="payment"
  style="border: none; border-radius: 8px;"
></iframe>

Listen for the outcome via postMessage:

window.addEventListener('message', function (event) {
  if (event.data.type === 'payment_success') {
    console.log('Payment successful:', event.data.payinId);
  } else if (event.data.type === 'payment_failure') {
    console.log('Payment failed:', event.data.error);
  }
});

The embed URL accepts allowedMethods (CARD, ACH, APPLE_PAY), theme (light / dark), and showSummary. See Payment Embed: Itemized Charges for the full parameter list and event reference.

Next steps

Webhook Events — get notified when forms are submitted and payments succeed instead of polling.
Payment Embed: Itemized Charges — the embedded payment component in depth.
Patient Onboarding Workflow — create the patient and book the appointment that precede this flow.

Getting Started

API Guides

Patient Management

Billing & Payments

Catalog & Inventory

Growth

Clinical & Scheduling

Platform

Forms, Payments & Notes Workflow

Forms, Payments & Notes Workflow

Overview

Step 1: Create a form and its note template

Step 2: Save a payment method

Step 3: Submit the form

Step 4: Create a pre-filled note

Step 5: Create an itemized charge

Step 6: Collect payment in the embedded component

Next steps

​Forms, Payments & Notes Workflow

​Overview

​Step 1: Create a form and its note template

​Step 2: Save a payment method

​Step 3: Submit the form

​Step 4: Create a pre-filled note

​Step 5: Create an itemized charge

​Step 6: Collect payment in the embedded component

​Next steps

Forms, Payments & Notes Workflow

Overview

Step 1: Create a form and its note template

Step 2: Save a payment method

Step 3: Submit the form

Step 4: Create a pre-filled note

Step 5: Create an itemized charge

Step 6: Collect payment in the embedded component

Next steps