API reference › Forms

Update a form

PATCH /v1/forms/{form}

Scope
forms:edit
Roles
admin, scheduler

Update an existing form. Groups and Fields are fully replaced. On a Contact form a recipient list (form.notifyTo, notifyCc, notifyBcc) that is not sent is left as stored, and one sent empty is cleared; the module type cannot change once the form has submissions.

Parameters

Path parameters

NameTypeDescription
form requiredinteger

Form ID

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

Request body required

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

FieldTypeDescription
scopestring or null

external requires form.submissionStatus and form.externalVisibility.

One of: internal, external.

form requiredobject (42 nested)
groups requiredarray of object (14 nested)

Nested fields

form 42 fields
FieldTypeDescription
form.idstring or null

Form code of an existing form.

form.name requiredstring

max length 255. Example Intake form.

form.descriptionstring or null
form.isPublishedboolean or null

Publishing turns on the stricter field rules.

Example false.

form.status requiredobject
form.status.idinteger or string

Example 1.

form.status.labelstring or null

Example Example.

form.moduleType requiredobject

The module the form collects, such as assignment, shift, client or consumer.

form.moduleType.idinteger or string

Example 1.

form.moduleType.labelstring or null

Example Example.

form.submissionStatusobject

Status a submission lands in. Required when scope is external.

form.submissionStatus.idinteger or string

Example 1.

form.submissionStatus.labelstring or null

Example Example.

form.externalVisibilityobject or null

Required for an external form.

form.externalVisibility.idstring

One of: public, private.

form.externalVisibility.labelstring
form.assignToobject or null
form.assignTo.idstring
form.assignTo.labelstring
form.assignTo.isCustomboolean or null
form.clientIdarray of object or null
form.clientId[].idinteger or string

Example 1.

form.clientId[].labelstring or null

Example Example.

form.consumerIdarray of object or null
form.consumerId[].idinteger or string

Example 1.

form.consumerId[].labelstring or null

Example Example.

form.serviceProviderIdarray of object or null
form.serviceProviderId[].idinteger or string

Example 1.

form.serviceProviderId[].labelstring or null

Example Example.

form.applicableLocationIdarray of object or null
form.applicableLocationId[].idinteger or string

Example 1.

form.applicableLocationId[].labelstring or null

Example Example.

form.financeReferenceIdarray of object or null
form.financeReferenceId[].idinteger or string

Example 1.

form.financeReferenceId[].labelstring or null

Example Example.

form.multiStepboolean or null

Show groups that start a step as separate pages.

form.reviewStepboolean or null

Add a review page before submit.

form.settingsobject or null
form.settings.thankYouMessagestring or null

max length 500.

form.notifyToarray of string or null

Submission notice recipients: email addresses.

form.notifyCcarray of string or null
form.notifyBccarray of string or null
groups 14 fields
FieldTypeDescription
groups[].idinteger or null

Existing group to keep.

groups[].name requiredstring

Example Contact details.

groups[].order requiredinteger

Example 1.

groups[].startsStepboolean or null
groups[].stepTitlestring or null

max length 255.

groups[].fields requiredarray of object

min items 1.

groups[].fields[].idinteger or null

Existing field to keep.

groups[].fields[].labelstring

Example Preferred contact time.

groups[].fields[].typestring

One of: text, textarea, number, email, phone, date, time, select, checkbox, toggle, file, radio, group.

groups[].fields[].isRequiredboolean or null
groups[].fields[].isVisibleboolean or null
groups[].fields[].isArchivedboolean or null
groups[].fields[].orderinteger

Example 1.

groups[].fields[].settingsobject or null

Per-type settings: ui (placeholder, style), validation, options [{label, value}], default, selectType / checkboxType / fileType (single or multiple), maxFileSize, toggleOnLabel / toggleOffLabel, and subFields for a group field.

Example

JSON
{
  "scope": "internal",
  "form": {
    "id": "string",
    "name": "Intake form",
    "description": "string",
    "isPublished": false,
    "status": {
      "id": 1,
      "label": "Example"
    },
    "moduleType": {
      "id": 1,
      "label": "Example"
    },
    "submissionStatus": {
      "id": 1,
      "label": "Example"
    },
    "externalVisibility": {
      "id": "public",
      "label": "string"
    },
    "assignTo": {
      "id": "string",
      "label": "string",
      "isCustom": true
    },
    "clientId": [
      {
        "id": 1,
        "label": "Example"
      }
    ],
    "consumerId": [
      {
        "id": 1,
        "label": "Example"
      }
    ],
    "serviceProviderId": [
      {
        "id": 1,
        "label": "Example"
      }
    ],
    "applicableLocationId": [
      {
        "id": 1,
        "label": "Example"
      }
    ],
    "financeReferenceId": [
      {
        "id": 1,
        "label": "Example"
      }
    ],
    "multiStep": true,
    "reviewStep": true,
    "settings": {
      "thankYouMessage": "string"
    },
    "notifyTo": [
      "string"
    ],
    "notifyCc": [
      "string"
    ],
    "notifyBcc": [
      "string"
    ]
  },
  "groups": [
    {
      "id": 0,
      "name": "Contact details",
      "order": 1,
      "startsStep": true,
      "stepTitle": "string",
      "fields": [
        {
          "id": 0,
          "label": "Preferred contact time",
          "type": "text",
          "isRequired": true,
          "isVisible": true,
          "isArchived": true,
          "order": 1,
          "settings": {}
        }
      ]
    }
  ]
}

Example request

Shell
curl -X PATCH "https://api.fetchfido.ai/v1/forms/{form}" \
  -H "Authorization: Bearer $FIDO_API_KEY" \
  -H "X-Tenant-ID: $FIDO_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{"scope":"internal","form":{"id":"string","name":"Intake form","description":"string","isPublished":false,"status":{"id":1,"label":"Example"},"moduleType":{"id":1,"label":"Example"},"submissionStatus":{"id":1,"label":"Example"},"externalVisibility":{"id":"public","label":"string"},"assignTo":{"id":"string","label":"string","isCustom":true},"clientId":[{"id":1,"label":"Example"}],"consumerId":[{"id":1,"label":"Example"}],"serviceProviderId":[{"id":1,"label":"Example"}],"applicableLocationId":[{"id":1,"label":"Example"}],"financeReferenceId":[{"id":1,"label":"Example"}],"multiStep":true,"reviewStep":true,"settings":{"thankYouMessage":"string"},"notifyTo":["string"],"notifyCc":["string"],"notifyBcc":["string"]},"groups":[{"id":0,"name":"Contact details","order":1,"startsStep":true,"stepTitle":"string","fields":[{"id":0,"label":"Preferred contact time","type":"text","isRequired":true,"isVisible":true,"isArchived":true,"order":1,"settings":{}}]}]}'

Try it

Responses

200 Form updated successfully

Form updated successfully

JSON
{
  "success": true,
  "data": {
    "id": 1,
    "version": 2
  }
}
Response fields (4)
FieldTypeDescription
successboolean

Example true.

dataobject
data.idinteger

Example 1.

data.versioninteger

Example 2.

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:edit' 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:edit' 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.