Get custom field definition

GET /api/v3/custom_field_definitions/{id}

Request

Response

URL

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

cURL command

curl --request GET 'https://example.aha.io/api/v3/custom_field_definitions/123' \
  --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.

ID of the custom field definition

Response fields

Choose which fields to include in the response. 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.

Search fields

Field	Type	Returned by default
Unique record ID.	integer	Yes
Include id in response
Name of the custom field definition.	string	Yes
Include name in response
Internal name of the custom field definition, shown only to administrators.	string	No
Include internal_name in response
Key of the custom field definition. Must be unique per record type and only use lowercase letters, numbers and underscores.	string	Yes
Include key in response
Type of the custom field definition.	string	Yes
Include type in response 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
Include record_type in response 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
Include custom_table in response Expand this association to browse its response fields.
HTML description of the record.	Note	No
Include description in response Expand this association to browse its response fields.
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
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 Expand this association to browse its response fields.
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
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 Expand this association to browse its response fields.
Text shown before the value of a number field. Null for other types.	string	No
Include prefix in response
Text shown after the value of a number field. Null for other types.	string	No
Include suffix in response
Whether a number field shows thousands separators. Always false for other types.	boolean	No
Include use_delimiters in response
Label shown next to a checkbox field. Null for other types.	string	No
Include label in response
How a predefined or editable choice list field shows its value. Null for other types.	string	No
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
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
Include supported_file_types in response
Custom table a relationship field links to; set on create only and null for other types.	CustomObjectDefinition	No
Include linked_custom_table in response Expand this association to browse its response fields.
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
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
Include scoring_system in response Expand this association to browse its response fields.
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
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 Expand this association to browse its response fields.
Date and time when the record was created.	date-time	No
Include created_at in response
Date and time when the record was last updated.	date-time	No
Include updated_at in response

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

Response field selection

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.

See field selection for details.

Response statuses

Error shape for 401, 403, 404

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

record: a single record. Fields are documented above.

Download the complete OpenAPI specification