Skip to main content

Understanding the Autotask Data Structure

If you have never worked with the Autotask API before, this page gives you the mental model you need. Autotask is a database that you read from and write to through its API. Once you understand how Autotask organizes its data, every query, ticket creation, and update becomes much easier to reason about.

This guide explains three core ideas: what an entity is, how every entity is identified by an ID, and how Autotask connects entities together using those IDs.

About This Guide​

This guide is a general introduction to the Autotask SOAP API itself. It is written for anyone who is new to the Autotask API, including anyone building integrations against the Autotask SOAP API, regardless of the tools they use. The goal is to give you a conceptual understanding of how the API is designed and how its data fits together.

This is not a guide to anything unique to the MSPintegrations implementation. MSPintegrations exposes the Autotask API so you can query and create Autotask records from within your workflows, and you interact with the same entities, IDs, and relationships described here. Throughout this guide you will find occasional sidebars that note how MSPintegrations exposes a particular behavior, but the core concepts apply to the Autotask API in general. Learn the fundamentals here, then apply that understanding as you work with Autotask through MSPintegrations.

The Autotask API Is Consistent and Predictable​

One of the most useful things to know about the Autotask API is that it is internally consistent and well-structured. Autotask follows the same naming schemes, styles, and design patterns across the entire API. The way one part of the API works is the way the rest of it works.

This consistency means that once you understand the fundamentals, you can confidently infer how unfamiliar parts of the API behave. If you learn how one entity, ID, or relationship works, you have effectively learned how they all work.

For that reason, the examples in this guide are illustrations of patterns that apply across the whole API, not special cases. When you read about tickets and ticket notes, the same pattern applies to accounts and account notes, projects and tasks, and every other parent and child relationship in Autotask. Read each example as a template you can apply everywhere, not as a one-off rule for a single entity.

Everything Is an Entity​

Autotask stores its data as entities. An entity is a single record of one type, such as an Account, a Ticket, a Contact, or a Time Entry. Each entity holds a set of properties, which are the individual data fields on that record.

For example, an Account entity has properties like AccountName, AccountType, and Phone. A Ticket entity has properties like Title, Description, and Status.

Autotask has over 150 entity types. For an introduction to the most common ones, see Autotask Entities.

Every Entity Has an ID​

Every entity in Autotask has a unique numeric identifier called its id. The ID is assigned by Autotask when the entity is created and never changes.

The ID is how you point to one specific record. You use it to:

  • Retrieve a single entity
  • Update the properties of that entity
  • Delete that entity
  • Link related entities together by storing one entity's ID on another, which is how Autotask cross-references and correlates related records

IDs are unique within an entity type. Ticket 12345 and Contact 12345 are completely unrelated records that happen to share the same number, because one is a Ticket and the other is a Contact.

How Entities Relate: ID Properties​

Entities are connected to each other through their properties. When one entity is related to another, the relationship is stored as an ID property that holds the ID of the related entity.

The rule to remember is: the child holds the parent's ID.

A clear example is ticket notes. A ticket note belongs to a ticket. When you create a TicketNote, it carries a TicketID property that holds the id of the ticket it belongs to. That single property is what links the note to the ticket.

A Ticket itself holds ID properties that point to the records it depends on:

PropertyPoints to
AccountIDThe Account the ticket belongs to
ContactIDThe primary Contact on the ticket
AssignedResourceIDThe Resource working the ticket

Because a property like ContactID or AccountID holds the ID of a separate record rather than the record itself, reading the related details would normally take a second call. MSPintegrations automatically expands linked objects when you query, so you can read the related entity's properties directly without making that extra call.

Two Kinds of Numbers: References and Picklist Values​

When you look at an entity, many properties contain a number that represents or references a particular value. Sometimes that number references another entity, and sometimes it represents a picklist value. These two kinds of numbers behave very differently, and telling them apart is essential.

Rule of thumb

If a property's number points to a record you can query (like a contact or account), it is a relationship. If it is one of a fixed set of choices for that field (like status or priority), it is a picklist value, not a relationship.

Entity references point to another record. Properties like AccountID, ContactID, and TicketID hold the id of a separate entity that the API exposes. That related record can be queried, created, updated, and deleted on its own. This is a true relationship between two entities.

Picklist values are fixed options on the field itself. Properties like Status, Priority, QueueID, and IssueType also hold a number, but that number is one of a fixed set of valid values the API exposes for that field. These values do correspond to real records that you configure in the Autotask UI, but the API does not expose those records as separate, queryable entities. There is no Status entity exposed through the API: you cannot query for statuses. Instead, the API exposes the list of valid statuses as picklist values on the field. A ticket simply has a status, and the status is one of a handful of discrete choices. You cannot link a ticket to a status record, because the API exposes no such record to link to. Think of these as the options in a dropdown menu.

The practical difference:

Entity referencePicklist value
ExamplesAccountID, ContactID, TicketIDStatus, Priority, QueueID, IssueType
The number isThe id of a separate recordOne of a fixed set of valid values for the field
Exposed by the API as its own entity?Yes: you can query itNo: only the valid values are exposed on the field
Configured where?Created as records (tickets, contacts, and so on)Configured in the Autotask UI, exposed by the API as picklist values
Is it a relationship?YesNo

MSPintegrations automatically expands both kinds, so a ticket's Status resolves to its label (for example, Complete) and a ticket's ContactID resolves to the contact's full details, all in one query. The difference is what sits behind the number: a related record for a reference, or a label for a picklist value.

There Are No Arrays: Relationships Use Separate Entities​

This is the single most important idea to internalize, and it surprises most people coming from modern web APIs.

The Autotask SOAP API has no array fields. An entity property holds one value: a string, a number, a date, or a single ID. A ticket does not contain a list of ticket notes or time entries stored inside it, and an account does not contain a list of account notes stored inside it. Instead, each ticket note and time entry relates to its ticket, and each account note relates to its account.

Autotask represents "many" relationships by creating separate entities. Both many-to-one relationships (such as a ticket having many notes or time entries) and many-to-many relationships (such as a ticket having many additional contacts) are built this way.

Worked Example: Additional Ticket Contacts​

A ticket has one primary contact, stored in the ticket's ContactID property. But a ticket can also have several additional contacts. Because there is no array to hold them, each additional contact is associated to the ticket by creating a new entity that represents that association.

To add an extra contact to a ticket, you create a TicketAdditionalContact entity that holds two ID properties:

PropertyPoints to
TicketIDThe ticket the contact is being added to
ContactIDThe contact being added

Each additional contact you add is one new TicketAdditionalContact entity. Adding three extra people to a ticket means creating three TicketAdditionalContact entities.

For the full discussion of how additional contacts and notifications work, see Managing Additional Ticket Contacts in Autotask.

Deleting a Relationship: Use the Join Entity's Own ID​

Removing an additional contact from a ticket trips up new users, so read this carefully.

The TicketAdditionalContact entity has its own id, just like every other entity. To remove an additional contact from a particular ticket, you delete the TicketAdditionalContact entity that links the contact to the ticket. You do this by deleting that TicketAdditionalContact entity itself, identified by its own id.

To un-associate a contact from a ticket, you do not reference the TicketID, and you do not reference the ContactID. Those are properties that describe the association; they are not what identifies the association record. You reference the TicketAdditionalContact entity's own id, which is the only thing that identifies the specific record to remove.

The same pattern applies to any relationship built from a separate entity: to break the relationship, you delete the entity that represents it, using that entity's own id. For the action that performs deletions, see API: Delete an Object.

Most Things Relate to an Account​

The Account is the hub of Autotask. An account represents a company: most often one of your customers. The majority of entities in Autotask ultimately trace back to an account through an AccountID property.

An account is the parent of many record types, including:

  • Tickets: service requests for that company
  • Contacts: the people who work at that company
  • Contracts: the service agreements covering that company
  • Configuration Items / Installed Products: the devices and assets at that company
  • Opportunities: sales records for that company

When you create a ticket, a contact, or a contract, you tell Autotask which account it belongs to by setting its AccountID. If you are not sure which account to use when no customer matches, see The Autotask "Zero" Account.

System-Wide Entities​

Not everything belongs to an account. Some entities are system-wide and exist independently of any single company.

The clearest example is the Resource. A resource represents a user who logs into Autotask, such as a technician or a manager. A resource is not owned by a customer account; the same resource can be assigned to tickets across many different accounts.

Other system-wide records include holiday sets, picklist values, and other configuration that applies across your whole Autotask instance rather than to one customer.

The practical takeaway: when you look for an entity, first ask whether it is account-scoped (a ticket, a contact, a contract) or system-wide (a resource, a holiday set). Account-scoped entities are filtered by AccountID. System-wide entities are not.

Putting It Together​

Here is how a single ticket connects to the rest of Autotask:

  • The ticket's AccountID points to the Account (the customer)
  • The ticket's ContactID points to the primary Contact at that account
  • The ticket's AssignedResourceID points to the Resource working it (a system-wide user)
  • Each TicketNote is its own entity, and the ticket note itself has a TicketID property that holds the ticket's id
  • Each additional contact is a TicketAdditionalContact entity holding the TicketID and a ContactID

Every one of these connections is an ID stored on an entity. There are no lists embedded inside the ticket. When you need "many" of something, you look for the separate entities that carry the ticket's ID.

There is one direction rule that ties all of this together: entities are linked from the child to the parent. The child entity holds the ID of its parent.

A ticket note is a child of a ticket. The ticket note carries the parent ticket's ID in its TicketID property. You do not add a note to a ticket by editing the ticket; the ticket has no field that lists its notes. Instead, you create the ticket note and set its TicketID to the ticket's id at the moment the note is created. That single property on the child is what establishes the relationship.

This same pattern applies everywhere:

  • A TimeEntry carries the TicketID of the ticket it belongs to
  • An account note carries the AccountID of the account it belongs to
  • A Contact carries the AccountID of the account it belongs to
  • A Contract carries the AccountID of the account it belongs to

In every case, the child entity names its parent. The parent is never edited to "hold" the child.

Once this clicks, the rest of the API follows the same rules everywhere.