API reference › General settings › Requirements and preferences

List the organization's requirements and preferences

GET /v1/settings/list-requirements

Scope
settings_general:read
Roles
admin, scheduler

Returns the organization-level requirement and preference rows — the top tier that client and consumer rows override. See also /v1/requirement-preferences for the flattened lookup lists.

Parameters

Query parameters

NameTypeDescription
populateboolean

When true, every row reports disabledDelete as false — used when seeding a form from these rows rather than editing them in place.

Example false.

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

Example request

Shell
curl "https://api.fetchfido.ai/v1/settings/list-requirements" \
  -H "Authorization: Bearer $FIDO_API_KEY" \
  -H "X-Tenant-ID: $FIDO_TENANT_ID"

Try it

Responses

200 Requirements and preferences retrieved

Requirements and preferences retrieved.

JSON
{
  "success": true,
  "message": "Requirement and Preference Retrieved!",
  "data": {
    "customizeRequirementPreferences": true,
    "requirementAndPreferences": [
      {
        "id": 5,
        "isDefault": false,
        "serviceType": {
          "id": 1,
          "label": "Example"
        },
        "serviceProviderType": {
          "id": 1,
          "label": "Example"
        },
        "skill": {
          "id": 1,
          "label": "Example"
        },
        "gender": {
          "id": "no_preference",
          "value": "no_preference",
          "label": "No Preference"
        },
        "certification": [
          {
            "id": 1,
            "label": "Example"
          }
        ],
        "clearance": [
          {
            "id": 1,
            "label": "Example"
          }
        ],
        "specialization": [
          {
            "id": 1,
            "label": "Example"
          }
        ],
        "disabledDelete": false
      }
    ]
  }
}
Response fields (30)

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

FieldTypeDescription
successboolean

Example true.

messagestring

Example Requirement and Preference Retrieved!.

dataobject (27 nested)

Nested fields

data 27 fields
FieldTypeDescription
data.customizeRequirementPreferencesboolean

Whether the organization keeps per-service-type rows rather than one default row.

Example true.

data.requirementAndPreferencesarray of object
data.requirementAndPreferences[].idinteger

Example 5.

data.requirementAndPreferences[].isDefaultboolean

Example false.

data.requirementAndPreferences[].serviceTypeobject
data.requirementAndPreferences[].serviceType.idinteger or string

Example 1.

data.requirementAndPreferences[].serviceType.labelstring or null

Example Example.

data.requirementAndPreferences[].serviceProviderTypeobject
data.requirementAndPreferences[].serviceProviderType.idinteger or string

Example 1.

data.requirementAndPreferences[].serviceProviderType.labelstring or null

Example Example.

data.requirementAndPreferences[].skillobject or null
data.requirementAndPreferences[].skill.idinteger or string

Example 1.

data.requirementAndPreferences[].skill.labelstring or null

Example Example.

data.requirementAndPreferences[].genderobject or null
data.requirementAndPreferences[].gender.idstring or null

Example no_preference.

data.requirementAndPreferences[].gender.valuestring or null

Example no_preference.

data.requirementAndPreferences[].gender.labelstring or null

Example No Preference.

data.requirementAndPreferences[].certificationarray of object
data.requirementAndPreferences[].certification[].idinteger or string

Example 1.

data.requirementAndPreferences[].certification[].labelstring or null

Example Example.

data.requirementAndPreferences[].clearancearray of object
data.requirementAndPreferences[].clearance[].idinteger or string

Example 1.

data.requirementAndPreferences[].clearance[].labelstring or null

Example Example.

data.requirementAndPreferences[].specializationarray of object
data.requirementAndPreferences[].specialization[].idinteger or string

Example 1.

data.requirementAndPreferences[].specialization[].labelstring or null

Example Example.

data.requirementAndPreferences[].disabledDeleteboolean

True when the row's provider role is still in use and cannot be removed.

Example false.

400 Bad request

Failed to retrieve.

JSON
{
  "success": false,
  "message": "Failed to retrieve."
}
Response fields (2)
FieldTypeDescription
successboolean

Example false.

messagestring

Example Failed to retrieve..

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

500 Server error

Server error.

JSON
{
  "success": false,
  "message": "Something went wrong!"
}
Response fields (2)
FieldTypeDescription
successboolean

Example false.

messagestring

Example Something went wrong!.