Skip to main content

Documentation Index

Fetch the complete documentation index at: https://www.plain.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

Using TypeScript? Check out our GraphQL SDK for a fully typed client.
We provide a number of methods for fetching customers:
  1. Get customers (To fetch more than one customer at a time)
  2. Get customer by ID
  3. Get customer by email
  4. Get customer by external ID
  5. Search for customers
All of these endpoints require the following permissions:
  • customer:read

​
Get customers

Our API allows you to fetch customers as a collection using the customers query in GraphQL. This endpoint supports Pagination. This is a very flexible endpoint which supports a variety of options for filtering and sorting, for full details try our API explorer.
Query
query getCustomers($cursor: String!) {
  customers(
    after: $cursor
    first: 50
    filters: { isMarkedAsSpam: false }
    sortBy: { field: FULL_NAME, direction: ASC }
  ) {
    edges {
      node {
        id
        fullName
        shortName
        email {
          email
          isVerified
        }
        externalId
        markedAsSpamAt {
          iso8601
        }
      }
    }
    totalCount
    pageInfo {
      hasPreviousPage
      hasNextPage
      startCursor
      endCursor
    }
  }
}
Variables
{
  "cursor": "eyJjdXN0b21lcnMuZnVsbF9uYW1lIjoiQWlkYSBTY2hpbm5lciIsImN1c3RvbWVycy5pZCI6ImNfMDFHMThFU01TWkdUWTQwU1pITk03M0hBQkIifQ=="
}

​
Get customer by ID

If you already have the ID of a customer from within Plain or one of our other endpoints you can fetch more details about them using the customer query in GraphQL.
Query
query getCustomerById($customerId: ID!) {
  customer(customerId: $customerId) {
    id
    fullName
    shortName
    email {
      email
      isVerified
    }
    externalId
    markedAsSpamAt {
      iso8601
    }
  }
}
Variables
{
  "customerId": "c_01H14DFQ4PDYBH398J1E99TWSS"
}

​
Get customer by email

To fetch a customer by email you can use the customerByEmail query in GraphQL.
Query
query getCustomerByEmail($email: String!) {
  customerByEmail(email: $email) {
    id
    fullName
    shortName
    email {
      email
      isVerified
    }
    externalId
    markedAsSpamAt {
      iso8601
    }
  }
}
Variables
{
  "email": "bob@example.com"
}

​
Get customer by external ID

If you store a stable identifier from your own system on Plain customers (for example your internal user ID), you can fetch the customer back by that value using the customerByExternalId query. External IDs are unique within a workspace.
Query
query getCustomerByExternalId($externalId: ID!) {
  customerByExternalId(externalId: $externalId) {
    id
    externalId
    fullName
    shortName
    email {
      email
      isVerified
    }
    markedAsSpamAt {
      iso8601
    }
  }
}
Variables
{
  "externalId": "your-external-id"
}

​
Search for customers

The searchCustomers query lets you do a case-insensitive partial match across a customer’s name, email, short name and external ID. This is the same search behaviour as the customer picker in the Plain app and is best suited for human-driven lookups rather than precise programmatic resolution. For exact lookups by email or external ID, prefer customerByEmail or customerByExternalId.
Query
query searchCustomers($search: String!, $first: Int = 25, $after: String) {
  searchCustomers(
    searchQuery: {
      or: [
        { fullName: { caseInsensitiveContains: $search } }
        { shortName: { caseInsensitiveContains: $search } }
        { email: { caseInsensitiveContains: $search } }
        { externalId: { caseInsensitiveContains: $search } }
      ]
    }
    first: $first
    after: $after
  ) {
    edges {
      node {
        id
        externalId
        fullName
        email {
          email
          isVerified
        }
        company {
          id
          name
        }
        markedAsSpamAt {
          iso8601
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
Variables
{
  "search": "alice",
  "first": 25
}