Skip to content
Plain Help Center home
Plain Help Center home

Using Plain's API

Plain's API gives your team access to the same powerful tools our own product is built on. Whether you want to connect customer data, build automations, or extend your workflows, Plain's API makes it possible.

This guide will walk you through the basics of Plain's API and what you'll need to get started.

If you are new to GraphQL, Apollo has resources for beginners. The official GraphQL documentation is another good starting point.

What you'll need to get started

Here's what someone on your team will need to get started with our API:

  • Your API key: This gives your system permission to talk to Plain. You can generate one from your Plain workspace settings.

  • A GraphQL client or script: Your team might use a tool like Postman, curl, or a GraphQL IDE.

  • The API endpoint:

    • URL: https://core-api.uk.plain.com/graphql/v1

  • Basic headers (for every request):

    • Content-Type: application/json

    • Authorization: Bearer YOUR_TOKEN

  • The GraphQL schema (optional):

    • Your team can download it here: https://core-api.uk.plain.com/graphql/v1/schema.graphql

What kind of things can you do with it?

Here are some examples of what your team can build using Plain's API:

  • Pull a list of your customers and display it in another internal tool

  • Upsert customer records into Plain from your product

  • Pull core details like usage, billing info, plan type into Customer Cards

  • Automatically create a note or label a customer thread when a status changes in your CRM

  • Fetch conversation data for reporting in tools like Retool or Looker

  • Programmatically create threads and send messages to customers via Slack or email

  • Trigger escalations from your own tooling using a machine user

A great way to explore what you can use our API for is to open our API explorer (which requires setting up a Plain workspace).

Machine users

A machine user is a non-human user you can create in your Plain workspace to perform API operations on behalf of your system or integrations. Machine users can do most things a regular user can – including creating threads, adding labels, sending messages, and triggering escalations.

To create a machine user, go to Settings → Machine users in your Plain workspace. You can then generate an API key scoped to that machine user.

Machine users are ideal for automations, webhooks, and any situation where actions should be attributed to a system rather than a human team member.

Migrating from another platform?

If you're importing historical threads from another support platform, note that the Plain API does not currently support setting a custom createdAt timestamp when creating threads. Threads will be created with the current timestamp. For larger migrations, we recommend using our Importers feature, or getting in touch so we can help scope the best approach for your data.

Making your first API call

Here's a real-world example a developer might start with:

"Find a customer in Plain using their email address."

To do this, they'll need:

  • An API key with the customer:read permission

  • The email address of the customer (which you can find on the right-hand side of their thread in Plain)

They can test it using curl, or our TypeScript SDK – whatever their preferred tools are.

Not sure where to start?

If you're curious about how Plain's API could work for your team, or you want help scoping a specific use case, just reach out to us. We're happy to walk through ideas, examples, or even build with you.

Powered by Plain