Prerequisites

1. An application and an access credential

SOFT Integration is consumed with the same credentials as the rest of the AI Services: an APP Id and an API Key associated with your registered application.

If you do not have an application registered yet, follow the procedure described in Credentials.

2. The GENESIS-SOFT-INTEGRATION permission

Each API Key carries a set of permissions that determine which services it can consume. To issue SOFT Integration signatures, the API Key must hold the GENESIS-SOFT-INTEGRATION permission.

3. An access token

Every REST call in this section is authenticated with a Bearer token obtained from /api/v1/token, exactly as for the rest of the AI Services:

1. Concatenate APP Id and API Key separated by :.
2. Encode the result in base64.
3. Send it as Authorization: Basic <token> to /api/v1/token.

const token = btoa(`${appId}:${apiKey}`);

const response = await fetch(
  "https://api-suite.invoxmedical.com/api/v1/token",
  {
    method: "POST",
    headers: { Authorization: `Basic ${token}` },
    body: JSON.stringify({ grant_type: "client_credentials" }),
  },
);

const { accessToken } = await response.json();

using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

var token = Convert.ToBase64String(
    Encoding.UTF8.GetBytes($"{appId}:{apiKey}"));

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Basic", token);

var content = new StringContent(
    "{\"grant_type\":\"client_credentials\"}", Encoding.UTF8, "application/json");

var response = await client.PostAsync(
    "https://api-suite.invoxmedical.com/api/v1/token", content);

using var doc = JsonDocument.Parse(await response.Content.ReadAsStringAsync());
var accessToken = doc.RootElement.GetProperty("accessToken").GetString();

import java.net.URI;
import java.net.http.*;
import java.util.Base64;
import com.fasterxml.jackson.databind.ObjectMapper;

String token = Base64.getEncoder()
    .encodeToString((appId + ":" + apiKey).getBytes());

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api-suite.invoxmedical.com/api/v1/token"))
    .header("Authorization", "Basic " + token)
    .POST(HttpRequest.BodyPublishers.ofString(
        "{\"grant_type\":\"client_credentials\"}"))
    .build();

HttpResponse<String> response = client.send(
    request, HttpResponse.BodyHandlers.ofString());

String accessToken = new ObjectMapper()
    .readTree(response.body()).get("accessToken").asText();

import base64
import requests

token = base64.b64encode(f"{app_id}:{api_key}".encode()).decode()

response = requests.post(
    "https://api-suite.invoxmedical.com/api/v1/token",
    headers={"Authorization": f"Basic {token}"},
    json={"grant_type": "client_credentials"},
)

access_token = response.json()["accessToken"]

The access token is valid for two hours. The full procedure is described in Credentials.

4. Physicians registered in the platform

SOFT Integration does not create users. Every physician you open a consultation for must already exist in your Invox Medical organization, be enabled, and be identified by the same email address you send in the signature request.

Users are created from the administration console or through Invite user.

5. Optional: a notification channel

Decide how you want to be told that a consultation has finished:

• Webhook — configure the OnMedicalReportFinished destination for your organization. SOFT Integration reuses that event.
• WebSocket — no configuration needed; you open the connection with the same signature.

Both channels can be used at the same time. See Notifications overview.