# Using the Hyperproof Custom Fields API

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.


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

Filter by object type using the `objectType` query parameter.


```bash
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:


```json
[
  {
    "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:


```json
{
  "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.