App Best Practices

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.

Security and PHI handling

• Treat the handshake access_token as a secret and scope it to the session (do not log it).
• Verify X-Hint-Signature for the handshake payload using Webhooks Security.
• Avoid storing or logging PHI unless you need it for the workflow. Prefer using IDs and fetching details on demand.