List custom field definitions

GET /api/v3/custom_field_definitions

Request

Response

URL

GET https://example.aha.io/api/v3/custom_field_definitions

cURL command

curl --request GET 'https://example.aha.io/api/v3/custom_field_definitions' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Accept: application/json'

Request conventions

API key or OAuth2 access token. See Authentication.

Use your account domain and token in copied requests. Request values and conditional fields must satisfy your account’s validation rules.

URL settings

Account subdomain

The part before .aha.io. Leave blank to use the example domain.

per_page

Number of records per page (default 25, max 200)

after

Opaque cursor from a previous response to fetch the next page

Fields

Choose fields to return, filter, or sort. Expand a field for examples and associated fields. Collections can only be returned on the top-level resource, not inside an associated resource.

Default response fields are returned until you select specific fields.

Add and edit filters and sorting in field details. Examples illustrate the response shape, not matching records.

Search fields

Field	Type	Returned by default	Sortable	Supported filters
Unique record ID.	integer	Yes	Yes	`eqnot_eqgtgteltlteinnot_inbetweenemptynot_empty`
Include id in responseSort by id
Name of the custom field definition.	string	Yes	Yes	`eqnot_eqcontainsstarts_withinnot_inemptynot_empty`
Include name in responseSort by name
Internal name of the custom field definition, shown only to administrators.	string	No	Yes	`eqnot_eqcontainsstarts_withinnot_inemptynot_empty`
Include internal_name in responseSort by internal_name
Key of the custom field definition. Must be unique per record type and only use lowercase letters, numbers and underscores.	string	Yes	Yes	`eqnot_eqcontainsstarts_withinnot_inemptynot_empty`
Include key in responseSort by key
Type of the custom field definition.	string	Yes	Yes	`eqnot_eqinnot_inemptynot_empty`
Include type in responseSort by type Allowed values: `textnotenumberdateurlcheckboxattachmentpredefined_choice_listeditable_choice_listpredefined_tagstagsconditional_choicescorecardworksheetmany_to_many_relationshipmany_to_one_relationshipone_to_many_relationshipusersworkspacesgoalsinitiativeskey_resultsreleasesepicsfeaturesideasidea_categoriesorganizationsidea_created_bycompetitorspersonascreative_briefs`
Record type the custom field definition belongs to. Custom table fields use custom_table.	string	No	Yes	`eqnot_eqinnot_inemptynot_empty`
Include record_type in responseSort by record_type Allowed values: `projectfeatureepicrequirementreleaserelease_phaseinitiativegoalkey_resultideaidea_endorsementidea_organizationidea_usercreative_briefpersonacompetitorcapacity_investmentteamprogram_incrementtaskdocumentstudyinterviewcustom_table`
Custom table the custom field definition belongs to if record_type is custom_table.	CustomObjectDefinition	No	No	`emptynot_empty`
Include custom_table in response Association filters apply to this field itself. Expand its subfields below to see their individual capabilities.
HTML description of the record.	Note	No	No	`emptynot_empty`
Include description in response Association filters apply to this field itself. Expand its subfields below to see their individual capabilities.
Layouts the custom field definition appears on. Not settable for account-level or custom table fields, which have no layouts to choose. Omitted by default. Request the field for inline records with default sub-fields, or choose sub-fields (e.g., ?fields=layouts[default]). Capped at 25 records. Only available on the top-level resource.	Collection	No	No	`emptynot_empty`
Collection envelope Records use the associated fields below. Type: `object` Required properties: records, has_more. url Type: `string` (uri) has_more Type: `boolean` next_url Type: `string` (uri) Include layouts in response Association filters apply to this field itself. Expand its subfields below to see their individual capabilities.
Options of a choice custom field definition, including hidden options. Null for other types. Omitted by default. Request the field for inline records with default sub-fields, or choose sub-fields (e.g., ?fields=options[default]). Capped at 25 records. Only available on the top-level resource.	Collection	No	No	None
Collection envelope Records use the associated fields below. Type: `object` Required properties: records, has_more. url Type: `string` (uri) has_more Type: `boolean` next_url Type: `string` (uri) Include options in response Association filters apply to this field itself. Expand its subfields below to see their individual capabilities.
Text shown before the value of a number field. Null for other types.	string	No	No	None
Include prefix in response
Text shown after the value of a number field. Null for other types.	string	No	No	None
Include suffix in response
Whether a number field shows thousands separators. Always false for other types.	boolean	No	No	None
Include use_delimiters in response
Label shown next to a checkbox field. Null for other types.	string	No	No	None
Include label in response
How a predefined or editable choice list field shows its value. Null for other types.	string	No	No	None
Include display in response Allowed values: `plain_textcolored_labels`
Which records a records field offers as values: all in the account, those in the record's workspace line or workspace, or those related to the record. The scopes available depend on the field type and record type. Null for other types.	string	No	No	None
Include scope in response Allowed values: `accountproject_lineprojectrelated`
File extensions an attachment field accepts, from: csv, doc, docx, eml, gif, jpeg, mov, mp4, msg, pdf, png, ppt, pptx, tiff, txt, xls, xlsx. Null or empty allows every file type. Null for other types.	array	No	No	None
Include supported_file_types in response
Custom table a relationship field links to; set on create only and null for other types.	CustomObjectDefinition	No	No	None
Include linked_custom_table in response Association filters apply to this field itself. Expand its subfields below to see their individual capabilities.
Which custom table records a many to many or many to one relationship field offers: all in the account, or those in the record's workspace and its parent lines. Idea organization fields only support account. Null for other types.	string	No	No	None
Include project_scope in response Allowed values: `accountproject`
Account scorecard a scorecard field uses; required for scorecard fields and null for other types.	ScoringSystem	No	No	None
Include scoring_system in response Association filters apply to this field itself. Expand its subfields below to see their individual capabilities.
Rows of a worksheet field, in display order. Null for other types. Omitted by default. Request the field for inline records with default sub-fields, or choose sub-fields (e.g., ?fields=worksheet_rows[default]). Capped at 25 records. Only available on the top-level resource.	Collection	No	No	None
Collection envelope Records use the associated fields below. Type: `object` Required properties: records, has_more. url Type: `string` (uri) has_more Type: `boolean` next_url Type: `string` (uri) Include worksheet_rows in response Association filters apply to this field itself. Expand its subfields below to see their individual capabilities.
Date and time when the record was created.	date-time	No	Yes	`eqgtgteltltebetweenemptynot_empty`
Include created_at in responseSort by created_at
Date and time when the record was last updated.	date-time	No	Yes	`eqgtgteltltebetweenemptynot_empty`
Include updated_at in responseSort by updated_at

Search matches the start of a field path and includes matching associations’ subfields. Use a dotted path to search within a specific association.

Query syntax

Return selected fields with a comma-separated fields parameter, or add a field to the defaults with fields=default,{field}. Expand an association above for its supported subfields and selection examples.

Filter with filter.{operator}[{field}]=value. Multiple filters combine with AND. Use comma-separated values for in and not_in, two inclusive bounds for between, and true for empty and not_empty.

Sort with sort.asc={field} or sort.desc={field}. Explicit sorting limits results to 1,000 records. Omit sorting to retrieve all results in descending ID order.

Set the page size with per_page. Follow pagination.next_url while pagination.has_more is true.

Filter operators

eq equals; not_eq does not equal; contains contains text; starts_with starts with text (both case-insensitive).

gt greater than; gte greater than or equal; lt less than; lte less than or equal.

in matches any listed value; not_in excludes listed values; between matches an inclusive range; empty and not_empty check for an absent or present value.

See field selection, filtering, and pagination and sorting limits for details.

Response statuses

Error shape for 400, 401, 403

Type: object

error

Type: object

Required properties: status, code, message, request_id.

status

Type: integer

code

Type: string

message

Type: string

request_id

Type: string

Response envelope and pagination

records: array of records. Fields are documented above.

pagination

Type: object

Required properties: has_more.

has_more

Type: boolean

next_cursor

Type: string or null

next_url

Type: string or null (uri)

truncated

Type: boolean

truncated_message

Type: string

Download the complete OpenAPI specification