Skip to main content

Data model

Plain's data model differs from other customer service systems in one significant way: there are no tickets, contacts, or conversations.

All interactions with a customer appear in their timeline in a single view. A customer's timeline consists of an ordered list of timeline entries which can be of different types.

Customer Timeline Data Model

Reference: Entry Union

Other entities in the data model:

  • Workspace: The main tenancy boundary. All data is segregated between workspaces.
  • Issue type: A list of all issues your customers get in touch about (e.g. "General question" or "Refund request"). Can be configured in Settings -> Issue Types.
  • Issue: A specific instance of an issue type with a unique identifier. Issues have an open and close entry on the customer's timeline.
  • Note: A private note in a customer's timeline only visible to Support App users.
  • Snippet: A text fragment that can easily be inserted into a conversation with a customer.
  • Communication channels: Currently chat and email. These channels need to be configured separately.
  • Human user: A "normal" user that uses the Support App. The documentation usually refers to this as just "user". Human users can be a member of multiple workspaces. Authentication is via an OAuth identity provider.
  • Machine user: A user that exclusively uses the Plain API to perform automation. Machine users are restricted to a single workspace. Authentication is via API keys.


The customer entity has the following fields:

  • id (string): Plain's id of the customer.
  • externalId (string, optional): Your customer’s id in your own systems. If provided, this is what is used to identify customers.
  • fullName (string): The full name of the customer.
  • shortName (string, optional): Typically the first name of the customer.
  • email
    • email (string): Their email address
    • isVerified (boolean): Whether the user has confirmed that they have access to their email address, for example they have already verified their email on your app or website.
  • status (enum): See customer life cycle section for details.
  • assignedToUser (optional): The user the customer is assigned to
  • assignedAt (string, iso timestamp, optional): When the customer was assigned.
  • lastIdleAt (string, iso timestamp, optional): When the customer was last idle, i.e. how long they've been in either active or snoozed status.

Reference: Customer Object

Customer life cycle

A customer has a status indicating what is currently happening to them. The statuses are:

  • IDLE: The default status of a customer when they don't have any open issues. Most activity on their timeline will move them into ACTIVE.
  • ACTIVE: The customer is currently either waiting for help or being helped, depending on if they're assigned to a user or not.
  • SNOOZED: Indicates that a user is waiting for a customer to get back. Any activity on their timeline will move them into ACTIVE.

Reference: Customer Status Enum