Iframe + draft orders quickstart

Embed the Relu viewer in your product and let your users run services on their own data.

Iframe + draft orders

Use this path when your product has its own users and you want them to run Relu services without you mediating every order.

1. Enable the iframe integration for your organization

Contact support@relu.ai to enable the iframe_integration scope for your organization. You'll get an Integrator ID.

2. Install the SDK

npm install @relu-bv/iframe-api

3. Create a draft order server-side

From your backend, call POST /orders with service_id and is_draft: true. Pre-fill whatever you already have; leave the rest for the user to complete in the iframe.

import os, requests

res = requests.post(
    "https://api.automate.relu.ai/orders",
    json={
        "service_id": "<service-uuid from GET /services>",
        "order_name": "Patient #1234",
        "is_draft": True,
        "input_data": {
            "lower_jaw": {
                "external_download_url": "https://your-storage.com/lower.stl",
                "extension": ".stl",
            }
        },
    },
    headers={"X-API-Key": os.environ["RELU_API_TOKEN"]},
).json()

order_id = res["id"]

const res = await (
  await fetch('https://api.automate.relu.ai/orders', {
    method: 'POST',
    headers: {
      'X-API-Key': process.env.RELU_API_TOKEN,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      service_id: '<service-uuid from GET /services>',
      order_name: 'Patient #1234',
      is_draft: true,
      input_data: {
        lower_jaw: {
          external_download_url: 'https://your-storage.com/lower.stl',
          extension: '.stl',
        },
      },
    }),
  })
).json();

const orderId = res.id;

If your organization must first add a payment method, this call returns 403 with detail.code set to payment_verification_required. See Coded refusals.

4. Invite the user and mint a user token

Share the draft with the end user, then mint a short-lived user token scoped to the order. See Draft order flow for the full sequence; the two API calls are POST /orders/{order_id}/share/invite and POST /connections/api-token.

5. Host the iframe

import { createViewerHost } from '@relu-bv/iframe-api';

const host = createViewerHost({
  integratorId: '<your-integrator-id>',
  container: document.getElementById('viewer')!,
  viewerUrl: 'https://automate.relu.ai',
  auth: { type: 'apiToken', token: userToken },
  onReady: (api) => api.navigate({ query: { finalize_order_id: orderId } }),
  onError: (e) => console.error(e),
});

Your user can now complete and submit the order. Poll POST /orders/job-statuses or wait for a callback to know when it is done.

Next steps

Read Draft order flow for the full flow
See the iframe integration guide for advanced config