Appearance
Get lookup typeahead results ​
API ReferenceNote: The path is a placeholder. The actual path is determined by the configuration of the app component.
Gets typeahead results to render as a dropdown list in the resource lookup input field.
When the user types into the lookup input field, Asana will send a request containing the entered string to the application's typeahead_url. The list of TypeaheadItems in the response will then be rendered in a dropdown list. When the user selects an item from the list, Asana will send a resource attach request to the app server, then process the response and render the attached resource in the widget.
OpenAPI definition ​
json
{
"openapi": "3.0.0",
"info": {
"description": "This is the interface for handling requests for app components. This reference is generated from an [OpenAPI spec] (https://raw.githubusercontent.com/Asana/openapi/master/defs/app_components_oas.yaml).",
"title": "App Components",
"termsOfService": "https://asana.com/terms",
"contact": {
"name": "Asana Support",
"url": "https://asana.com/support"
},
"license": {
"name": "Apache 2.0",
"url": "https://www.apache.org/licenses/LICENSE-2.0"
},
"version": "0.1",
"x-docs-schema-whitelist": [
"AttachedResourceResponse",
"FormField-Checkbox",
"FormField-Date",
"FormField-Datetime",
"FormField-Dropdown",
"FormField-MultiLineText",
"FormField-RadioButton",
"FormField-RichText",
"FormField-SingleLineText",
"FormField-StaticText",
"FormField-Typeahead",
"FormMetadataResponse",
"RanActionResponse",
"WidgetFooter-CustomText",
"WidgetFooter-Created",
"WidgetFooter-Updated",
"WidgetMetadataResponse",
"WidgetField-DatetimeWithIcon",
"WidgetField-Pill",
"WidgetField-TextWithIcon",
"TypeaheadListResponse",
"TypeaheadItem",
"FormValues",
"BadRequestResponse",
"UnauthorizedResponse",
"ForbiddenResponse",
"NotFoundResponse",
"InternalServerErrorResponse"
]
},
"x-readme": {
"explorer-enabled": false
},
"servers": [
{
"url": "{siteUrl}",
"description": "Main endpoint."
}
],
"tags": [
{
"name": "Lookups",
"description": "If the app defined a resource attach URL, tasks without a widget offer the lookup functionality. This appears as a text input to the user. When the user submits the text, the app responds with either a resource attachment or with an error."
}
],
"components": {
"responses": {
"BadRequest": {
"description": "Bad request",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BadRequestResponse"
}
}
}
},
"Unauthorized": {
"description": "Unauthorized",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UnauthorizedResponse"
}
}
}
},
"Forbidden": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ForbiddenResponse"
}
}
}
},
"NotFound": {
"description": "Not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/NotFoundResponse"
}
}
}
},
"InternalServerError": {
"description": "Server error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InternalServerErrorResponse"
}
}
}
}
},
"schemas": {
"RootUIComponentRequest": {
"description": "The building block of all app component requests.",
"type": "object",
"properties": {
"expires_at": {
"type": "string",
"description": "The time (in ISO 8601 date format) when the request should expire.",
"example": "2019-04-15T01:01:46.055Z"
},
"user": {
"type": "string",
"description": "The user GID this hook is coming from.",
"example": "54321"
},
"workspace": {
"type": "string",
"description": "The workspace GID this hook is coming from.",
"example": "12345"
}
}
},
"BadRequestResponse": {
"description": "An error response object indicating a bad request (i.e., a status code of `400`).",
"type": "object",
"properties": {
"error": {
"description": "The error to display.",
"type": "string",
"example": "Illegal or malformed request."
}
}
},
"ForbiddenResponse": {
"description": "An error response object indicating a forbidden request (i.e., a status code of `403`).",
"type": "object",
"properties": {
"error": {
"description": "The error to display.",
"type": "string",
"example": "Access forbidden."
}
}
},
"InternalServerErrorResponse": {
"description": "An error response object indicating a request that could not be found (i.e., a status code of `500`).",
"type": "object",
"properties": {
"error": {
"description": "The error to display.",
"type": "string",
"example": "Internal server error."
}
}
},
"NotFoundResponse": {
"description": "An error response object indicating a request that could not be found (i.e., a status code of `404`).",
"type": "object",
"properties": {
"error": {
"description": "The error to display.",
"type": "string",
"example": "Not found."
}
}
},
"TypeaheadItem": {
"description": "An object describing a typeahead result.",
"type": "object",
"required": [
"title",
"value"
],
"properties": {
"title": {
"description": "The title of the typeahead item.",
"type": "string",
"example": "OTP Team PF"
},
"subtitle": {
"description": "The subtitle of the typeahead item.",
"type": "string",
"example": "OTP"
},
"value": {
"description": "The value of the typeahead item.",
"type": "string",
"example": "OTP"
},
"icon_url": {
"description": "The URL of the icon to display next to the title.",
"type": "string",
"example": "https://example-icon.png"
}
}
},
"TypeaheadListRequest": {
"allOf": [
{
"$ref": "#/components/schemas/RootUIComponentRequest"
},
{
"type": "object",
"description": "The body of a typeahead request.",
"properties": {
"workspace": {
"type": "string",
"description": "The workspace GID this hook is coming from.",
"example": "12345"
},
"query": {
"type": "string",
"description": "The user's input in the typeahead text input.",
"example": "Messages"
},
"task": {
"type": "string",
"description": "*Conditional*. The task GID this hook is coming from. `task` is only present in the [modal form](/docs/modal-form) (as there is a \"context task\"), but not in the [rule action](/docs/rule-action) (as rules are associated with a _project_).",
"example": "67890"
},
"user": {
"type": "string",
"description": "The user GID this hook is coming from.",
"example": "54321"
},
"expires_at": {
"type": "string",
"description": "The time (in ISO 8601 format) when the request should expire.",
"example": "2019-04-15T01:01:46.055Z"
}
}
}
]
},
"TypeaheadListResponse": {
"description": "The response to a successful typeahead request.",
"type": "object",
"required": [
"items"
],
"properties": {
"header": {
"description": "*Optional*. Header text to display above the list of typeahead results. If no `header` is passed in or the value is an empty string, only the typeahead results with be rendered.",
"type": "string",
"example": "List of messages"
},
"items": {
"description": "Array of [TypeaheadItem](/reference/app-components/lookups#typeaheaditem) objects that indicate typeahead results.",
"type": "array",
"items": {
"$ref": "#/components/schemas/TypeaheadItem"
}
}
}
},
"UnauthorizedResponse": {
"description": "An error response object indicating a unauthorized request (i.e., a status code of `401`).",
"type": "object",
"properties": {
"error": {
"description": "The error to display.",
"type": "string",
"example": "Authorization required."
}
}
}
}
},
"paths": {
"/resource_typeahead_url_path_placeholder": {
"get": {
"summary": "Get lookup typeahead results",
"description": "_Note: The path is a placeholder. The actual path is determined by the configuration of the app component._\n\nGets typeahead results to render as a dropdown list in the resource lookup input field.\n\nWhen the user types into the lookup input field, Asana will send a request containing the entered string to the application's `typeahead_url`. The list of [TypeaheadItem](/reference/app-components/lookups#typeaheaditem)s in the response will then be rendered in a dropdown list. When the user selects an item from the list, Asana will send a [resource attach](/reference/custom-types/attachresource) request to the app server, then process the response and render the attached resource in the widget.",
"tags": [
"Lookups"
],
"operationId": "getTypeaheadResults",
"requestBody": {
"description": "Request to retrieve typeahead results for a resource lookup query.",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TypeaheadListRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successfully retrieved typeahead results.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TypeaheadListResponse"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/Forbidden"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"500": {
"$ref": "#/components/responses/InternalServerError"
}
}
}
}
}
}