App Integration guide

FAMILIARIZE YOURSELF WITH HINT API

Before integrating with Hint, you need to understand our API architecture and authentication patterns.

INSTANT ON VIA OAUTH

Documentation: https://developers.hint.com/docs/instanton-via-oauth

Instant On allows users to instantly provide your application with API credentials without them needing to manually send you API keys.

MAKING API REQUESTS

Documentation: https://developers.hint.com/docs/making-requests

Hint uses RESTful APIs with Bearer Auth authentication:

Example API request:

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



const patients = await response.json();

Key Points: • All requests require Authorization: Bearer {token} header • Use HTTPS for all communications • API responses are JSON formatted • Rate limiting applies (see documentation for limits)

WEBHOOKS FOR REAL-TIME UPDATES

Documentation: https://developers.hint.com/docs/webhooks

Receive real-time notifications when data changes in Hint:

Example webhook endpoint:

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



  switch (type) {
    case 'patient.created':
      handle_patient_created(object)
      break;
    case 'patient.updated':
      handle_patient_updated(object)
      break;
    case 'patient.destroyed:
      handle_patient_destroyed(object)
      break;
  }



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

AUTHENTICATE VIA HANDSHAKE

The handshake establishes secure communication between your application and Hint.

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 a handshake url, Hint will initiate the handshake there by sending the following payload

{
  "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",
}

app.post("/handshake", (req, res) => {
  const signature = req.headers["x-hint-signature"];
  const payload = req.body;


  const sessionKey = generateSessionKey(payload);


  return res.json({ session_key: sessionKey });
});

The signature is validated the same way to webhooks

CONFIGURE IFRAME

Your application must be embeddable within Hint’s interface.

TECHNICAL SPECIFICATIONS

Requirement	Specification
Dimensions	1024px x 768px, fixed
Responsive Behavior	Scale gracefully within bounds
Communication	We’ll provide an SDK

Once the handshake is complete and we have received a session_key, we’ll load the partner app inside an iframe. The partner must provide us with a url that can be framed. We’ll append the session_key as a query parameter when embedding.

MAP TO API ENDPOINTS FOR CLINICAL INTERACTIONS

Create and manage clinical interactions within Hint's system.

CREATE CLINICAL INTERACTION

Documentation: https://developers.hint.com/reference/interactioncreateinteraction#/

Create a new partner interaction, this how the user will return to your iframe.

const createInteraction = async (patientId, noteData) => {
  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 await response.json();
};

UPDATE CLINICAL INTERACTION

Documentation: https://developers.hint.com/reference/partnerinteractionupdatepartnerinteraction#/

const updateInteraction = async (noteId, 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({
      status: ‘signed’,
    })
  });



  return await response.json();
};