Account fields

Account fields are custom fields you can attach to an account. For example a plan name, MRR, account owner or any other attribute that is meaningful at the account level rather than per-customer.

For TypeScript, the GraphQL SDK gives you a fully typed client for these operations.

Working with account fields involves two layers:

Account field schemas define what fields exist (type, label, options). You create the schema once.
Account field values are the per-account values stored against a given schema.

This is the same model as thread fields: see thread fields for the equivalent on threads. Each operation needs its own permissions:

upsertAccountFieldSchema: tenantFieldSchema:create, tenantFieldSchema:update, and tenantFieldSchema:delete
deleteAccountFieldSchema: tenantFieldSchema:delete
upsertAccountField: tenantField:create, tenantField:update, and tenantFieldSchema:read, plus tenant:read when you identify the account by externalId
deleteAccountField: tenant:edit

Create or update account field schemas

upsertAccountFieldSchema accepts an array of schemas to create or update in one call. Each schema is identified by the combination of source and externalFieldId. Supported field types are STRING_TYPE, NUMBER_TYPE, BOOLEAN_TYPE, STRING_ARRAY, DATETIME_TYPE, ENUM_TYPE, USER_REFERENCE_TYPE and ACCOUNT_REFERENCE_TYPE (use options to define the allowed values).

Mutation

mutation upsertAccountFieldSchema($input: UpsertAccountFieldSchemaInput!) {
  upsertAccountFieldSchema(input: $input) {
    results
    accountFieldSchemas {
      id
      externalFieldId
      label
      type
      options
      isVisible
      order
    }
    error {
      message
      type
      code
      fields {
        field
        message
        type
      }
    }
  }
}

Variables

{
  "input": {
    "accountFieldSchemas": [
      {
        "source": "your-system",
        "externalFieldId": "plan",
        "label": "Plan",
        "type": "STRING_TYPE",
        "isVisible": true,
        "order": 0
      }
    ]
  }
}

Delete an account field schema

Deleting a schema also removes any account field values stored against it.

Mutation

mutation deleteAccountFieldSchema($input: DeleteAccountFieldSchemaInput!) {
  deleteAccountFieldSchema(input: $input) {
    accountFieldSchema {
      id
      externalFieldId
    }
    error {
      message
      type
      code
      fields {
        field
        message
        type
      }
    }
  }
}

Variables

{
  "input": {
    "accountFieldSchemaId": "tfs_01J7Z..."
  }
}

Set an account field value

Once a schema exists, use upsertAccountField to set or update the value for a specific account. Pass exactly one of stringValue, numberValue, booleanValue, arrayValue, dateValue, userReferenceValues or accountReferenceValues matching the schema’s type.

Mutation

mutation upsertAccountField($input: UpsertAccountFieldInput!) {
  upsertAccountField(input: $input) {
    result
    accountField {
      id
      externalFieldId
      value {
        __typename
        ... on AccountFieldStringValue {
          stringValue
        }
        ... on AccountFieldNumberValue {
          numberValue
        }
        ... on AccountFieldBooleanValue {
          booleanValue
        }
      }
    }
    error {
      message
      type
      code
      fields {
        field
        message
        type
      }
    }
  }
}

Variables

{
  "input": {
    "accountFieldIdentifier": {
      "accountId": "te_01H8H46YPB2S4MAJM382FG9423",
      "externalFieldId": "plan"
    },
    "type": "STRING_TYPE",
    "stringValue": "enterprise"
  }
}

Delete an account field value

To clear an account’s value for a specific field without removing the schema itself, call deleteAccountField.

Mutation

mutation deleteAccountField($input: DeleteAccountFieldInput!) {
  deleteAccountField(input: $input) {
    accountField {
      id
      externalFieldId
    }
    error {
      message
      type
      code
      fields {
        field
        message
        type
      }
    }
  }
}

Variables

{
  "input": {
    "accountFieldId": "tf_01J7Z..."
  }
}

GraphQL API

Building Agents

Agent integrations

Webhooks

Channels

Customer Cards

UI Components

Security

Changelog

Create or update account field schemas

Delete an account field schema

Set an account field value

Delete an account field value

​Create or update account field schemas

​Delete an account field schema

​Set an account field value

​Delete an account field value

Create or update account field schemas

Delete an account field schema

Set an account field value

Delete an account field value