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 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.

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 '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",
    "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,
    "vitalScanUrl": "https://www.gofa.app/vital-scan/<generated-session-id>#scanToken=<hosted-session-token>"
  }
}

The fragment in vitalScanUrl 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.

Every successful POST creates a new independent session and consumes one available point. Sending the same body again creates another session and consumes another point. The endpoint does not support a customer-supplied idempotency key.

Hosted session lifecycle

A session is valid 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 another point. If a user leaves before completion, the session remains non-terminal until it is completed or expires.

The hosted experience can move through these states:

When the assessment completes, the GOFA hosted page shows the result. The point used to create a session is not refunded if the session fails, expires, or the user leaves the hosted flow. Deleting a session is also not a refund.

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 a point, but it still requires 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.

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",
    "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",
    "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.

Delete a session

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

Deletion is free and returns 204 No Content when the session belongs to your workspace. It is a soft delete: subsequent access to that session returns 404, and the original point is not refunded.

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

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 and DELETE handlers 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 successful session creation (POST with 201) consumes one point.
• GET and DELETE requests do not consume points.
• All three operations are subject to the configured requests-per-minute protection and may return the standard rate-limit headers.
• A new POST is always a new session; no customer idempotency key is available.

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