API

Every plain.api.* operation is listed below with parameter shapes and return types from the plugin Zod schemas.

New to Corsair? See API access, authentication, and error handling.

Companies

fetch

companies.fetch Fetch a company by ID. Risk: read

await corsair.plain.api.companies.fetch({});

Input

Name	Type	Required	Description
`companyId`	`string`	Yes	—

Output

Name	Type	Required	Description
`company`	`object`	No	—

company full type

{
  id: string,
  name: string,
  domainName: string,
  contractValue?: number | null
}

update

companies.update Create or update a company by ID or domain. Risk: write

await corsair.plain.api.companies.update({});

Input

Name	Type	Required	Description
`identifier`	`object`	Yes	—
`name`	`string`	Yes	—
`domainName`	`string`	Yes	—
`contractValue`	`number`	No	—
`accountOwnerUserId`	`string`	No	—

identifier full type

{
  companyId?: string,
  companyDomainName?: string
}

Output

Name	Type	Required	Description
`result`	`CREATED \| UPDATED \| NOOP`	No	—
`company`	`object`	No	—

company full type

{
  id: string,
  name: string,
  domainName: string,
  contractValue?: number | null
}

Customer Groups

addCustomer

customerGroups.addCustomer Add a customer to one or more customer groups. Risk: write

await corsair.plain.api.customerGroups.addCustomer({});

Input

Name	Type	Required	Description
`customerId`	`string`	Yes	—
`customerGroupIdentifiers`	`object[]`	Yes	—

customerGroupIdentifiers full type

{
  customerGroupId?: string,
  customerGroupKey?: string,
  externalId?: string
}[]

Output

Name	Type	Required	Description
`customerGroupMemberships`	`object[]`	Yes	—

customerGroupMemberships full type

{
  customerId: string,
  customerGroup: {
    id: string,
    name: string,
    key: string,
    color: string,
    externalId?: string | null
  }
}[]

create

customerGroups.create Create a customer group. Risk: write

await corsair.plain.api.customerGroups.create({});

Input

Name	Type	Required	Description
`name`	`string`	Yes	—
`key`	`string`	Yes	—
`color`	`string`	Yes	—
`externalId`	`string`	No	—

Output

Name	Type	Required	Description
`customerGroup`	`object`	Yes	—

customerGroup full type

{
  id: string,
  name: string,
  key: string,
  color: string,
  externalId?: string | null
}

list

customerGroups.list List customer groups with cursor pagination. Risk: read

await corsair.plain.api.customerGroups.list({});

Input

Name	Type	Required	Description
`filters`	`object`	No	—
`first`	`number`	No	—
`after`	`string`	No	—
`last`	`number`	No	—
`before`	`string`	No	—

filters full type

{
  externalIds?: string[]
}

Output

Name	Type	Required	Description
`customerGroups`	`object[]`	Yes	—
`pageInfo`	`object`	Yes	—

customerGroups full type

{
  id: string,
  name: string,
  key: string,
  color: string,
  externalId?: string | null
}[]

pageInfo full type

{
  hasNextPage: boolean,
  hasPreviousPage: boolean,
  startCursor?: string | null,
  endCursor?: string | null
}

removeCustomer

customerGroups.removeCustomer Remove a customer from one or more customer groups. Risk: write

await corsair.plain.api.customerGroups.removeCustomer({});

Input

Name	Type	Required	Description
`customerId`	`string`	Yes	—
`customerGroupIdentifiers`	`object[]`	Yes	—

customerGroupIdentifiers full type

{
  customerGroupId?: string,
  customerGroupKey?: string,
  externalId?: string
}[]

Output

Name	Type	Required	Description
`success`	`true`	Yes	—

Customers

delete

customers.delete Delete a customer asynchronously. Risk: write

await corsair.plain.api.customers.delete({});

Input

Name	Type	Required	Description
`customerId`	`string`	Yes	—

Output

Name	Type	Required	Description
`success`	`true`	Yes	—

getByEmail

customers.getByEmail Fetch a customer by email address. Risk: read

await corsair.plain.api.customers.getByEmail({});

Input

Name	Type	Required	Description
`email`	`string`	Yes	—

Output

Name	Type	Required	Description
`customer`	`object`	No	—

customer full type

{
  id: string,
  externalId?: string | null,
  fullName: string,
  shortName?: string | null,
  email: {
    email: string,
    isVerified: boolean
  }
}

getById

customers.getById Fetch a customer by Plain customer ID. Risk: read

await corsair.plain.api.customers.getById({});

Input

Name	Type	Required	Description
`customerId`	`string`	Yes	—

Output

Name	Type	Required	Description
`customer`	`object`	No	—

customer full type

{
  id: string,
  externalId?: string | null,
  fullName: string,
  shortName?: string | null,
  email: {
    email: string,
    isVerified: boolean
  }
}

list

customers.list List customers with optional filters and cursor pagination (first/after or last/before). Risk: read

await corsair.plain.api.customers.list({});

Input

Name	Type	Required	Description
`filters`	`object`	No	—
`sortBy`	`object`	No	—
`first`	`number`	No	—
`after`	`string`	No	—
`last`	`number`	No	—
`before`	`string`	No	—

filters full type

{
  isMarkedAsSpam?: boolean,
  customerGroupIds?: string[],
  customerGroupKeys?: string[],
  companyIdentifiers?: {
    companyId?: string,
    companyDomainName?: string
  }[],
  tenantIdentifiers?: {
    tenantId?: string,
    externalId?: string
  }[],
  slackChannelId?: string
}

sortBy full type

{
  field: FULL_NAME,
  direction: ASC | DESC
}

Output

Name	Type	Required	Description
`customers`	`object[]`	Yes	—
`pageInfo`	`object`	Yes	—
`totalCount`	`number`	Yes	—

customers full type

{
  id: string,
  externalId?: string | null,
  fullName: string,
  shortName?: string | null,
  email: {
    email: string,
    isVerified: boolean
  }
}[]

pageInfo full type

{
  hasNextPage: boolean,
  hasPreviousPage: boolean,
  startCursor?: string | null,
  endCursor?: string | null
}

upsert

customers.upsert Create or update a customer by identifier. Risk: write

await corsair.plain.api.customers.upsert({});

Input

Name	Type	Required	Description
`identifier`	`object`	Yes	—
`onCreate`	`object`	Yes	—
`onUpdate`	`object`	Yes	—

identifier full type

{
  externalId?: string,
  emailAddress?: string,
  customerId?: string
}

onCreate full type

{
  externalId?: string,
  fullName: string,
  shortName?: string,
  email: {
    email: string,
    isVerified: boolean
  },
  customerGroupIdentifiers?: {
    customerGroupId?: string,
    customerGroupKey?: string,
    externalId?: string
  }[],
  tenantIdentifiers?: {
    tenantId?: string,
    externalId?: string
  }[]
}

onUpdate full type

{
  externalId?: {
    value?: string | null
  },
  fullName?: {
    value: string
  },
  shortName?: {
    value?: string | null
  },
  email?: {
    email: string,
    isVerified: boolean
  }
}

Output

Name	Type	Required	Description
`result`	`CREATED \| UPDATED \| NOOP`	No	—
`customer`	`object`	No	—

customer full type

{
  id: string,
  externalId?: string | null,
  fullName: string,
  shortName?: string | null,
  email: {
    email: string,
    isVerified: boolean
  }
}

Graphql

run

graphql.run Run an arbitrary GraphQL query or mutation. Risk: write

await corsair.plain.api.graphql.run({});

Input

Name	Type	Required	Description
`query`	`string`	Yes	—
`variables`	`object`	No	—
`operationName`	`string`	No	—

variables full type

{
}

Output: lazy

Threads

create

threads.create Create a thread for a customer. Risk: write

await corsair.plain.api.threads.create({});

Input

Name	Type	Required	Description
`customerIdentifier`	`object`	Yes	—
`title`	`string`	No	—
`description`	`string`	No	—
`priority`	`number`	No	—
`labelTypeIds`	`string[]`	No	—
`threadFields`	`object[]`	No	—
`assignedTo`	`object`	No	—
`externalId`	`string`	No	—
`tenantIdentifier`	`object`	No	—
`channel`	`API \| EMAIL \| SLACK \| MS_TEAMS \| CHAT \| INTERNAL \| DISCORD \| IMPORT`	No	—

customerIdentifier full type

{
  externalId?: string,
  emailAddress?: string,
  customerId?: string
}

threadFields full type

{
  key: string,
  type: STRING | BOOL | ENUM | NUMBER | CURRENCY | DATE,
  stringValue?: string,
  booleanValue?: boolean,
  numberValue?: number,
  dateValue?: string
}[]

assignedTo full type

{
  userId?: string,
  machineUserId?: string
}

tenantIdentifier full type

{
  tenantId?: string,
  externalId?: string
}

Output

Name	Type	Required	Description
`thread`	`object`	No	—

thread full type

{
  id: string,
  ref: string,
  title: string,
  status: string,
  priority: number
}

fetchIssues

threads.fetchIssues Fetch external thread links for a customer and flatten as issue records. Risk: read

await corsair.plain.api.threads.fetchIssues({});

Input

Name	Type	Required	Description
`customerId`	`string`	Yes	—
`threadFirst`	`number`	No	—
`threadAfter`	`string`	No	—
`threadLast`	`number`	No	—
`threadBefore`	`string`	No	—
`linkFirst`	`number`	No	—

Output

Name	Type	Required	Description
`issues`	`object[]`	Yes	—
`pageInfo`	`object`	Yes	—
`totalThreads`	`number`	Yes	—

issues full type

{
  threadId: string,
  threadRef: string,
  threadTitle: string,
  link: {
    id: string,
    sourceId: string,
    sourceType: string,
    title: string,
    description?: string | null,
    url: string,
    status: string,
    linkType: string
  }
}[]

pageInfo full type

{
  hasNextPage: boolean,
  hasPreviousPage: boolean,
  startCursor?: string | null,
  endCursor?: string | null
}

getById

threads.getById Fetch a thread by Plain thread ID. Risk: read

await corsair.plain.api.threads.getById({});

Input

Name	Type	Required	Description
`threadId`	`string`	Yes	—

Output

Name	Type	Required	Description
`thread`	`object`	No	—

thread full type

{
  id: string,
  ref: string,
  title: string,
  status: string,
  priority: number
}

listDeprecated

threads.listDeprecated Deprecated threads listing operation; use threads.query. Risk: read

await corsair.plain.api.threads.listDeprecated({});

Input

Name	Type	Required	Description
`filters`	`object`	No	—
`sortBy`	`object`	No	—
`first`	`number`	No	—
`after`	`string`	No	—
`last`	`number`	No	—
`before`	`string`	No	—

filters full type

{
  threadIds?: string[],
  refs?: string[],
  labelTypeIds?: string[],
  priorities?: number[],
  customerIds?: string[],
  isAssigned?: boolean,
  assignedToUser?: string[],
  isMarkedAsSpam?: boolean,
  supportEmailAddresses?: string[],
  customerGroupIdentifiers?: {
    customerGroupId?: string,
    customerGroupKey?: string,
    externalId?: string
  }[],
  tierIdentifiers?: {
    tierId?: string,
    externalId?: string
  }[],
  companyIdentifiers?: {
    companyId?: string,
    companyDomainName?: string
  }[],
  tenantIdentifiers?: {
    tenantId?: string,
    externalId?: string
  }[],
  messageSource?: CHAT | EMAIL | API | SLACK | MS_TEAMS | DISCORD | INTERNAL[],
  participantIds?: string[],
  broadcastIds?: string[],
  statuses?: TODO | SNOOZED | DONE[]
}

sortBy full type

{
  field: STATUS_CHANGED_AT | CREATED_AT | CLOSEST_TO_BREACH_SLA | LAST_INBOUND_MESSAGE_AT | PRIORITY | THREAD_FIELD,
  direction: ASC | DESC,
  threadFieldKey?: string
}

Output

Name	Type	Required	Description
`threads`	`object[]`	Yes	—
`pageInfo`	`object`	Yes	—
`totalCount`	`number`	Yes	—

threads full type

{
  id: string,
  ref: string,
  title: string,
  status: string,
  priority: number
}[]

pageInfo full type

{
  hasNextPage: boolean,
  hasPreviousPage: boolean,
  startCursor?: string | null,
  endCursor?: string | null
}

query

threads.query List threads with filters, sort, and cursor pagination. Risk: read

await corsair.plain.api.threads.query({});

Input

Name	Type	Required	Description
`filters`	`object`	No	—
`sortBy`	`object`	No	—
`first`	`number`	No	—
`after`	`string`	No	—
`last`	`number`	No	—
`before`	`string`	No	—

filters full type

{
  threadIds?: string[],
  refs?: string[],
  labelTypeIds?: string[],
  priorities?: number[],
  customerIds?: string[],
  isAssigned?: boolean,
  assignedToUser?: string[],
  isMarkedAsSpam?: boolean,
  supportEmailAddresses?: string[],
  customerGroupIdentifiers?: {
    customerGroupId?: string,
    customerGroupKey?: string,
    externalId?: string
  }[],
  tierIdentifiers?: {
    tierId?: string,
    externalId?: string
  }[],
  companyIdentifiers?: {
    companyId?: string,
    companyDomainName?: string
  }[],
  tenantIdentifiers?: {
    tenantId?: string,
    externalId?: string
  }[],
  messageSource?: CHAT | EMAIL | API | SLACK | MS_TEAMS | DISCORD | INTERNAL[],
  participantIds?: string[],
  broadcastIds?: string[],
  statuses?: TODO | SNOOZED | DONE[]
}

sortBy full type

{
  field: STATUS_CHANGED_AT | CREATED_AT | CLOSEST_TO_BREACH_SLA | LAST_INBOUND_MESSAGE_AT | PRIORITY | THREAD_FIELD,
  direction: ASC | DESC,
  threadFieldKey?: string
}

Output

Name	Type	Required	Description
`threads`	`object[]`	Yes	—
`pageInfo`	`object`	Yes	—
`totalCount`	`number`	Yes	—

threads full type

{
  id: string,
  ref: string,
  title: string,
  status: string,
  priority: number
}[]

pageInfo full type

{
  hasNextPage: boolean,
  hasPreviousPage: boolean,
  startCursor?: string | null,
  endCursor?: string | null
}

sendMessage

threads.sendMessage Reply to a thread via Plain routing. Risk: write

await corsair.plain.api.threads.sendMessage({});

Input

Name	Type	Required	Description
`threadId`	`string`	Yes	—
`textContent`	`string`	Yes	—
`markdownContent`	`string`	No	—
`attachmentIds`	`string[]`	No	—
`impersonation`	`object`	No	—

impersonation full type

{
  asCustomer: {
    customerIdentifier: {
      externalId?: string,
      emailAddress?: string,
      customerId?: string
    }
  }
}

Output

Name	Type	Required	Description
`success`	`true`	Yes	—

update

threads.update Update a thread title. Risk: write

await corsair.plain.api.threads.update({});

Input

Name	Type	Required	Description
`threadId`	`string`	Yes	—
`title`	`string`	Yes	—

Output

Name	Type	Required	Description
`thread`	`object`	No	—

thread full type

{
  id: string,
  ref: string,
  title: string,
  status: string,
  priority: number
}

Tiers

fetch

tiers.fetch Fetch a tier by ID. Risk: read

await corsair.plain.api.tiers.fetch({});

Input

Name	Type	Required	Description
`tierId`	`string`	Yes	—

Output

Name	Type	Required	Description
`tier`	`object`	No	—

tier full type

{
  id: string,
  name: string,
  externalId?: string | null,
  color?: string,
  isDefault?: boolean
}

list

tiers.list List tiers with cursor pagination. Risk: read

await corsair.plain.api.tiers.list({});

Input

Name	Type	Required	Description
`first`	`number`	No	—
`after`	`string`	No	—
`last`	`number`	No	—
`before`	`string`	No	—

Output

Name	Type	Required	Description
`tiers`	`object[]`	Yes	—
`pageInfo`	`object`	Yes	—

tiers full type

{
  id: string,
  name: string,
  externalId?: string | null,
  color?: string,
  isDefault?: boolean
}[]

pageInfo full type

{
  hasNextPage: boolean,
  hasPreviousPage: boolean,
  startCursor?: string | null,
  endCursor?: string | null
}

Users

delete

users.delete Delete a workspace user. Risk: write

await corsair.plain.api.users.delete({});

Input

Name	Type	Required	Description
`userId`	`string`	Yes	—

Output

Name	Type	Required	Description
`success`	`true`	Yes	—

getById

users.getById Fetch a workspace user by ID. Risk: read

await corsair.plain.api.users.getById({});

Input

Name	Type	Required	Description
`userId`	`string`	Yes	—

Output

Name	Type	Required	Description
`user`	`object`	No	—

user full type

{
  id: string,
  fullName: string,
  publicName: string,
  email: string,
  isDeleted?: boolean
}

Overview

Plugins

Companies

fetch

update

Customer Groups

addCustomer

create

list

removeCustomer

Customers

delete

getByEmail

getById

list

upsert

Graphql

run

Threads

create

fetchIssues

getById

listDeprecated

query

sendMessage

update

Tiers

fetch

list

Users

delete

getById

​Companies

​fetch

​update

​Customer Groups

​addCustomer

​create

​list

​removeCustomer

​Customers

​delete

​getByEmail

​getById

​list

​upsert

​Graphql

​run

​Threads

​create

​fetchIssues

​getById

​listDeprecated

​query

​sendMessage

​update

​Tiers

​fetch

​list

​Users

​delete

​getById

Companies

fetch

update

Customer Groups

addCustomer

create

list

removeCustomer

Customers

delete

getByEmail

getById

list

upsert

Graphql

run

Threads

create

fetchIssues

getById

listDeprecated

query

sendMessage

update

Tiers

fetch

list

Users

delete

getById