Skip to main content
Using TypeScript? Check out our GraphQL SDK for a fully typed client.
Tenant fields are custom fields you can attach to a tenant — for example a plan name, MRR, account owner or any other attribute that is meaningful at the tenant level rather than per-customer. Working with tenant fields involves two layers:
  1. Tenant field schemas define what fields exist (type, label, options). You create the schema once.
  2. Tenant field values are the per-tenant values stored against a given schema.
This is the same model as thread fields — see thread fields for the equivalent on threads. These operations require the following permissions:
  • tenant:edit
  • tenantFieldSchema:create / tenantFieldSchema:edit / tenantFieldSchema:delete (for schema operations)

​
Create or update tenant field schemas

upsertTenantFieldSchema 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 and ENUM_TYPE (use options to define the allowed values).
Mutation
mutation upsertTenantFieldSchema($input: UpsertTenantFieldSchemaInput!) {
  upsertTenantFieldSchema(input: $input) {
    result
    tenantFieldSchemas {
      id
      externalFieldId
      label
      type
      options
      isVisible
      order
    }
    error {
      message
      type
      code
      fields {
        field
        message
        type
      }
    }
  }
}
Variables
{
  "input": {
    "tenantFieldSchemas": [
      {
        "source": "your-system",
        "externalFieldId": "plan",
        "label": "Plan",
        "type": "STRING_TYPE",
        "isVisible": true,
        "order": 0
      }
    ]
  }
}

​
Delete a tenant field schema

Deleting a schema also removes any tenant field values stored against it.
Mutation
mutation deleteTenantFieldSchema($input: DeleteTenantFieldSchemaInput!) {
  deleteTenantFieldSchema(input: $input) {
    tenantFieldSchema {
      id
      externalFieldId
    }
    error {
      message
      type
      code
      fields {
        field
        message
        type
      }
    }
  }
}
Variables
{
  "input": {
    "tenantFieldSchemaId": "tfs_01J7Z..."
  }
}

​
Set a tenant field value

Once a schema exists, use upsertTenantField to set or update the value for a specific tenant. Pass exactly one of stringValue, numberValue, booleanValue, arrayValue or dateValue matching the schema’s type.
Mutation
mutation upsertTenantField($input: UpsertTenantFieldInput!) {
  upsertTenantField(input: $input) {
    result
    tenantField {
      id
      externalFieldId
      value {
        __typename
        ... on TenantFieldStringValue {
          stringValue
        }
        ... on TenantFieldNumberValue {
          numberValue
        }
        ... on TenantFieldBooleanValue {
          booleanValue
        }
      }
    }
    error {
      message
      type
      code
      fields {
        field
        message
        type
      }
    }
  }
}
Variables
{
  "input": {
    "tenantFieldIdentifier": {
      "tenantId": "te_01H8H46YPB2S4MAJM382FG9423",
      "externalFieldId": "plan"
    },
    "type": "STRING_TYPE",
    "stringValue": "enterprise"
  }
}

​
Delete a tenant field value

To clear a tenant’s value for a specific field without removing the schema itself, call deleteTenantField.
Mutation
mutation deleteTenantField($input: DeleteTenantFieldInput!) {
  deleteTenantField(input: $input) {
    tenantField {
      id
      externalFieldId
    }
    error {
      message
      type
      code
      fields {
        field
        message
        type
      }
    }
  }
}
Variables
{
  "input": {
    "tenantFieldId": "tf_01J7Z..."
  }
}