Attio v2

Provides integration with Attio CRM to read workspace objects, lists and attribute definitions, and to query, create, update, upsert and delete records and list entries in your Workflows. Templates are generated from the objects, lists and attributes in your Attio workspace. The Node is available on Cloud Runtime Clusters.

Revision History

0.0.0.8 - Initial release.

Connection

Use this Connection to store the Attio access token and the workspace definitions used to build templates and validate requests.

Setup Notes

1. Create an access token for your Attio workspace.
2. Grant the token the permissions required by the operations you plan to use:
   • Records: record_permission:read and object_configuration:read. Writes require record_permission:read-write.
   • List entries: list_entry:read and list_configuration:read. Writes require list_entry:read-write.
3. Create an Attio Connection in Flowgear and enter the token in AccessToken.
4. Test the Connection. The test confirms that Attio reports the token as active; a token that Attio reports as inactive fails the test.
5. Run AcquireMetadata. This downloads the Attio API document and reads the workspace's objects, lists, attributes, select options and statuses, then saves them on the Connection. All templates and Methods require this metadata.
6. Select a Method and its operation template, then map the fields needed by your Workflow.

Requests use the fixed https://api.attio.com endpoint. Replace the token on the Connection when it is revoked or reissued.

Run AcquireMetadata again after adding or changing objects, lists, attributes, select options or statuses in Attio, and after changing AccessToken. The saved definitions are bound to the token used to acquire them, so changing the token without acquiring metadata again stops the Node with an instruction to run AcquireMetadata. A failed acquisition keeps the previously saved metadata.

Methods

Select an operation template for the Method you want to use. The template supplies OperationId, a GUID identifying that operation, and describes its Options, Items and Response fields. Record and list entry templates are generated per object or list in your workspace, and their names include the object or list slug, such as Create a record — companies or List entries — sales. An OperationId from a different Method is rejected.

Query

Reads definitions, records or list entries using the selected template. Record and list entry queries retrieve subsequent pages automatically as you consume Response.

Create

Creates one record or list entry for each input item. Supply the item's fields directly through Items; the Node builds the Attio data request envelope.

Update

Updates or upserts one record or list entry for each input item. The selected template determines how values are written:

• Upsert a record creates the record, or updates the existing record whose value for the attribute named in Options.matching_attribute matches. The matching attribute must be a unique attribute in the acquired workspace metadata.
• Upsert a list entry by parent creates the entry, or updates the existing entry for the same parent record.
• Update a record (append multiselect values) and Update a list entry (append multiselect values) add new values to multiselect attributes and keep existing values.
• Update a record (overwrite multiselect values) and Update a list entry (overwrite multiselect values) replace the existing values of multiselect attributes.

When an update template for a list entry has no writable fields, supply an Items stream containing an empty object, {}, for each request you intend to make.

Delete

Deletes the record or list entry identified in Options. This Method executes once per invocation and has no Items input. Delete templates never supply a default record or entry ID.

Usage Notes

• Attribute values are collections of value objects, even for single-valued attributes. For example, a text attribute is written as "name": [{"value": "Example company"}]. Read-only attributes and fields that are not in the selected template are rejected.
• Reference other records and workspace members by their IDs. The Node does not create referenced records by matching their attributes.
• Record and list entry filters support text, number, rating and checkbox attributes discovered in your workspace. Use $eq for those attribute types, or $contains for text attributes. Supply either filter or filter_view_id, not both. Template samples illustrate valid inputs and are not applied automatically.
• Sorts pair a discovered attribute with a direction of asc or desc. Path-based sorts are not supported.
• Let the Node handle pagination. Do not add limit, offset or cursor to Options.
• Map string and integer collections as CSV strings, such as the parent_object and allowed_object_ids fields in list and attribute definitions. Quote values containing commas, quotes or line breaks, and double any quotes inside a quoted value. Whitespace is preserved. An empty string represents an empty collection, while "" represents one empty string. Object collections remain structured.
• Consume the response stream to process all query pages or all create and update items. The first page or write executes when the Node starts; later pages and items are processed as the stream advances.
• Check Flowgear.IsSuccess for every mutation result. Business errors returned by Attio produce a failed row and allow later input items to continue. Missing required fields or unsupported fields in the first item stop the Node; in later items they produce a failed row. Authentication failures, transport failures and timeouts stop the Node.
• The Node retries rate-limited requests up to three times, respecting Attio's Retry-After value. Writes that time out or fail with a server error are not retried automatically. Check Attio before repeating a write because the request may already have succeeded.
• Templates and invocations use the metadata saved on the Connection and make no additional requests to download the API document. Template listing does not contact Attio.

Examples

Query companies by name

Select the Query template List records — companies and supply the following Options object:

{
  "object": "companies",
  "filter": {
    "name": {
      "$eq": "Example company"
    }
  }
}

Each row in Response is one matching company record.

Create a company

Select the Create template Create a record — companies, set Options.object to companies, and supply the following object as an item in Items:

{
  "values": {
    "name": [
      {
        "value": "Example company"
      }
    ]
  }
}

Check the result's Flowgear.IsSuccess before using the returned record ID in later operations.

See also

• Attio REST API reference.