API reference › Forms › Request forms in the portals

Fetch the custom form for the client portal Add Request screen

GET /v1/portal/client/request-form

Scope
forms:read
Roles
client

Same body as GET /forms/module-fields/client_request, for a client portal user (who has no Forms access). Always the module's generic active form, the one the create and update requests validate against; assignTo, clientId and locationId query values are ignored.

Parameters

None of its own.

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

Example request

Shell
curl "https://api.fetchfido.ai/v1/portal/client/request-form" \
  -H "Authorization: Bearer $FIDO_API_KEY" \
  -H "X-Tenant-ID: $FIDO_TENANT_ID"

Try it

Responses

200 Array of form schemas, or null when no active form applies

Array of form schemas, 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 .

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.