API reference › Forms

Create a new form

POST /v1/forms

Scope
forms:write
Roles
admin, scheduler

Create a new internal or external form with groups and fields. A Contact form (form.moduleType.id contact) must be external, cannot hold file fields, and may carry form.notifyTo, form.notifyCc and form.notifyBcc (lists of ASCII email addresses; at most 50 in all; Bcc is set by the admin role only). Empty To means the org's admins and schedulers.

Parameters

None of its own.

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 POST "https://api.fetchfido.ai/v1/forms" \
  -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

201 Form created successfully

Form created successfully

JSON
{
  "success": true,
  "data": {
    "id": 1,
    "name": "New Form"
  }
}
Response fields (4)
FieldTypeDescription
successboolean

Example true.

dataobject
data.idinteger

Example 1.

data.namestring

Example New Form.

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