Skip to content
HeyX API

Create Problem

Required scope: problem:create

POST /public-api/publicapi.v1.Problem/CreateProblem

Creates a general or template-backed problem. title is required, must be nonblank, and is limited to 200 characters. A general problem can be customerless; omit customerId rather than sending an empty string. Omitted severity defaults to 2; explicit severity is 1 through 5.

The actor needs problem write access and, when customerId is supplied, customer write access. Selecting a template additionally requires content-template read access. API-key scopes do not replace these permissions.

The smallest general-problem request is:

{ "title": "test" }

Optional assigneeIds are account IDs, not member IDs, from ListMembers or SearchMembers. Assignees must be active workspace members. Up to 100 unique assignees, 100 labels, and 500 manual text tasks are supported. Description and each task body are limited to 20,000 characters. Each label needs an active workspace label id or a nonblank name; names are limited to 100 characters and colorHex to 20.

Generated Reference
POST /public-api/publicapi.v1.Problem/CreateProblem

Creates a general or template-backed problem. Customer is optional unless the template contains advanced tasks. This operation is not idempotent.

Request CreateProblemRequest
Response CreateProblemResponse

CreateProblemRequest

Field Type Description
customer_id optional string
title string
description string
severity optional int32 Defaults to the selected template's severity, or 2 for a general problem.
assignee_ids repeated string Account IDs returned by ListMembers.
tasks repeated CreateProblemTaskInput
labels repeated ProblemLabel
problem_template_id optional string Preserves title. Empty description uses the template description. Template tasks are retained; supplied tasks append. Required assignments and blocks cannot be removed. Discover requirements through ProblemTemplate.

CreateProblemResponse

Field Type
problem Problem

Related Types

CreateProblemTaskInput

Field Type
body string

ProblemLabel

Field Type
id optional string
name string
color_hex string

Problem

Field Type
id string
title string
description string
status ProblemStatus
severity int32
customer_id optional string
problem_template_id optional string
problem_template_name string
assignees repeated ProblemAssignee
labels repeated ProblemLabel
resolved_at optional int64
closed_at optional int64
archived_at optional int64
created_at int64
updated_at int64
total_tasks int32
completed_tasks int32

ProblemAssignee

Field Type
id string
display_name string
kind string 
{
  "customerId": "<customer-id>",
  "title": "Inspection follow-up",
  "description": "Check the inverter installation",
  "severity": 3,
  "assigneeIds": ["<account-id>"],
  "tasks": [{ "body": "Schedule a site visit" }]
}

Use a template

Section titled “Use a template”

Discover an active template with List Problem Templates and inspect Get Problem Template before choosing it. Use the same creation endpoint:

{
  "title": "Inspection follow-up",
  "problemTemplateId": "<problem-template-id>",
  "customerId": "<customer-id>",
  "tasks": [{ "body": "Call the customer after inspection" }]
}

The explicit title is preserved. Empty or omitted description inherits the template description; omitted severity inherits template severity. Template tasks remain and supplied tasks append. Required template assignees and journey track blocks are retained. Templates with advanced tasks require a customer. Inherited and supplied values together must fit the creation limits; oversized templates fail rather than silently dropping tasks or requirements.

Creating a template-backed problem is not the same as authoring a template. Arbitrary workflow/action configuration and advanced-task configuration cannot be supplied in this request. The response contains a bounded problem summary; use Get Problem for task detail.

This operation is not idempotent. Do not blindly retry after a timeout.

HeyX API