Skip to main content

Nervoscan REST API

Use the Nervoscan REST API to authenticate, create a scan job, upload a video, monitor job status, and fetch final results for contactless vital‑sign analysis.

Base URL​

  • https://backend.nervoscan.com

All paths below are relative to the base URL.

1) Authenticate​

Obtain a short‑lived bearer token using your username and password.

  • Method: POST
  • Path: /clientlogin
  • Headers:
    • Content-Type: application/json
  • Request Body (JSON):
{
  "username": "<USERNAME>",
  "password": "<PASSWORD>"
}
  • Response (JSON):
{ 
    "success": true,
    "access_token": "<ACCESS_TOKEN>",
    "refresh_token": "<REFRESH_TOKEN>",
}

2) Create a Job (Get API Key)​

Request a job/API key you will use for uploading and tracking.

  • Method: POST
  • Path: /clientgeturl
  • Headers:
    • Authorization: Bearer <ACCESS_TOKEN>
    • Content-Type: application/json
  • Request Body (JSON):
{
  "host_name": "www.nervoscan.com"
}
  • Response (JSON):
{ "url": "https://.../scan?api_key=<JOB_ID>" }

Extract <JOB_ID> from the api_key query parameter. Always use the host name as www.nervoscan.com unless you have a custom domain name setup with our team.

3) Upload Video​

Upload the recorded video for processing.

  • Method: POST
  • Path: /submitscan
  • Headers:
    • Authorization: Bearer <ACCESS_TOKEN>
    • Content-Type: multipart/form-data
  • Body (multipart/form-data):
    • file: the video file (binary). Recommended content type: video/mp4.
    • data: a JSON string with the following structure:
{
  "uuid": "<JOB_ID>",
  "meta_data": {}
}
  • Response: JSON acknowledgment of submission.

Notes

  • uuid must match the <JOB_ID> from step 2 Create a Job.
  • meta_data is optional and can be used to pass custom information.

4) Check Job Status​

Poll for job status until the job completes or fails.

  • Method: POST
  • Path: /check
  • Headers:
    • Authorization: Bearer <ACCESS_TOKEN>
    • Content-Type: application/json
  • Request Body (JSON):
{ "api_key": "<JOB_ID>" }
  • Response (JSON):
{ "job_status": "Pending" }

Possible values: Pending, Completed, Failed.

5) Fetch Final Results​

After status is Completed, fetch the final averaged results.

  • Method: POST
  • Path: /getcustomerinfo
  • Headers:
    • Authorization: Bearer <ACCESS_TOKEN>
    • Content-Type: application/json
  • Request Body (JSON):
{
  "mode": "selection",
  "api_keys": ["<JOB_ID>"]
}
  • Response (JSON): Final results payload for the specified job.

Error Handling​

Common error codes/messages you may encounter in responses:

  • INVALID_USERNAME, INVALID_PASSWORD: invalid credentials
  • NO_SCANS_AVAILABLE or messages like "No scans available!" / "No packages available!": plan limit reached
  • INVALID_CONTENT_TYPE: incorrect upload headers/body
  • JOB_NOT_REGISTERED: job missing/expired

All endpoints return standard HTTP status codes with a JSON error body.

Implementation Notes​

  • Always use HTTPS and store tokens securely.
  • Videos should be clear, well‑lit, and front‑facing for best results.
  • For real‑time streaming and live window results, use the JS SDK, which manages streaming and live results for you.