Get Form - Documentation

Get Form

curl --request GET \
  --url https://api.usecobalt.com/v1/forms/{id} \
  --header 'access_token: <api-key>' \
  --header 'client_id: <api-key>' \
  --header 'client_secret: <api-key>'

import requests

url = "https://api.usecobalt.com/v1/forms/{id}"

headers = {
    "client_id": "<api-key>",
    "client_secret": "<api-key>",
    "access_token": "<api-key>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {client_id: '<api-key>', client_secret: '<api-key>', access_token: '<api-key>'}
};

fetch('https://api.usecobalt.com/v1/forms/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.usecobalt.com/v1/forms/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "access_token: <api-key>",
    "client_id: <api-key>",
    "client_secret: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.usecobalt.com/v1/forms/{id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("client_id", "<api-key>")
	req.Header.Add("client_secret", "<api-key>")
	req.Header.Add("access_token", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.usecobalt.com/v1/forms/{id}")
  .header("client_id", "<api-key>")
  .header("client_secret", "<api-key>")
  .header("access_token", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.usecobalt.com/v1/forms/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["client_id"] = '<api-key>'
request["client_secret"] = '<api-key>'
request["access_token"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "success": true,
  "form": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "emr_form_id": "392",
    "emr_fvid": "1045",
    "name": "GAD-7",
    "type": "Assessment",
    "version": "3",
    "status": "Active",
    "build_date": "2026-01-15",
    "synced_at": "2026-08-26T09:00:00.000Z",
    "created_at": "2026-01-20T12:00:00.000Z",
    "updated_at": "2026-08-26T09:00:00.000Z",
    "definition": {
      "categories": [
        {}
      ]
    }
  }
}

{
  "success": true,
  "message": "Invalid form ID format. Must be a valid UUID."
}

{
  "success": true,
  "message": "Form not found"
}

GET

forms

{id}

Get Form

curl --request GET \
  --url https://api.usecobalt.com/v1/forms/{id} \
  --header 'access_token: <api-key>' \
  --header 'client_id: <api-key>' \
  --header 'client_secret: <api-key>'

import requests

url = "https://api.usecobalt.com/v1/forms/{id}"

headers = {
    "client_id": "<api-key>",
    "client_secret": "<api-key>",
    "access_token": "<api-key>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {client_id: '<api-key>', client_secret: '<api-key>', access_token: '<api-key>'}
};

fetch('https://api.usecobalt.com/v1/forms/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.usecobalt.com/v1/forms/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "access_token: <api-key>",
    "client_id: <api-key>",
    "client_secret: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.usecobalt.com/v1/forms/{id}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("client_id", "<api-key>")
	req.Header.Add("client_secret", "<api-key>")
	req.Header.Add("access_token", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.usecobalt.com/v1/forms/{id}")
  .header("client_id", "<api-key>")
  .header("client_secret", "<api-key>")
  .header("access_token", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.usecobalt.com/v1/forms/{id}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["client_id"] = '<api-key>'
request["client_secret"] = '<api-key>'
request["access_token"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "success": true,
  "form": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "emr_form_id": "392",
    "emr_fvid": "1045",
    "name": "GAD-7",
    "type": "Assessment",
    "version": "3",
    "status": "Active",
    "build_date": "2026-01-15",
    "synced_at": "2026-08-26T09:00:00.000Z",
    "created_at": "2026-01-20T12:00:00.000Z",
    "updated_at": "2026-08-26T09:00:00.000Z",
    "definition": {
      "categories": [
        {}
      ]
    }
  }
}

{
  "success": true,
  "message": "Invalid form ID format. Must be a valid UUID."
}

{
  "success": true,
  "message": "Form not found"
}

Returns a single cached form by its Cobalt id, including the full definition — the nested tree of categories, questions, and selectable answers. Use this to discover the question ids you supply in the answers object of POST /v1/services. The id path parameter is the Cobalt form id (UUID) from GET /v1/forms.

Forms are currently supported for Credible.

The definition structure

definition.categories is an ordered tree. A category holds child categories and questions; a question holds selectable answers.

Each question carries an emrQuestionId. That id is the key you use in the service answers object.
Each answer carries a value — the option a question can be scored/set to (for a scored questionnaire this is the numeric score, e.g. "0".."3").
isRequired / isFormRequired tell you which questions must be answered; omitting a required answer fails the service with Missing required answers.

The form metadata fields (emr_form_id, synced_at, …) are snake_case. The nested definition is passed through as the EMR structures it and keeps its own field names (e.g. emrQuestionId, emrCategoryId). Treat the definition as an opaque tree — read the ids and values out of it rather than depending on its exact field casing.

Example Request

curl https://api.usecobalt.com/v1/forms/123e4567-e89b-12d3-a456-426614174000 \
-H 'client_id: ci_live_198908HJDKJSH98789OHKJL' \
-H 'client_secret: cs_live_9827hofdsklOYYHJLJh' \
-H 'access_token: 493JKLHIU98789hLKH9HHJH'

Example Response

{
    "success": true,
    "form": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "emr_form_id": "392",
        "emr_fvid": "1045",
        "name": "GAD-7",
        "type": "Assessment",
        "version": "3",
        "status": "Active",
        "build_date": "2026-01-15",
        "synced_at": "2026-08-26T09:00:00.000Z",
        "created_at": "2026-01-20T12:00:00.000Z",
        "updated_at": "2026-08-26T09:00:00.000Z",
        "definition": {
            "categories": [
                {
                    "emrCategoryId": "7781",
                    "parentEmrCategoryId": null,
                    "name": "GAD-7",
                    "order": 1,
                    "categories": [],
                    "questions": [
                        {
                            "emrQuestionId": "453149",
                            "emrCategoryId": "7781",
                            "order": 1,
                            "text": "Feeling nervous, anxious, or on edge",
                            "formatCode": "RB",
                            "formatLabel": "Radio Button",
                            "isRequired": true,
                            "isFormRequired": false,
                            "externalId": null,
                            "snomedCode": null,
                            "loincCode": null,
                            "units": null,
                            "calcFormula": null,
                            "answers": [
                                { "emrAnswerId": "980011", "value": "0", "order": 1 },
                                { "emrAnswerId": "980012", "value": "1", "order": 2 },
                                { "emrAnswerId": "980013", "value": "2", "order": 3 },
                                { "emrAnswerId": "980014", "value": "3", "order": 4 }
                            ]
                        }
                    ]
                }
            ]
        }
    }
}

Error Responses

Invalid ID Format

{
    "success": false,
    "message": "Invalid form ID format. Must be a valid UUID."
}

Form Not Found

{
    "success": false,
    "message": "Form not found"
}

Authorizations

client_id

string

header

required

client_secret

string

header

required

access_token

string

header

required

Path Parameters

string

required

Cobalt form id (UUID).

Response

The cached form with its full definition

success

boolean

form

object

Show child attributes

​The definition structure

​Example Request

​Example Response

​Error Responses

​Invalid ID Format

​Form Not Found

Authorizations

Path Parameters

Response

The definition structure

Example Request

Example Response

Error Responses

Invalid ID Format

Form Not Found