Create custom field definition

POST /api/v3/custom_field_definitions

Request

Response

URL

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

JSON body

{
  "record": {
    "name": "Example record",
    "key": "example",
    "type": "text",
    "record_type": "project"
  }
}

cURL command

curl --request POST 'https://example.aha.io/api/v3/custom_field_definitions' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "record": {
    "name": "Example record",
    "key": "example",
    "type": "text",
    "record_type": "project"
  }
}'

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.

Request fields

Send fields for the new record inside a JSON record object.

Only writable fields for this endpoint are listed. Required flags reflect the endpoint schema; record and workspace validation also applies.

Search request fields

Field	Type	Response field
Name of the custom field definition.	string	`name`
Include name in request Value for name Accepted value shape and constraints Type: `string`
Key of the custom field definition. Must be unique per record type and only use lowercase letters, numbers and underscores.	string	`key`
Include key in request Value for key Accepted value shape and constraints Type: `string`
Type of the custom field definition.	string	`type`
Include type in request Value for type Accepted value shape and constraints Type: `string` Allowed values: "text", "note", "number", "date", "url", "checkbox", "attachment", "predefined_choice_list", "editable_choice_list", "predefined_tags", "tags", "conditional_choice", "scorecard", "worksheet", "many_to_many_relationship", "many_to_one_relationship", "one_to_many_relationship", "users", "workspaces", "goals", "initiatives", "key_results", "releases", "epics", "features", "ideas", "idea_categories", "organizations", "idea_created_by", "competitors", "personas", "creative_briefs" 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	`record_type`
Include record_type in request Value for record_type Accepted value shape and constraints Type: `string` Allowed values: "project", "feature", "epic", "requirement", "release", "release_phase", "initiative", "goal", "key_result", "idea", "idea_endorsement", "idea_organization", "idea_user", "creative_brief", "persona", "competitor", "capacity_investment", "team", "program_increment", "task", "document", "study", "interview", "custom_table" Allowed values: `projectfeatureepicrequirementreleaserelease_phaseinitiativegoalkey_resultideaidea_endorsementidea_organizationidea_usercreative_briefpersonacompetitorcapacity_investmentteamprogram_incrementtaskdocumentstudyinterviewcustom_table`
Internal name of the custom field definition, shown only to administrators.	string	`internal_name`
Include internal_name in request Accepted value shape and constraints Type: `string`
HTML description of the record.	string	`description`
Include description in request Accepted value shape and constraints Type: `string`
Layouts the custom field definition appears on. Not settable for account-level or custom table fields, which have no layouts to choose. Items are merged into the existing collection: each item adds a record, or removes it with `_destroy: true`. Records not listed are left unchanged, and an empty array changes nothing.	array	`layouts`
Include layouts in request Accepted value shape and constraints Type: `array` Array item shape Type: `object` id Type: `string` _destroy Type: `boolean`
Text shown before the value of a number field. Null for other types.	string	`prefix`
Include prefix in request Accepted value shape and constraints Type: `string`
Text shown after the value of a number field. Null for other types.	string	`suffix`
Include suffix in request Accepted value shape and constraints Type: `string`
Whether a number field shows thousands separators. Always false for other types.	boolean	`use_delimiters`
Include use_delimiters in request Accepted value shape and constraints Type: `boolean`
Label shown next to a checkbox field. Null for other types.	string	`label`
Include label in request Accepted value shape and constraints Type: `string`
How a predefined or editable choice list field shows its value. Null for other types.	string	`display`
Include display in request Accepted value shape and constraints Type: `string` Allowed values: "plain_text", "colored_labels" 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	`scope`
Include scope in request Accepted value shape and constraints Type: `string` Allowed values: "account", "project_line", "project", "related" 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	`supported_file_types`
Include supported_file_types in request Accepted value shape and constraints Type: `array` Array item shape Type: `string`
ID of the custom table a relationship field links to; set on create only and null for other types.	string	`linked_custom_table`
Include linked_custom_table_id in request Accepted value shape and constraints Type: `string` Submit `linked_custom_table_id`; the response includes `linked_custom_table`.
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	`project_scope`
Include project_scope in request Accepted value shape and constraints Type: `string` Allowed values: "account", "project" Allowed values: `accountproject`
ID of the account scorecard a scorecard field uses; required for scorecard fields and null for other types.	string	`scoring_system`
Include scoring_system_id in request Accepted value shape and constraints Type: `string` Submit `scoring_system_id`; the response includes `scoring_system`.
Rows of a worksheet field. Send a row's id to update the fields you provide, omit the id to add a row at the end, or set _destroy to true to remove a row. Rows you don't send remain unchanged.	array	`worksheet_rows`
Include worksheet_rows in request Accepted value shape and constraints Type: `array` Array item shape Type: `object` id Type: `string` type Type: `string` Allowed values: "field", "section" name Type: `string` equation Type: `string` format Type: `string` Allowed values: "string", "number", "percent", "currency", "date", "boolean" precision Type: `integer` show_thousand_separator Type: `boolean` currency Type: `string` Allowed values: "us_dollar", "euro", "pound", "yen" date_format Type: `string` Allowed values: "american", "standard", "computer", "month", "full_text_month_year", "abbrev_text_month_year" _destroy Type: `boolean`
ID of the custom table the custom field definition belongs to if record_type is custom_table.	string	`custom_table`
Include custom_table_id in request Accepted value shape and constraints Type: `string` Submit `custom_table_id`; the response includes `custom_table`.

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

Create and update responses also include fields submitted in the record body. Submitted association IDs return their associated response fields.

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 400, 401, 403, 404, 409

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

Error shape for 422

Type: object

error

Type: object

Required properties: status, code, message, details, request_id.

status

Type: integer

Allowed values: 422

code

Type: string

Allowed values: "record.validation_failed", "record.cannot_delete"

message

Type: string

details

Type: array

Array item shape

Type: object

field

Type: string

message

Type: string

code

Type: string

request_id

Type: string

Response envelope and pagination

record: a single record. Fields are documented above.

Download the complete OpenAPI specification