Coperniq formTemplates API
The formTemplates API from Coperniq — 2 operation(s) for formtemplates.
OpenAPI Specification
openapi: 3.1.0
info:
title: API Key accounts formTemplates API
version: 1.0.0
servers:
- url: https://api.coperniq.io/v1
description: Production server
tags:
- name: formTemplates
paths:
/form-templates:
get:
operationId: list-form-templates
summary: List Form Templates
description: 'Retrieve all form templates for the company. Form templates are reusable form definitions
that define the layout, fields, assignees, and labels for forms created on projects/workflows.
'
tags:
- formTemplates
parameters:
- name: includeArchived
in: query
description: Include archived form templates in results
required: false
schema:
type: boolean
default: false
- name: x-api-key
in: header
required: true
schema:
type: string
responses:
'200':
description: List of form templates
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/FormTemplateSummary'
'401':
description: Authentication failed
content:
application/json:
schema:
$ref: '#/components/schemas/ListFormTemplatesRequestUnauthorizedError'
/form-templates/{formTemplateId}:
get:
operationId: get-form-template-by-id
summary: Get Form Template
description: 'Retrieve a specific form template by ID, including its full field layout.
'
tags:
- formTemplates
parameters:
- name: formTemplateId
in: path
description: Form template identifier
required: true
schema:
type: integer
- name: x-api-key
in: header
required: true
schema:
type: string
responses:
'200':
description: Form template details
content:
application/json:
schema:
$ref: '#/components/schemas/FormTemplateDetail'
'400':
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/GetFormTemplateByIdRequestBadRequestError'
'401':
description: Authentication failed
content:
application/json:
schema:
$ref: '#/components/schemas/GetFormTemplateByIdRequestUnauthorizedError'
'404':
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/GetFormTemplateByIdRequestNotFoundError'
patch:
operationId: update-form-template
summary: Update Form Template
description: 'Update an existing form template. All fields are optional — only provided fields are updated. `formLayouts` is optional — omit it to leave the existing layout untouched.
**formLayouts replacement:** When provided, the `formLayouts` array **fully replaces** all layout groups and their fields on the template. Position is determined by array order.
**IDs are not stable across updates.** Every update internally deletes all existing layout rows and inserts new ones, so every group and field receives a new auto-generated ID after each PATCH. The IDs returned in a GET response are only valid until the next PATCH. Do not store or rely on layout IDs across updates.
**Using `id` in the request:** You can pass `{ "id": <id from a recent GET> }` for a group or field to reference its current data without repeating all attributes — the API will look up the existing name, type, isRequired, etc. and carry them forward. This is a convenience shortcut for the current request only; the ID will be different in the response.
**Assignee (mutually exclusive — use at most one):**
- `assigneeId` — assign a specific user by ID.
- `assigneeProperty` — assign by project property key: `OWNER`, `SALES_REP`, `PROJECT_MANAGER`, `CREATED_BY`, or a custom PERSON property `keyName`.
- `assigneeTeamId` — assign a team: the team lead becomes the assignee and all other team members are added as collaborators.
**Collaborators:**
- `collaborators` — replaces the list of direct user collaborator IDs.
- `collaboratorProperties` — replaces the list of property-based collaborators. Each value is a standard key (`OWNER`, `SALES_REP`, `PROJECT_MANAGER`, `CREATED_BY`) or a custom PERSON property `keyName`.
- `collaboratorTeamIds` — team IDs whose members are resolved to user IDs and merged (deduplicated) into collaborators alongside any direct `collaborators` and members from `assigneeTeamId`.
'
tags:
- formTemplates
parameters:
- name: formTemplateId
in: path
required: true
schema:
type: string
- name: x-api-key
in: header
required: true
schema:
type: string
responses:
'200':
description: Form template updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/FormTemplateDetail'
'400':
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateFormTemplateRequestBadRequestError'
'401':
description: Authentication failed
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateFormTemplateRequestUnauthorizedError'
'404':
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateFormTemplateRequestNotFoundError'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/FormTemplateUpdate'
components:
schemas:
FormTemplateDetailCollaboratorsItems:
type: object
properties:
id:
type: integer
firstName:
type: string
lastName:
type: string
email:
type: string
title: FormTemplateDetailCollaboratorsItems
ListFormTemplatesRequestUnauthorizedError:
type: object
properties:
message:
type: string
code:
$ref: '#/components/schemas/FormTemplatesGetResponsesContentApplicationJsonSchemaCode'
title: ListFormTemplatesRequestUnauthorizedError
FormTemplateDetailLabelsItems:
type: object
properties:
id:
type: integer
label:
type: string
color:
type: string
title: FormTemplateDetailLabelsItems
FormTemplateSummary:
type: object
properties:
id:
type: integer
description: Form template identifier
name:
type: string
description: Template name
fileId:
type:
- integer
- 'null'
description: Associated file identifier
isArchived:
type: boolean
description: Whether the template is archived
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
createdBy:
oneOf:
- $ref: '#/components/schemas/FormTemplateSummaryCreatedBy'
- type: 'null'
parentWorkOrderTemplateId:
type:
- integer
- 'null'
title: FormTemplateSummary
GetFormTemplateByIdRequestNotFoundError:
type: object
properties:
message:
type: string
code:
$ref: '#/components/schemas/FormTemplatesFormTemplateIdGetResponsesContentApplicationJsonSchemaCode'
title: GetFormTemplateByIdRequestNotFoundError
FormTemplateLayout:
type: object
properties:
id:
type: integer
description: Layout row identifier
name:
type:
- string
- 'null'
description: Group label for GROUP type, null for COLUMN type
type:
$ref: '#/components/schemas/FormTemplateLayoutType'
description: GROUP = section header containing child items in properties. COLUMN = an actual form field.
columnId:
type:
- integer
- 'null'
description: Column (property) identifier. Null for GROUP items.
column:
$ref: '#/components/schemas/FormTemplateLayoutColumn'
description: Field metadata. Only present for COLUMN type.
properties:
type: array
items:
$ref: '#/components/schemas/FormTemplateChildLayout'
description: Nested child items. Populated for GROUP items (containing COLUMN children). Empty array for COLUMN items.
fields:
type: array
items:
$ref: '#/components/schemas/FormTemplateChildLayout'
description: Deprecated alias of properties; kept for backward compatibility. Use properties instead.
title: FormTemplateLayout
GetFormTemplateByIdRequestUnauthorizedError:
type: object
properties:
message:
type: string
code:
$ref: '#/components/schemas/FormTemplatesFormTemplateIdGetResponsesContentApplicationJsonSchemaCode'
title: GetFormTemplateByIdRequestUnauthorizedError
FormTemplatesFormTemplateIdPatchResponsesContentApplicationJsonSchemaCode:
type: string
enum:
- NOT_FOUND
title: FormTemplatesFormTemplateIdPatchResponsesContentApplicationJsonSchemaCode
FormTemplatePropertyInput:
type: object
properties:
id:
type: integer
description: 'ID of an existing field from a recent GET response. When provided without other fields (and without projectPropertyKey), the API carries forward the field''s current name, type, isRequired, and all other attributes. Note: IDs change after every update — only use an id obtained from the most recent GET on this template.
'
projectPropertyKey:
type: string
description: 'The keyName of an existing project property. When provided, the API resolves the property and auto-populates all field attributes. All other fields on this object become optional overrides.
'
name:
type: string
description: Field label. When projectPropertyKey is used, providing name overrides the property's display name on the form.
type:
$ref: '#/components/schemas/FormTemplatePropertyInputType'
description: 'Field type. Required when projectPropertyKey is not provided. TEXT = text input, NUMERIC = number input, DROPDOWN = single or multi-select (set multiple: true for multi-select), FILE = file attachment.
'
isRequired:
type: boolean
description: Whether the field is required. Overrides the property default when projectPropertyKey is used.
isReadOnly:
type: boolean
description: Whether the field is read-only. Overrides the property default when projectPropertyKey is used.
multiple:
type: boolean
description: When true, allows multiple selections. Applicable to DROPDOWN fields.
notes:
type:
- string
- 'null'
description: Helper text shown beneath the field.
options:
$ref: '#/components/schemas/FormTemplatePropertyInputOptions'
description: Field-type-specific configuration (e.g. dropdown choices).
referenceFileIds:
type: array
items:
type: integer
description: File IDs attached as reference documents to this field.
description: 'A single field inside a form group.
**Using `projectPropertyKey` (recommended for project-linked fields)**
When `projectPropertyKey` is provided, the API looks up the project property by its key
and automatically fills in `name`, `type`, `isRequired`, `isReadOnly`, `multiple`, and `options`
from the property definition. All other fields become optional overrides — for example, you can
pass `isRequired: true` to override the property''s default.
Example — link to a project property by key:
```json
{ "projectPropertyKey": "sales_rep" }
```
Example — link and override required:
```json
{ "projectPropertyKey": "sales_rep", "isRequired": true }
```
**Manual field (no `projectPropertyKey`)**
When `projectPropertyKey` is omitted, `type` is required and all other fields
(name, isRequired, isReadOnly) should be provided explicitly.
'
title: FormTemplatePropertyInput
FormTemplateChildLayoutColumn:
type: object
properties:
id:
type: integer
name:
type: string
type:
type: string
multiple:
type: boolean
isRequired:
type: boolean
isReadOnly:
type: boolean
description: Field metadata
title: FormTemplateChildLayoutColumn
FormTemplateUpdate:
type: object
properties:
name:
type: string
description: Template name. Optional — omit to leave the existing name untouched.
formLayouts:
type: array
items:
$ref: '#/components/schemas/FormTemplateLayoutInput'
description: 'Optional. When provided, **fully replaces** all layout groups and their fields. Include existing groups with their `id` to keep/update them; omit the `id` for new groups. Groups not included are removed. Array order determines position.
If omitted, the existing layout is left untouched.
'
assigneeId:
type:
- integer
- 'null'
description: Direct user ID to assign. Mutually exclusive with `assigneeProperty` and `assigneeTeamId`.
assigneeProperty:
type:
- string
- 'null'
description: 'Property-based assignee. Use a standard key (`OWNER`, `SALES_REP`, `PROJECT_MANAGER`, `CREATED_BY`) or a custom PERSON property keyName. Mutually exclusive with `assigneeId` and `assigneeTeamId`.
'
assigneeTeamId:
type:
- integer
- 'null'
description: 'Assign a team: the team lead becomes the assignee and all other team members are added as collaborators. Mutually exclusive with `assigneeId` and `assigneeProperty`.
'
collaborators:
type: array
items:
type: integer
description: Replaces the list of direct user collaborator IDs.
collaboratorProperties:
type: array
items:
type: string
description: 'Property-based collaborators. Each value is a standard key (`OWNER`, `SALES_REP`, `PROJECT_MANAGER`, `CREATED_BY`) or a custom PERSON property keyName.
'
collaboratorTeamIds:
type: array
items:
type: integer
description: 'Team IDs whose members are added as collaborators. Resolved to individual user IDs and merged (deduplicated) with any direct `collaborators` and members from `assigneeTeamId`.
'
labels:
type: array
items:
type: integer
description: Replaces the list of label IDs applied to the template.
dueDateXDaysAfter:
type:
- integer
- 'null'
description: Number of days after creation that the form is due.
title: FormTemplateUpdate
UpdateFormTemplateRequestBadRequestError:
type: object
properties:
message:
type: string
code:
$ref: '#/components/schemas/FormTemplatesFormTemplateIdPatchResponsesContentApplicationJsonSchemaCode'
field:
type: string
description: Field that caused the validation error (if applicable)
title: UpdateFormTemplateRequestBadRequestError
FormTemplateDetail:
type: object
properties:
id:
type: integer
description: Form template identifier
name:
type: string
description: Template name
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
assignee:
oneOf:
- $ref: '#/components/schemas/FormTemplateDetailAssignee'
- type: 'null'
description: Direct user assignment. Null if assigneeProperty is used instead.
assigneeProperty:
type:
- string
- 'null'
description: 'Property-based assignee key. Returns a standard key (`OWNER`, `SALES_REP`, `PROJECT_MANAGER`, `CREATED_BY`) or the keyName of a custom PERSON property. Null if a direct user assignee is set.
'
collaborators:
type: array
items:
$ref: '#/components/schemas/FormTemplateDetailCollaboratorsItems'
description: Direct user collaborators.
collaboratorProperties:
type: array
items:
type: string
description: 'Property-based collaborator keys. Each value is a standard key (`OWNER`, `SALES_REP`, `PROJECT_MANAGER`, `CREATED_BY`) or the keyName of a custom PERSON property.
'
labels:
type: array
items:
$ref: '#/components/schemas/FormTemplateDetailLabelsItems'
dueDateXDaysAfter:
type:
- integer
- 'null'
description: Number of days after creation that the form is due
formLayouts:
type: array
items:
$ref: '#/components/schemas/FormTemplateLayout'
description: Top-level layout items (GROUP sections and standalone COLUMN fields). Only root-level items are returned; child items are nested inside each GROUP's properties array.
title: FormTemplateDetail
FormTemplateChildLayoutType:
type: string
enum:
- COLUMN
title: FormTemplateChildLayoutType
FormTemplateDetailAssignee:
type: object
properties:
id:
type: integer
firstName:
type: string
lastName:
type: string
email:
type: string
description: Direct user assignment. Null if assigneeProperty is used instead.
title: FormTemplateDetailAssignee
FormTemplatePropertyInputOptions:
type: object
properties: {}
description: Field-type-specific configuration (e.g. dropdown choices).
title: FormTemplatePropertyInputOptions
FormTemplatesGetResponsesContentApplicationJsonSchemaCode:
type: string
enum:
- UNAUTHORIZED
title: FormTemplatesGetResponsesContentApplicationJsonSchemaCode
UpdateFormTemplateRequestNotFoundError:
type: object
properties:
message:
type: string
code:
$ref: '#/components/schemas/FormTemplatesFormTemplateIdPatchResponsesContentApplicationJsonSchemaCode'
title: UpdateFormTemplateRequestNotFoundError
FormTemplateSummaryCreatedBy:
type: object
properties:
id:
type: integer
firstName:
type: string
lastName:
type: string
email:
type: string
title: FormTemplateSummaryCreatedBy
FormTemplatesFormTemplateIdGetResponsesContentApplicationJsonSchemaCode:
type: string
enum:
- NOT_FOUND
title: FormTemplatesFormTemplateIdGetResponsesContentApplicationJsonSchemaCode
GetFormTemplateByIdRequestBadRequestError:
type: object
properties:
message:
type: string
code:
$ref: '#/components/schemas/FormTemplatesFormTemplateIdGetResponsesContentApplicationJsonSchemaCode'
field:
type: string
description: Field that caused the validation error (if applicable)
title: GetFormTemplateByIdRequestBadRequestError
FormTemplateLayoutInput:
type: object
properties:
id:
type: integer
description: 'ID of an existing group from a recent GET response. When provided without other fields, the API carries forward the group''s current name. Note: IDs change after every update — only use an id obtained from the most recent GET on this template.
'
name:
type:
- string
- 'null'
description: Group title displayed above the fields.
properties:
type: array
items:
$ref: '#/components/schemas/FormTemplatePropertyInput'
description: Ordered list of fields inside this group.
description: A form group containing a title and an ordered list of field properties.
title: FormTemplateLayoutInput
FormTemplateLayoutColumn:
type: object
properties:
id:
type: integer
name:
type: string
type:
type: string
description: 'Field type: DROPDOWN, NUMERIC, BOOLEAN, DATE, DATETIME, TEXT, LONG_TEXT, PERSON, FILE, SEPARATOR, PROJECT, LINK, TIMERANGEDAYS'
multiple:
type: boolean
isRequired:
type: boolean
isReadOnly:
type: boolean
description: Field metadata. Only present for COLUMN type.
title: FormTemplateLayoutColumn
FormTemplateLayoutType:
type: string
enum:
- GROUP
- COLUMN
description: GROUP = section header containing child items in properties. COLUMN = an actual form field.
title: FormTemplateLayoutType
FormTemplatePropertyInputType:
type: string
enum:
- TEXT
- NUMERIC
- DROPDOWN
- FILE
description: 'Field type. Required when projectPropertyKey is not provided. TEXT = text input, NUMERIC = number input, DROPDOWN = single or multi-select (set multiple: true for multi-select), FILE = file attachment.
'
title: FormTemplatePropertyInputType
FormTemplateChildLayout:
type: object
properties:
id:
type: integer
description: Layout row identifier
name:
type:
- string
- 'null'
type:
$ref: '#/components/schemas/FormTemplateChildLayoutType'
columnId:
type:
- integer
- 'null'
description: Column (property) identifier
column:
$ref: '#/components/schemas/FormTemplateChildLayoutColumn'
description: Field metadata
title: FormTemplateChildLayout
UpdateFormTemplateRequestUnauthorizedError:
type: object
properties:
message:
type: string
code:
$ref: '#/components/schemas/FormTemplatesFormTemplateIdPatchResponsesContentApplicationJsonSchemaCode'
title: UpdateFormTemplateRequestUnauthorizedError
securitySchemes:
BasicAuth:
type: http
scheme: basic