1. Core Concepts

    Core Concepts

    This guide covers the core concepts you’ll encounter in your work with the Attio API.

    We also have specific guides for Actors, Errors and Webhooks.


    A Workspace is a top-level grouping for an organisation within Attio. For example, if your company is called “Pied Piper”, you’ll likely be operating within the Pied Piper workspace.

    Small companies will usually have one workspace, but larger companies may have several. A user can belong to many Workspaces.

    When using the Attio API, your access will be limited to the scope of the Workspace that your access token belongs to.

    Workspace Members

    Within each Workspace, there are many Workspace Members. A Workspace Member represent a User within a Workspace. They are distinct from a User in that Users have one identity that may be shared amongst many Workspaces, but each User can only have one Workspace Member for each Workspace.


    Integrations are a grouping of access tokens, webhooks, scopes and configuration related to the developer API.

    You can view the Integrations you have created within the “Developers” tab of your Workspace settings.

    Particle: Attio’s Data Model

    At the core of Attio is our powerful and flexible data model. We call that data model “Particle”.

    Particle has three core concepts: Objects, Attributes, and Records.


    Objects are the data types used to store facts about your customer. By themselves, they contain little information other than a name, but they are the root on which other Particle concepts sit.

    Attio comes with two Objects by default: People and Companies.

    In relational database terms, Objects are roughly tables. In object-orientated terms, they are analogous to classes.

    Note that an instance of an Object is called a Record (see below).


    Records are an instantiation of an Object, e.g. a specific Person or a specific Company.

    In relational database terms, a Record is roughly a row in a table. In object-orientated terms, they are analogous to an object (an instantiated class).


    Lists are groups of Entries, designed to model a particular process. For example, you might have a 'Sales' List that contains the Companies you have deals with.

    Rows in a List are known as Entries (see below).

    Like Objects, Lists are roughly tables in relational database terms, or classes in object-orientated terms.


    An Entry is a row in a List which corresponds to a single Record. You create an Entry by adding a Record to a List.

    Like Records, Entries contain their own data, as well as linking to the data of the parent Record.

    Like Records, an Entry is roughly a row in a table in relational database terms, or an object (an instantiated class) in object-orientated terms.


    Attributes sit on Objects and Lists and describe which data we can store.

    Some Attributes, such as the name on a Person, are system defined. Others, you define yourself, either in Attio’s UI or over the API.

    Attributes are one of many types such as text, number, select, or currency.

    In relational database terms, an Attribute is roughly a column in a table.