Custom Field
The definitions of a workspace's custom fields — their names, kinds and dropdown options.
Definitions themselves are managed in the Nifty app; this API exposes them read-only. What you do here is look up a definition so you can SET a value on something: include customFields: [{ customFieldId, value }] in a task, project, list or member create or update body.
value is ALWAYS a string, whatever the field kind — send "true" or "false" for a checkbox, a member id for a user field, one of the option values from ?expand=options for a dropdown, and the written-out value for the rest. Send "" to clear a field.
List Custom Fields
List customFields. Returns a paginated envelope (data, total, limit, hasMore, nextCursor). Filterable by 4 fields. Ordered by name unless you pass sort.
Required scope: custom-fields: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: name.
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.
name[eq]Filter where name equals.
name[contains]Filter where name contains.
name[startsWith]Filter where name starts with.
type[eq]Filter where type equals.
type[in]Filter where type is one of (comma-separated list).
inLibrary[eq]Filter where inLibrary equals.
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 Custom Fields › 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 Custom Field
Retrieve a single Custom Field by id.
Required scope: custom-fields:read
path Parameters
id^[0-9A-Za-z_!]+$ · requiredId of the Custom Field.
query Parameters
expandComma-separated relations to inline (see Expanding objects above). Valid values are listed in the enum.
Get Custom Field › Responses
OK
idUnique identifier for this resource.
createdAtCreation timestamp.
nameField name, for example "Priority" or "T-shirt size".
typeWhat kind of value this field holds. It decides how you format the string you send: checkbox takes "true" / "false", user takes a member id, dropdown takes one of the field's option values, and the rest take the value written out (a number, a date, a URL).
associationsThe kinds of thing this field can be attached to.
inLibraryWhether this definition comes from the reusable field library rather than being bound to one workspace. Library definitions are not returned by this API today, so it is always false here.
teamIdThe workspace (team) this field definition belongs to.
updatedAtLast update timestamp.
descriptionOptional help text for this field.
currencyISO currency code for a currency field. Null for every other type.
The selectable choices, for a dropdown field. Fetch them with ?expand=options and send one of the returned values when setting the field.
Roles this field is hidden from. Read-only here — fetch it with ?expand=hiddenFor; visibility is managed in the Nifty app.