API reference › Forms

Fetch custom-fields schema for a module (add-mode)

GET /v1/forms/module-fields/{module}

Scope
forms:read
Roles
admin, scheduler

Returns an array of customFields response shapes (form + groups + fields with default values) — one entry per active internal form matching the given scope, merged with the module's generic form. Used when rendering the add screen for a module that does not yet have a record.

Parameters

Path parameters

NameTypeDescription
module requiredstring

Module key (client, consumer, assignment, shift, service-provider, client-location)

One of: client, consumer, assignment, shift, service-provider, client-location.

Query parameters

NameTypeDescription
assignTostring

Form scope for assignment/shift: 'organization' (generic) or 'client' (client-specific, with clientId).

One of: organization, client.

clientIdstring

Client id (CLT-…) to fetch the client-specific form for assignment/shift/client-location.

Example CLT-8LE81N.

locationIdstring

Client location id (CLTLOC-…) to fetch the location-specific form (client-location).

Example CLTLOC-423LS.

Every call also sends Authorization and X-Tenant-ID; see Getting started.

Example request

Shell
curl "https://api.fetchfido.ai/v1/forms/module-fields/{module}" \
  -H "Authorization: Bearer $FIDO_API_KEY" \
  -H "X-Tenant-ID: $FIDO_TENANT_ID"

Try it

Responses

200 Form fields retrieved, or null when no active form applies

Form fields retrieved, or null when no active form applies.

JSON
{
  "success": true,
  "message": "Form fields retrieved!",
  "data": [
    {
      "form": {
        "id": "FRM-7KQ2PA",
        "name": "Intake",
        "description": "string",
        "isPublished": true,
        "formType": "internal",
        "moduleType": {
          "id": "client",
          "label": "Client"
        },
        "status": {
          "id": 1,
          "label": "Active"
        },
        "assignTo": {
          "id": "organization",
          "label": "Organization",
          "isCustom": false
        },
        "version": 2,
        "multiStep": false,
        "reviewStep": false,
        "externalVisibility": {
          "id": "private",
          "label": "Private"
        },
        "lastUsedDate": "01/15/2025",
        "settings": {}
      },
      "startsStep": 1,
      "groups": [
        {
          "label": "Contact",
          "isRequired": false,
          "isArchived": false,
          "fields": [
            null
          ]
        }
      ]
    }
  ]
}
Response fields (44)

3 top-level fields; 1 hold nested fields, listed below.

FieldTypeDescription
successboolean

Example true.

messagestring

Example Form fields retrieved!.

dataarray of object or null (41 nested)

One entry per active form in scope, each in the same shape the form-details endpoint returns, with each field's empty value filled in, archived placements dropped and a usage count attached. Sent as null — not an empty array — when no active form applies.

Nested fields

data 41 fields
FieldTypeDescription
data[].formobject
data[].form.idstring

The form code.

Example FRM-7KQ2PA.

data[].form.namestring

Example Intake.

data[].form.descriptionstring or null
data[].form.isPublishedboolean

Example true.

data[].form.formTypestring or null

Example internal.

data[].form.moduleTypeobject or null
data[].form.moduleType.idstring

Example client.

data[].form.moduleType.labelstring

Example Client.

data[].form.statusobject or null
data[].form.status.idinteger or string

Example 1.

data[].form.status.labelstring

Example Active.

data[].form.assignToobject or null
data[].form.assignTo.idstring

Example organization.

data[].form.assignTo.labelstring

Example Organization.

data[].form.assignTo.isCustomboolean

Example false.

data[].form.versioninteger or null

Example 2.

data[].form.multiStepboolean

Example false.

data[].form.reviewStepboolean

Only meaningful while multiStep is true.

Example false.

data[].form.externalVisibilityobject or null
data[].form.externalVisibility.idstring

One of: public, private. Example private.

data[].form.externalVisibility.labelstring

Example Private.

data[].form.lastUsedDatestring or null

Example 01/15/2025.

data[].form.settingsobject or null
data[].startsStepinteger or null

Example 1.

data[].groupsarray of object

Field groups in render order; a single-step form has one.

data[].groups[].labelstring or null

Example Contact.

data[].groups[].isRequiredboolean

Example false.

data[].groups[].isArchivedboolean

Example false.

data[].groups[].fieldsarray of object
data[].groups[].fields[].fieldKeystring

Example preferred_name.

data[].groups[].fields[].labelstring

Example Preferred name.

data[].groups[].fields[].typestring

Example text.

data[].groups[].fields[].isDefaultboolean

Example false.

data[].groups[].fields[].isRequiredboolean

Example true.

data[].groups[].fields[].isArchivedboolean

Example false.

data[].groups[].fields[].valueany or null

The field's type-correct empty value in add mode: false, null, [] or the empty string.

data[].groups[].fields[].usageCountinteger or null

Active forms this field appears on.

Example 3.

data[].groups[].fields[].settingsobject or null
data[].groups[].fields[].uiobject or null
data[].groups[].fields[].validationobject or null
401 Not signed in

Missing, invalid or expired API key.

JSON
{
  "success": false,
  "message": "Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for.",
  "errors": null,
  "code": "API_KEY_MISSING"
}
Response fields (4)
FieldTypeDescription
successboolean

Example false.

messagestring

Example Invalid API key. Org and user tier keys must send an X-Tenant-ID header naming the organization the key was issued for..

errorsany or null

Null on this status.

codestring

Machine-readable reason, for branching on in client code.

One of: API_KEY_MISSING, API_KEY_INVALID, API_KEY_EXPIRED. Example API_KEY_MISSING.

403 Not allowed

Scope, tenant, IP allow-list or RBAC check failed.

JSON
{
  "success": false,
  "message": "You don't have permission to access this endpoint. This API key is missing the 'forms:read' scope.",
  "errors": null,
  "code": ""
}
Response fields (4)
FieldTypeDescription
successboolean

Example false.

messagestring

Example You don't have permission to access this endpoint. This API key is missing the 'forms:read' scope..

errorsany or null

Null on this status.

codestring

Always empty on this status.

Example .

422 Validation failed

Unsupported module

JSON
{
  "success": false,
  "message": "Unable to save. Please check the highlighted fields",
  "errors": null,
  "code": ""
}
Response fields (4)
FieldTypeDescription
successboolean

Example false.

messagestring

Example Unable to save. Please check the highlighted fields.

errorsany or null

Details when the handler has them — a field-keyed object, a single string, or null.

codestring

Empty unless the handler sets one.

Example .

429 Too many requests

Rate limit exceeded. See Retry-After.

JSON
{
  "success": false,
  "message": "You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds.",
  "errors": null,
  "code": "RATE_LIMITED"
}
Response fields (4)
FieldTypeDescription
successboolean

Example false.

messagestring

Example You've exceeded this API key's rate limit of 120 requests per minute. Try again in 37 seconds..

errorsany or null

Null on this status.

codestring

Machine-readable reason, for branching on in client code.

One of: RATE_LIMITED. Example RATE_LIMITED.