Using the Hyperproof Custom Fields API

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

This document explains how to discover and use custom fields in Hyperproof. You'll use the Custom Fields API to look up field metadata (IDs, types, options) and then include those IDs and values in other API requests (e.g., when creating or updating controls, risks, tasks).

API Overview

The Custom Fields API provides read access to custom field definitions for your organization. You typically:

1. Retrieve the full set of fields (optionally filtered by object type).
2. Find the field by its name.
3. Use its id (and option IDs, if applicable) when setting values on supported objects in other endpoints.

Base URL: https://api.hyperproof.app/v1/customfields

Key Endpoint: GET / — retrieves all custom fields for an organization.

Custom fields can have types such as text, number, date, single‑select, or multi‑select, and are available on specific object types (e.g., controls, risks, tasks).

Retrieving Custom Fields

To fetch custom fields, make a GET request to the root path.

curl --request GET \
  --url "https://api.hyperproof.app/v1/customfields" \
  --header "Authorization: Bearer $ACCESS_TOKEN"

Filter by object type using the objectType query parameter.

curl --request GET \
  --url "https://api.hyperproof.app/v1/customfields?objectType=control" \
  --header "Authorization: Bearer $ACCESS_TOKEN"

Once you have the set of fields, use the name to locate the one you need. The field object includes the IDs required to set values elsewhere (e.g., fieldId and select‐field option IDs).

Parameters

• objectType (query, optional) — Filters by a specific object type. Must be one of the allowed enums (e.g., control, risk, task).

Response

200 OK — Returns an array of custom fields (a CustomFieldCollection). Each item typically includes:

• id — Unique identifier for the field.
• orgId — Organization identifier.
• name — Human‑readable name (e.g., "Location").
• type — Field type (e.g., textSingleSelect, number, date).
• availableOn — Array of object types where this field is usable (e.g., ["control", "risk"]).
• options — For select fields, an array of options with their own id and textValue.
• Other properties such as isRequired, icon, status (active/archived), and timestamps.

Example response:

[
  {
    "id": "d88d505d-5199-11ee-a644-522476618ae8",
    "orgId": "ce83e3cd-5199-11ee-a644-522476618ae8",
    "name": "secondary priority",
    "type": "textSingleSelect",
    "availableOn": ["control", "risk"],
    "icon": "Location",
    "isRequired": false,
    "options": [
      {
        "id": "3d36f1d6-64af-11ef-af67-6a1d3a1c7211",
        "orgId": "ce83e3cd-5199-11ee-a644-522476618ae8",
        "fieldId": "d88d505d-5199-11ee-a644-522476618ae8",
        "isDefault": false,
        "textValue": "High"
      },
      {
        "id": "3d36f1d5-64af-11ef-af67-6a1d3a1c7211",
        "orgId": "ce83e3cd-5199-11ee-a644-522476618ae8",
        "fieldId": "d88d505d-5199-11ee-a644-522476618ae8",
        "isDefault": false,
        "textValue": "Low"
      },
      {
        "id": "3d36cac4-64af-11ef-af67-6a1d3a1c7211",
        "orgId": "ce83e3cd-5199-11ee-a644-522476618ae8",
        "fieldId": "d88d505d-5199-11ee-a644-522476618ae8",
        "isDefault": false,
        "textValue": "Medium"
      }
    ],
    "status": "active"
  }
]

Use this endpoint to discover field IDs and, for select types, the option IDs needed to set values in other API calls.

Setting Custom Field Values

The Custom Fields API is read‑only for definitions. You set values via other endpoints when creating or updating supported objects (e.g., controls or risks).

Guidelines:

• Always include the field's fieldId when setting a value.

• Non‑select fields: use the appropriate value key — textValue, numberValue, dateValue, or userValue (GUID).

• Select fields:

  • Single‑select: use selection with the option's id (not the textValue).
  • Multi‑select: use selections with an array of option IDs.

• Add custom fields in the payload under a top‑level customFields array.

Example payload snippet:

{
  "customFields": [
    {
      "fieldId": "ceb912ab-519b-11ee-a644-522476618ae8",
      "textValue": "John Smith"
    },
    {
      "fieldId": "ceb912ab-519b-11ee-a644-522476618ae9",
      "numberValue": "12345"
    },
    {
      "fieldId": "ceb912ab-519b-11ee-a644-522476618ae7",
      "selection": "3d36f1d6-64af-11ef-af67-6a1d3a1c7211"
    },
    {
      "fieldId": "ceb912ab-519b-11ee-a644-522476618ae6",
      "selections": [
        "3d36cac4-64af-11ef-af67-6a1d3a1c7211",
        "3d36f1d5-64af-11ef-af67-6a1d3a1c7211"
      ]
    }
  ]
}

Include this customFields array in the body of the relevant POST or PATCH calls for objects that support custom fields.

Common Object Types

Examples of object types that may support custom fields include: control, risk, and task. Consult the specific object APIs for their create/update schemas and whether custom fields are accepted.

Tips

• Look up field and option IDs once and cache them if you plan to reuse them across requests.
• When changing a field's name in the UI, its id remains stable—use IDs, not names, in integrations.
• For user pickers, pass the userValue (a GUID) corresponding to the user.