Create discovery interview

POST /api/v3/discovery_interviews

Request

Response

URL

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

JSON body

{
  "record": {
    "name": "Example record"
  }
}

cURL command

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

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 record.	string	`name`
Include name in request Value for name Accepted value shape and constraints Type: `string`
Date and time when the interview starts.	date-time	`start_time`
Include start_time in request Accepted value shape and constraints Type: `string` (date-time)
Date and time when the interview ends.	date-time	`end_time`
Include end_time in request Accepted value shape and constraints Type: `string` (date-time)
Status of the interview.	string	`status`
Include status in request Accepted value shape and constraints Type: `string` Allowed values: "scheduling", "scheduled", "processing", "analyzing", "completed", "canceled" Allowed values: `schedulingscheduledprocessinganalyzingcompletedcanceled`
Mode of the interview.	string	`mode`
Include mode in request Accepted value shape and constraints Type: `string` Allowed values: "in_person", "phone", "video", "focus_group", "observation", "document_analysis" Allowed values: `in_personphonevideofocus_groupobservationdocument_analysis`
ID of the study containing the interview.	string	`study`
Include study_id in request Accepted value shape and constraints Type: `string` Submit `study_id`; the response includes `study`.
ID of the type of interview.	string	`interview_type`
Include interview_type_id in request Accepted value shape and constraints Type: `string` Submit `interview_type_id`; the response includes `interview_type`.
Custom field values to set. Property names are custom field definition keys, and each value is one of the supported input formats below, depending on the field type. Attachment fields are read-only and can't be set.	object	`custom_fields`
Include custom_fields in request Accepted value shape and constraints Type: `object` Custom property values Type: `one of the shapes below` Supported shape 1 Text field Type: `string` Supported shape 2 Note field Type: `string` Supported shape 3 URL field Type: `string` (uri) Supported shape 4 Number field Type: `string` Supported shape 5 Date field Type: `string` (date) Supported shape 6 Checkbox field Type: `boolean` Supported shape 7 Single select field Type: `object` Minimum properties: 1 id Type: `string` name Type: `string` Supported shape 8 Conditional choice field Type: `object` Required properties: id. id Type: `string` Supported shape 9 Multi-select field Type: `array` Array item shape Type: `object` id Type: `string` name Type: `string` _destroy Type: `boolean` Supported shape 10 Records field Type: `array` Array item shape Type: `object` id Type: `string` _destroy Type: `boolean` Supported shape 11 Single custom table link Type: `object` Required properties: id. id Type: `string` Supported shape 12 Custom table links Type: `array` Array item shape Type: `object` id Type: `string` _destroy Type: `boolean` Supported shape 13 Worksheet field Type: `array` Array item shape Type: `object` Required properties: id, value. id Type: `string` value Type: `string or number or boolean or null` Supported shape 14 Scorecard field Type: `object` Minimum properties: 1 score Type: `number or null` score_facts Type: `array` Array item shape Type: `object` scoring_system_metric_id Type: `string` value Type: `number` _destroy Type: `boolean` Supported shape 15 Clear value Type: `null` Use your account’s custom field API keys and values matching each field’s type.
ID of the workspace that contains the record.	string	`project`
Include project_id in request Accepted value shape and constraints Type: `string` Submit `project_id`; the response includes `project`.

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
URL to view the record in Aha!	string	Yes
Include html_url in response
API URL for the record.	string	Yes
Include url in response
Name of the record.	string	Yes
Include name in response
Reference number of the record.	string	Yes
Include reference_num in response
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
Date and time when the interview starts.	date-time	No
Include start_time in response
Date and time when the interview ends.	date-time	No
Include end_time in response
Status of the interview.	string	No
Include status in response Allowed values: `schedulingscheduledprocessinganalyzingcompletedcanceled`
Mode of the interview.	string	No
Include mode in response Allowed values: `in_personphonevideofocus_groupobservationdocument_analysis`
Summary of the interview.	string	No
Include summary in response
Sentiment analysis of the interview.	DiscoverySentiment	No
Include sentiments in response Expand this association to browse its response fields.
Workspace that contains the record.	Project	No
Include project in response Expand this association to browse its response fields.
Study containing the interview.	DiscoveryStudy	No
Include study in response Expand this association to browse its response fields.
Type of interview.	DiscoveryInterviewType	No
Include interview_type in response Expand this association to browse its response fields.
Interview transcript. To append content on update, send a TXT, VTT, or DOCX file as record[transcript] using multipart/form-data. Transcript uploads are not supported in application/json requests.	Note	No
Include transcript in response Expand this association to browse its response fields.
Interview participants. Omitted by default. Request the field for inline records with default sub-fields, or choose sub-fields (e.g., ?fields=idea_users[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 idea_users in response Expand this association to browse its response fields.
Highlights from the transcript. Omitted by default. Request the field for inline records with default sub-fields, or choose sub-fields (e.g., ?fields=annotations[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 annotations in response Expand this association to browse its response fields.
Records linked to the interview.	LinkedRecord	No
Include linked_records in response Expand this association to browse its response fields.
Custom field values. Property names are custom field definition keys, and each value is one of the supported formats below, depending on the field type. Omitted unless requested with the fields parameter or submitted in the request. Fields with no stored value are omitted.	object	No
Include custom_fields in responseCustom field API key Custom field keys depend on your account. Request `fields=custom_fields` or `fields=custom_fields.your_key`.

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