Custom Fields API

Read the definitions of your community’s advocate custom fields: what each field is called, what type it is, and which options it offers. The values live on each advocate.

Requires the advocates permission. Definitions are not personal data, so advocates:pii is not needed.

Endpoint	Returns
`GET /api/v1/custom_fields`	Every custom field, in the order set in Settings

List custom fields

GET https://integrations.stokedhq.com/api/v1/custom_fields

The list is not paginated and takes no filters: a community has a handful of fields.

You rarely need to call this on its own. Every advocate response carries the same id, identifier, label, response_type, and options for each field in its top-level meta.custom_fields, so you can render an advocate’s values without a second request. Call this endpoint when you want the rest: whether a field is required, its position, and its placeholder and helper text.

Request

GET /api/v1/custom_fields

cURL

curl "https://integrations.stokedhq.com/api/v1/custom_fields" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/vnd.api+json"

Ruby

require "net/http"
require "json"

uri = URI("https://integrations.stokedhq.com/api/v1/custom_fields")

request = Net::HTTP::Get.new(uri)
request["Authorization"] = "Bearer YOUR_API_KEY"
request["Accept"] = "application/vnd.api+json"

response = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) }
raise "HTTP #{response.code}: #{response.body}" unless response.is_a?(Net::HTTPSuccess)

puts JSON.parse(response.body)["data"]

Python

import requests

response = requests.get(
    "https://integrations.stokedhq.com/api/v1/custom_fields",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Accept": "application/vnd.api+json",
    },
)
response.raise_for_status()

print(response.json()["data"])

using System.Net.Http.Headers;
using System.Text.Json;

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "YOUR_API_KEY");
client.DefaultRequestHeaders.Accept.ParseAdd("application/vnd.api+json");

using var response = await client.GetAsync("https://integrations.stokedhq.com/api/v1/custom_fields");
response.EnsureSuccessStatusCode();

using var document = JsonDocument.Parse(await response.Content.ReadAsStringAsync());
Console.WriteLine(document.RootElement.GetProperty("data"));

JavaScript

const url = new URL("https://integrations.stokedhq.com/api/v1/custom_fields");

const response = await fetch(url, {
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    Accept: "application/vnd.api+json",
  },
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);

const { data } = await response.json();
console.log(data);

Response

Response custom-fields-index.json Download

{
  "data": [
    {
      "type": "custom_fields",
      "id": "01k5examplecust0mf1eld0001",
      "attributes": {
        "identifier": "bike_model",
        "label": "Bike model",
        "response_type": "short_text",
        "options": [],
        "required": false,
        "position": 1,
        "placeholder_text": null,
        "helper_text": null,
        "created_at": "2026-08-20T14:00:00Z",
        "updated_at": "2026-08-20T14:00:00Z"
      }
    },
    {
      "type": "custom_fields",
      "id": "01k5examplecust0mf1eld0002",
      "attributes": {
        "identifier": "accessories",
        "label": "Accessories",
        "response_type": "multiple_select",
        "options": [
          "Rain cover",
          "Child seats",
          "Front rack"
        ],
        "required": false,
        "position": 2,
        "placeholder_text": null,
        "helper_text": "Everything fitted to the bike",
        "created_at": "2026-08-20T14:00:00Z",
        "updated_at": "2026-08-20T14:00:00Z"
      }
    }
  ]
}

Custom field attributes

Records with "type": "custom_fields".

Attribute	Type	Description
`identifier`	string	The key this field’s value appears under in an advocate’s `custom_fields` object, and the CSV export’s column name after `custom_field_`
`label`	string	The name shown to admins and advocates
`response_type`	string	`short_text`, `long_text`, `number`, `checkbox`, `single_select`, or `multiple_select`
`options`	array of strings	The choices for a `single_select` or `multiple_select` field, in order. Empty for other types. An advocate’s value uses these same strings.
`required`	boolean	Whether an advocate has to answer it
`position`	integer	Sort order in Settings
`placeholder_text`	string or null	Placeholder shown in the empty input
`helper_text`	string or null	Help text shown under the input
`created_at`	timestamp
`updated_at`	timestamp	When the definition last changed

Adding, renaming, or deleting a custom field changes every advocate’s record, so it moves every advocate’s updated_at. An incremental sync of advocates picks the new shape up on its own.