Custom external data

Custom external data allows a client application to add app-specific metadata to tasks in the API. The custom data includes a string gid that can be used to retrieve objects and a data blob that can store character strings.

The blob may store unicode-safe serialized data such as JSON or YAML. The external gid is capped at 1,024 characters, while data blobs are capped at 32,768 characters. Each object supporting external data can have one gid and one data blob stored with it. You can also use either or both of those fields.

The external gid field is a good choice to create a reference between a resource in Asana and another database, such as cross-referencing an Asana task with a customer record in a CRM, or a bug in a dedicated bug tracker. Since it is just a unicode string, this field can store numeric IDs as well as URIs. However, when using URIs, extra care must be taken that the parameter is escaped correctly when forming queries . By assigning an external gid, you can use the notation external:custom_id to reference your object anywhere that you may use the original object gid.

📘

OAuth

You will need to authenticate with OAuth, as the gid and data are app-specific, and these fields are not visible in the UI. This also means that external data set by one OAuth app will be invisible to all other OAuth apps. However, the data is visible to all users of the same app that can view the resource to which the data is attached, so this should not be used for private user data.