Vital Scan API

The Vital Scan API lets your backend create a hosted assessment for a user. GOFA hosts the assessment experience and returns the result through the session API.

Workflow

1. From your server, create a session with a bearer API key.
2. Pass the returned launchUrl (also returned as vitalScanUrl) to your web application or mobile WebView, or open it in a top-level browser window.
3. Let the user complete the hosted assessment.
4. Poll the session by its vitalScanResultId until it reaches a terminal status.

The returned URL is the integration boundary for the hosted experience. Inline <iframe> embedding is not supported.

Base URL and authentication

The Production API base URL is:

https://www.gofa.app

Vital Scan is a server-to-server API. Keep your API key in your backend and do not place it in browser code, frontend bundles, mobile apps, WebViews, URLs, or public repositories. See Authentication for the required bearer header.

Do not send x-request-id. GOFA creates a request ID for every request and returns it in the x-request-id response header. Error responses also include the same value as error.requestId, so you can give it to GOFA Support without exposing credentials or user data.

For each assessment, generate an Idempotency-Key on your backend. Keep the same key and request body for retries, including retries made with a replacement API key from the same workspace.

Create a hosted session

POST /api/v1/vital-scan/sessions

The request body is strict: send only the fields documented below.

returnUrl is optional. If you use it, your workspace administrator must first add the exact HTTPS origin under Vital Scan's Allowed return origins in the customer portal (API Services → Vital Scan → Quick start). See workspace preparation. A path or query string may be included in the request URL, but credentials must not be included. If the supplied URL contains a fragment, GOFA clears it when navigating back; fragments are not preserved in the return navigation. The origin must match the approved origin.

curl --request POST 'https://www.gofa.app/api/v1/vital-scan/sessions' \
  --header 'Authorization: Bearer <GOFA_API_KEY>' \
  --header 'Idempotency-Key: 7dfdc983-1c55-49a3-99b2-238e78ef934a' \
  --header 'Content-Type: application/json' \
  --data '{
    "userId": "customer-member-123",
    "locale": "en",
    "returnUrl": "https://your-app.example/vital-scan/complete"
  }'

Replace the example return URL only with an HTTPS URL whose origin is approved in your workspace. The response to a successful request is 201 Created and includes a GOFA-generated request ID header:

HTTP/1.1 201 Created
x-request-id: <GOFA-generated-request-id>

{
  "data": {
    "vitalScanResultId": "<generated-session-id>",
    "userId": "customer-member-123",
    "status": "created",
    "createdAt": "2026-08-28T09:00:00.000Z",
    "updatedAt": "2026-08-28T09:00:00.000Z",
    "firstOpenedAt": null,
    "startedAt": null,
    "completedAt": null,
    "failedAt": null,
    "expiresAt": "2026-08-28T11:00:00.000Z",
    "returnUrl": "https://your-app.example/vital-scan/complete",
    "error": null,
    "metrics": null,
    "launchUrl": "https://www.gofa.app/vital-scan/<generated-session-id>#scanToken=<hosted-session-token>",
    "vitalScanUrl": "https://www.gofa.app/vital-scan/<generated-session-id>#scanToken=<hosted-session-token>"
  }
}

The fragment in the launch URL contains a temporary Hosted session credential. Give this URL only to the intended user for this session. Do not log or persist it, include it in analytics events, or forward it to another user. It is not an API key.

The first successful POST for an idempotency key returns 201 Created and consumes the configured Vital Scan price in credits. Replaying the same key and request in the same workspace returns the original session with 200 OK and Idempotency-Replayed: true; it does not charge again. A changed request with the same key returns 409 IDEMPOTENCY_CONFLICT. The key must contain 16–128 ASCII letters, numbers, ., _, :, or -; a UUID is suitable. Missing or invalid keys return 400 IDEMPOTENCY_KEY_INVALID. Scope is the workspace and product, so rotating the API key does not change the replay.

Hosted session lifecycle

A session can accept hosted input for two hours from creation; expiresAt is the end of that window. An unfinished session can be resumed in the same hosted experience and the user can retry the scan without creating another session or consuming more credits. If a user leaves before completion, the session remains non-terminal until it is completed or expires.

Replaying a creation request never extends expiresAt. Once the session is terminal or the window has ended, the replay keeps the original ID and returns launchUrl: null and vitalScanUrl: null.

The hosted experience can move through these states:

When the assessment completes, the GOFA hosted page shows the result. The credits used to create a session are not refunded if the session fails, expires, or the user leaves the hosted flow.

If you provide an approved returnUrl, an ordinary hosted session offers a return action after completion. If the user exits the hosted flow before completion, GOFA navigates to the URL immediately. GOFA navigates to that URL with these query parameters:

• vital_scan_session_id: the session ID.
• status: completed or exited.

The return URL does not receive a bearer token or health data, and the hosted token fragment is removed before navigation. Without a returnUrl, the user stays on the GOFA hosted completion or exit page.

Treat the return query parameters as navigation hints, not trusted result data. Your backend must verify the session with GET and associate it with the correct signed-in user. An exited return does not mean the session is failed.

Browser, camera, and WebView checklist

• Open the complete HTTPS vitalScanUrl, including its token fragment, in a top-level browser or camera-capable WebView. Do not strip the fragment, embed the page in an iframe, or append your Commercial API key.
• Allow camera access when prompted. For a native WebView, the host application must handle the operating system's camera permissions as well as the WebView's web-content permission requests. Permission denial needs a clear recovery path or an option to open the session in the system browser.
• Keep the page foregrounded during capture and follow the hosted page's face positioning and lighting instructions. Test backgrounding, returning to the page, and camera interruptions on the devices you intend to support.
• Test camera allow/deny, completion, early exit, reopening the same session, expiry, and return navigation in your actual browser or embedded app. Include iOS Safari, Android Chrome, and your WKWebView or Android WebView if those are part of your product's device matrix.

This is an integration acceptance checklist, not a certified browser/version support matrix. The public API contract does not guarantee every embedded browser or OS version. Confirm your target device matrix with GOFA before rollout.

Read a session and result

GET /api/v1/vital-scan/sessions/{vitalScanResultId}

Reading a session does not consume credits, but it still requires valid bearer authentication and is subject to the configured requests-per-minute limit. The same session may be polled no more than once every five seconds. A poll that is too soon returns 429; wait for the Retry-After response header before polling again.

Any active API key owned by the same workspace can read its session; the key that created it is not required. Workspace access can still be disabled.

curl --request GET \
  'https://www.gofa.app/api/v1/vital-scan/sessions/<vitalScanResultId>' \
  --header 'Authorization: Bearer <GOFA_API_KEY>'

For example, an in-progress session returns 200 OK with metrics: null:

{
  "data": {
    "vitalScanResultId": "<generated-session-id>",
    "userId": "customer-member-123",
    "status": "in_progress",
    "createdAt": "2026-08-28T09:00:00.000Z",
    "updatedAt": "2026-08-28T09:01:05.000Z",
    "firstOpenedAt": "2026-08-28T09:00:30.000Z",
    "startedAt": "2026-08-28T09:00:45.000Z",
    "completedAt": null,
    "failedAt": null,
    "expiresAt": "2026-08-28T11:00:00.000Z",
    "returnUrl": null,
    "error": null,
    "metrics": null
  }
}

The response DTO contains:

Result fields and missing values

Every measurement field, including nested fields, is optional. Unavailable fields are omitted, not populated with zero. A completed session may have metrics: null if no SDK result is stored, or an empty/partial metrics object. Do not assume completion guarantees any particular measurement. Check for a numeric value explicitly rather than using a truthiness check: zero and missing are different. Field names are case-sensitive.

For advanced SDK fields without an explicit unit or scale above, confirm the unit, interpretation, and availability with GOFA before displaying them to customers. This reference specifies the transport shape, not diagnostic thresholds or clinical interpretation. Internal SDK quality fields and raw capture data are not part of the public metrics response.

Completed response example

This synthetic example includes the full session envelope and a partial set of measurements. Values illustrate JSON structure, not expected ranges or guaranteed outputs. GET does not return vitalScanUrl or its temporary credential.

{
  "data": {
    "vitalScanResultId": "<generated-session-id>",
    "userId": "customer-member-123",
    "status": "completed",
    "createdAt": "2026-08-28T09:00:00.000Z",
    "updatedAt": "2026-08-28T09:02:00.000Z",
    "firstOpenedAt": "2026-08-28T09:00:30.000Z",
    "startedAt": "2026-08-28T09:00:45.000Z",
    "completedAt": "2026-08-28T09:02:00.000Z",
    "failedAt": null,
    "expiresAt": "2026-08-28T11:00:00.000Z",
    "returnUrl": "https://your-app.example/vital-scan/complete",
    "error": null,
    "metrics": {
      "hr": 72,
      "hrv": 42.5,
      "sbp": 118,
      "dbp": 76,
      "spo2": 98,
      "rr": 16,
      "hrv_indices": { "RMSSD": 38.2, "SDNN": 42.5 },
      "ANSIndex": { "PNS": 0.4, "SNS": -0.2 },
      "PRQ": 4.5
    }
  }
}

The API is addressed by vitalScanResultId; it does not provide a list, search, or webhook endpoint. The public contract does not promise a generic retention period, so keep the identifier and any application records you need in your own systems.

Session removal

This public API has no session deletion operation. DELETE on the single session path returns 405 Method Not Allowed. Keep your own application records according to your policies; leaving or expiring does not refund the creation charge.

Errors and request IDs

All responses include a GOFA-generated x-request-id. For errors from the common API access boundary, the JSON envelope is:

{
  "error": {
    "code": "<public-error-code>",
    "message": "<human-readable-message>",
    "requestId": "<GOFA-generated-request-id>"
  }
}

The current public codes are:

Errors returned by the GET handler use the same JSON envelope shape but intentionally return only error.message and error.requestId; those handler responses do not promise an error.code for 404, the per-session polling 429, or route 500 responses. The common access boundary can still return the codes listed above before a handler runs. The per-session 429 message explains the five-second polling interval and includes Retry-After. This is distinct from the common requests-per-minute rate_limit_exceeded response.

Rate limits and charging

• A first successful session creation (POST with 201) consumes the current Vital Scan price in credits; an idempotent 200 replay does not charge again.
• GET requests do not consume credits.
• POST and GET are subject to the configured requests-per-minute protection and may return the standard rate-limit headers.
• Use a new idempotency key only for a genuinely new assessment; a replay retains the original two-hour deadline.

For an end-to-end walkthrough, see Quick Start. For the authentication boundary and retry guidance, see Authentication and Errors & limits.