A form: a set of questions respondents answer, optionally wired to an automation that creates a task, document, message or check-in from each submission.
This surface covers form structure. Read submitted responses in the Nifty app.
A form's questions are written as a whole: sending fields replaces the entire set, deleting anything you leave out. Keep a question by including its id. A form must always keep at least one question, may hold at most 200, and each question at most 100 choices.
List Forms
List forms. Returns a paginated envelope (data, total, limit, hasMore, nextCursor). Filterable by 6 fields. Ordered by createdAt unless you pass sort.
Required scope: forms:read
query Parameters
sortField to sort by. Prefix with - for descending (-createdAt); a createdAt:desc / createdAt:asc suffix works too, but never both markers at once. Default: createdAt.
cursorOpaque cursor for the next page (the envelope nextCursor).
limitItems per page (1–200, default 50). A larger value is clamped to the cap rather than rejected, so always follow nextCursor instead of assuming one page held everything.
includeTotalWhen true, the response envelope includes the total number of matching rows. Omit it for cheaper pagination.
expandComma-separated relations to inline (see Expanding objects above). Valid values are listed in the enum.
purgeAt[null]Filter where purgeAt is null (pass true).
purgeAt[notNull]Filter where purgeAt is not null (pass true).
purgeAt[gt]Filter where purgeAt is greater than.
purgeAt[gte]Filter where purgeAt is greater than or equal to.
purgeAt[lt]Filter where purgeAt is less than.
purgeAt[lte]Filter where purgeAt is less than or equal to.
automation[eq]Filter where automation equals.
automation[in]Filter where automation is one of (comma-separated list).
docAccessType[eq]Filter where docAccessType equals.
docAccessType[in]Filter where docAccessType is one of (comma-separated list).
projectId[eq]Filter where projectId equals.
projectId[in]Filter where projectId is one of (comma-separated list).
createdById[eq]Filter where createdById equals.
createdById[in]Filter where createdById is one of (comma-separated list).
createdAt[gt]Filter where createdAt is greater than.
createdAt[gte]Filter where createdAt is greater than or equal to.
createdAt[lt]Filter where createdAt is less than.
createdAt[lte]Filter where createdAt is less than or equal to.
List Forms › Responses
OK
The page of results.
totalTotal rows matching the query (across pages).
limithasMorenextCursorOpaque cursor for the next page; null on the last page.
Get Form
Retrieve a single Form by id.
Required scope: forms:read
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the Form.
query Parameters
expandComma-separated relations to inline (see Expanding objects above). Valid values are listed in the enum.
Get Form › Responses
OK
idUnique identifier — an opaque string; never parse or generate one.
createdAtCreation timestamp.
updatedAtLast update timestamp.
createdByActorIdWho created this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records created any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with GET /actors/{id}, whose memberId gives you the person to use against /members.
updatedByActorIdWho last wrote to this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records last written any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with GET /actors/{id}, whose memberId gives you the person to use against /members.
createdByActorTypeThe creator actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from actors.type; read-only, not directly writable.
updatedByActorTypeThe last writer actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from actors.type via the row's updatedByActorId; read-only, not directly writable.
purgeAtWhen this resource will be permanently deleted — soft-delete time + 30-day retention; null while live.
deletedByIdMember who soft-deleted this resource (server-stamped). A member id — resolve it with GET /members/{id}.
nameThe form's name, shown to respondents as its title. Set it with meta.title.
automationWhat Nifty does when the form is submitted: task creates a task, doc a document, message a chat message, checkin a check-in response. null for a plain form that just records answers. When it is task, both targetStatusId and targetListId are required in the same request.
targetStatusIdThe board column a task automation files its new task into. Required whenever automation is task.
targetListIdThe list a task automation files its new task into. Required whenever automation is task.
The form's display metadata. title is the form's name, shown to respondents (also surfaced read-only as name); description is the blurb under it.
What a respondent sees after submitting: a heading, body text, an optional image, an optional redirect, and an optional auto-reply email. Stored verbatim, so its keys are snake_case unlike the rest of this API.
multiSubmitWhether one respondent may submit the form more than once. Defaults to false.
docAccessTypeWho can see the document a doc automation creates: public (the whole team), limited (invited members), private (the author only). Defaults to public.
urlThe public link respondents open to fill this form in. Null until the form has been shared.
projectIdAn optional project to associate this form with. It does not affect who can see the form — forms are visible across the whole workspace.
createdByIdTeam member who created this form — a member id, so resolve it with GET /members/{id}. Read-only, set from the caller. Null for creates that have no member behind them.
The form's questions, in the order respondents see them. This is a full replacement: any existing field missing from the array is deleted, along with its options and any answers already submitted to it — include each field's id to keep it. Omit the key entirely to leave the questions untouched. Cannot be an empty array (a form keeps at least one question), and cannot exceed 200 fields.
The related Project, present only when you pass ?expand=project.
The related Actor, present only when you pass ?expand=createdByActor.
The related Actor, present only when you pass ?expand=updatedByActor.
The related Team Member, present only when you pass ?expand=deletedBy.
Restore Form
Restore a Form that was deleted, returning it to list results. Restoring one that is already active succeeds and changes nothing.
Required scope: forms:delete
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the Form.
Headers
Idempotency-KeyOptional replay key (see Idempotent requests above).
Restore Form › Responses
OK
idUnique identifier — an opaque string; never parse or generate one.
createdAtCreation timestamp.
updatedAtLast update timestamp.
createdByActorIdWho created this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records created any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with GET /actors/{id}, whose memberId gives you the person to use against /members.
updatedByActorIdWho last wrote to this record — a person, an agent, an automation or the system itself. Read-only, stamped by the server on writes made through this API, and null on records last written any other way, so treat it as present-or-null rather than always populated. This is an actor id (a UUID), not a member id: look it up with GET /actors/{id}, whose memberId gives you the person to use against /members.
createdByActorTypeThe creator actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from actors.type; read-only, not directly writable.
updatedByActorTypeThe last writer actor's type (human, agent, cron, recurringTask, automation, outboxRetry, systemDefault). Server-derived from actors.type via the row's updatedByActorId; read-only, not directly writable.
purgeAtWhen this resource will be permanently deleted — soft-delete time + 30-day retention; null while live.
deletedByIdMember who soft-deleted this resource (server-stamped). A member id — resolve it with GET /members/{id}.
nameThe form's name, shown to respondents as its title. Set it with meta.title.
automationWhat Nifty does when the form is submitted: task creates a task, doc a document, message a chat message, checkin a check-in response. null for a plain form that just records answers. When it is task, both targetStatusId and targetListId are required in the same request.
targetStatusIdThe board column a task automation files its new task into. Required whenever automation is task.
targetListIdThe list a task automation files its new task into. Required whenever automation is task.
The form's display metadata. title is the form's name, shown to respondents (also surfaced read-only as name); description is the blurb under it.
What a respondent sees after submitting: a heading, body text, an optional image, an optional redirect, and an optional auto-reply email. Stored verbatim, so its keys are snake_case unlike the rest of this API.
multiSubmitWhether one respondent may submit the form more than once. Defaults to false.
docAccessTypeWho can see the document a doc automation creates: public (the whole team), limited (invited members), private (the author only). Defaults to public.
urlThe public link respondents open to fill this form in. Null until the form has been shared.
projectIdAn optional project to associate this form with. It does not affect who can see the form — forms are visible across the whole workspace.
createdByIdTeam member who created this form — a member id, so resolve it with GET /members/{id}. Read-only, set from the caller. Null for creates that have no member behind them.
The form's questions, in the order respondents see them. This is a full replacement: any existing field missing from the array is deleted, along with its options and any answers already submitted to it — include each field's id to keep it. Omit the key entirely to leave the questions untouched. Cannot be an empty array (a form keeps at least one question), and cannot exceed 200 fields.