App Integration guide

This guide walks through everything required to embed your application inside Hint Marketplace: core API familiarity, the marketplace handshake, iframe requirements, and clinical interaction endpoints.

Familiarize yourself with the Hint API

Before touching the marketplace surface, make sure your team understands Hint's authentication and integration patterns.

InstantOn via OAuth

Review InstantOn via OAuth. InstantOn eliminates manual API key sharing and is the only approved way for practices to grant you access.

Making API requests

Study Making Requests for language examples, Bearer authentication, and environment guidance. Every request must include Authorization: Bearer {token} headers and use HTTPS.

const response = await fetch('https://api.hint.com/v1/provider/patients', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
    Accept: 'application/json'
  }
});

const patients = await response.json();

Webhooks for real-time updates

Use Webhooks to subscribe to lifecycle events and validate signatures before processing.

app.post('/webhook/hint', (req, res) => {
  const { type, object } = req.body;

  switch (type) {
    case 'patient.created':
      handlePatientCreated(object);
      break;
    case 'patient.updated':
      handlePatientUpdated(object);
      break;
    case 'patient.destroyed':
      handlePatientDestroyed(object);
      break;
    default:
      break;
  }

  res.status(200).send('ok');
});

Authenticate via handshake

The marketplace handshake establishes a secure session between Hint and your iframe.

Custom Roles

Hint offers a way for your app to define custom roles that can later be manually assigned to each user of the practice by a practice admin. The assigned roles will be sent in the handshake payload. You can configure your custom roles here by clicking the "Edit" button.

STEP 1: Initialize Handshake

Provide Hint with a handshake URL. We'll POST a payload containing the user, practice, integration, and a scoped access token.

{
  "timestamp":"2025-10-30T14:20:19.316986-03:00",
  "user":{
    "id":"user-BtAH8TTXCo6P",
    "email":"[email protected]",
    "first_name":"Agustin",
    "last_name":"Gomez",
    "name":"Agustin Gomez",
    "partner_roles": ["admin"]
  },
  "practice": {
    "id": "pra-cmVPOcw7hcIs",
    "name": "Zak's Test Practice"
  },
  "integration": {
    "id": "int-MicbNQhj6hsv"
  },
  "access_token": "lo40kQDzotPRcmyEo8FuWtd92jd3BZsszbt3"
}

Verify the X-Hint-Signature header exactly as described in Webhooks Security.

Step 2: Issue a session key

Return a session_key that represents the new iframe session.

app.post('/handshake', (req, res) => {
  const signature = req.headers['x-hint-signature'];
  verifySignature(signature, req.body); // reuse your webhook helper

  const sessionKey = generateSessionKey(req.body); // your logic
  res.json({ session_key: sessionKey });
});

flowchart LR
    HintUI[Hint UI<br/>opens marketplace app] --> Handshake[Partner /handshake endpoint]
    Handshake -->|Validate signature + return session_key| HintUI
    HintUI -->|Embed iframe?session_key=...| PartnerIframe[Partner iframe URL]
    PartnerIframe -->|Use session_key + Hint SDK| HintAPIs[Hint APIs]
    classDef node fill:#ffffff,stroke:#7c3aed,stroke-width:1px,color:#0f172a,font-size:12px
    class HintUI,Handshake,PartnerIframe,HintAPIs node

Configure the iframe

Your application must render within the Hint UI cleanly.

Once the handshake succeeds, Hint loads your iframe and appends the session_key as a query parameter. That key is required to initialize the Hint Marketplace JS SDK.

Map to clinical interaction endpoints

Use clinical interactions to let users jump between Hint and your embedded experience.

Create a clinical interaction

Reference Create Partner Interaction. Interactions provide a durable pointer for the user to reopen your iframe later.

const createInteraction = async patientId => {
  const response = await fetch(
    `https://api.hint.com/v1/provider/patients/${patientId}/interactions`,
    {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${accessToken}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        type: 'partner',
        status: 'draft'
      })
    }
  );

  return response.json();
};

Update a clinical interaction

Use Update Partner Interaction to update the interaction state (e.g., signed vs. draft) when your workflow completes.

const updateInteraction = async (patientId, interactionId, updates) => {
  const response = await fetch(
    `https://api.hint.com/v1/provider/patients/${patientId}/interactions/${interactionId}`,
    {
      method: 'PATCH',
      headers: {
        Authorization: `Bearer ${accessToken}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(updates)
    }
  );

  return response.json();
};

Integrate with the Hint UI

Use the Hint Marketplace JS SDK to detect the current patient, respond to navigation changes, and close the iframe when your workflow ends. The SDK also exposes deep-link helpers (queryParams, fragment) so you can drive consistent navigation between Hint users.

Testing your integration

Run end-to-end scenarios in the staging tenant before requesting production enablement.

Test URL: https://app.staging.hint.com