API reference › Consumers

Create a new consumer

POST /v1/consumers

Scope
consumers:write
Roles
admin, scheduler

Parameters

None of its own.

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

Request body required

68 top-level fields; 29 hold nested fields, listed below.

FieldTypeDescription
name requiredstring

max length 255. Example Pat Doe.

emailstring (email) or null

Required when portalAccess, networkAccess or receiveEmail is true. Unique among this organization's users, and in the network when networkAccess is true.

max length 255. Example pat@example.test.

descriptionstring or null

min length 5, max length 2000.

logostring (binary) or null

jpg, jpeg or png, max 2 MB.

isPublishedboolean or null

Example true.

dateOfBirthstring (date) or null

Under 18 makes the consumer a minor; a new minor needs a guardian or the independent-minor acknowledgment

Example 2014-05-01.

hasLegalGuardianboolean or null

Guardians act for this consumer whatever their age. Omit to leave as stored

independentMinorAckboolean or null

A minor deliberately with no guardian; needs independentMinorReason

independentMinorReasonstring or null

max length 255.

notifyMinorTooboolean or null

Under guardianship, the consumer also receives their own notifications

guardiansarray of object or null (9 nested)

Replaces the consumer's guardian links when sent (a JSON string on multipart). Omit to leave them as they are

genderobject (2 nested)

Required when published.

countryCodestring or null

max length 5. Example +1.

phonestring or null

Required when receiveSms is true.

max length 20. Example 2025550101.

phoneTypestring or null

One of: sms_and_voice, voice_only. Example sms_and_voice.

phoneExtensionstring or null

max length 10. Example 204.

videoPhoneCountryCodestring or null

max length 5. Example +1.

videoPhonestring or null

max length 20.

addressLine1string or null

max length 255. Example 101 Street.

addressLine2string or null

max length 255.

citystring or null

max length 100. Example Austin.

stateobject (2 nested)
postalCodestring or null

12345 or 12345-6789.

Example 78759.

statusobject (2 nested)

Required when published.

priorityobject (2 nested)
consumerTypeobject (2 nested)
hearingStatusobject (2 nested)

Required when published. id is a hearing-status value such as deaf.

communicationModesarray of object or null (2 nested)

Required when published.

portalAccess requiredboolean

Let the consumer sign in to the consumer portal. Defaults to the organization's auto-populate setting.

Example false.

networkAccessboolean or null

Share the consumer with the Fido network.

Example false.

rolesarray of object or null (3 nested)
enableCalendarIntegrationboolean or null
assignmentUpdatesboolean or null

Notification preference.

serviceRemindersboolean or null

Notification preference.

receiveEmailboolean or null

Notification preference.

receiveSmsboolean or null

Notification preference.

receiveInAppboolean or null

Notification preference.

profileShareWithinOrganizationboolean or null
defaultTimezonestring or null

Localization. Required when published.

Example America/Chicago.

defaultLanguageobject (2 nested)

Localization.

dateFormatobject (2 nested)

Localization. Required when published.

timeFormatstring or null

Localization. Required when published.

startOfWeekobject (2 nested)

Localization. Required when published.

startOfDaystring or null

Localization.

Example 08:00.

endOfDaystring or null

Localization.

Example 18:00.

preferredServiceLocationsobject (2 nested)

Required when published. id is onsite, remote or both.

associatedClientarray of object or null (9 nested)

Clients the consumer is associated with. Required when published. A client left out of an update is detached.

userPreferredarray of object or null (2 nested)

Preferred providers. Must not overlap userRestricted.

userRestrictedarray of object or null (2 nested)

Restricted providers.

clientRestrictedarray of object or null (2 nested)
customizeRequirementPreferencesboolean or null

Per-service-type requirements. true reads requirementAndPreferences; false reads the flat default-tier fields below.

serviceTypesarray of object or null (2 nested)

Default requirement tier. Service types.

serviceProviderTypesarray of object or null (2 nested)

Default requirement tier. Provider roles.

providerTypesarray of object or null (2 nested)

Default requirement tier. Provider types.

skillsobject or null (2 nested)

Default requirement tier. Minimum skill level.

genderPreferencesobject or null (2 nested)

Default requirement tier. Preferred provider gender.

certificationsarray of object or null (4 nested)

Default requirement tier. Required certifications.

clearancesarray of object or null (4 nested)

Default requirement tier. Required clearances.

specializationsarray of object or null (2 nested)

Default requirement tier. Required specializations.

restrictedClientsarray of object or null (2 nested)

Clients the consumer may not be scheduled with.

consumerRestrictedarray of object or null (2 nested)

Consumer users restricted from this consumer.

assignmentRequestboolean or null

Notification preference.

allowClientsToBroadcastImmediatelyboolean or null

The consumer's requests broadcast without scheduler review.

requirementAndPreferencesarray of object or null (23 nested)

Required with customizeRequirementPreferences=true when publishing a consumer that has no service type yet.

internalNotesstring or null

min length 2, max length 2000.

documentsarray of object or null (9 nested)
customFieldsobject or null

Custom field values keyed by field id.

externalCustomFieldsobject or null

Values for the external custom fields, keyed by field id.

Nested fields

guardians 9 fields
FieldTypeDescription
guardians[].idstring or null

Example GRD-ABC123.

guardians[].name requiredstring

max length 255. Example Jane Doe.

guardians[].emailstring (email) or null

Required (422 on guardians.N.email) when this guardian's portal access to the consumer is on, either by hasPortalAccess in this payload or as stored. Sent empty, it clears the stored address (needs a phone); left out, the stored address is kept

Example jane@example.com.

guardians[].countryCodestring or null

Example +1.

guardians[].phonestring or null

Email or phone is required

Example 5551230000.

guardians[].relationshipId requiredinteger

Entry from GET /api/v1/guardian-relationships

Example 1.

guardians[].isPrimaryboolean

Exactly one row is primary

Example true.

guardians[].receivesNotificationsboolean

Example true.

guardians[].hasPortalAccessboolean or null

This guardian's portal access to this consumer; omit to leave it as it is

gender 2 fields
FieldTypeDescription
gender.idinteger or string

Example 1.

gender.labelstring or null

Example Example.

state 2 fields
FieldTypeDescription
state.idinteger or string

Example 1.

state.labelstring or null

Example Example.

status 2 fields
FieldTypeDescription
status.idinteger or string

Example 1.

status.labelstring or null

Example Example.

priority 2 fields
FieldTypeDescription
priority.idinteger or string

Example 1.

priority.labelstring or null

Example Example.

consumerType 2 fields
FieldTypeDescription
consumerType.idinteger or string

Example 1.

consumerType.labelstring or null

Example Example.

hearingStatus 2 fields
FieldTypeDescription
hearingStatus.idinteger or string

Example 1.

hearingStatus.labelstring or null

Example Example.

communicationModes 2 fields
FieldTypeDescription
communicationModes[].idinteger or string

Example 1.

communicationModes[].labelstring or null

Example Example.

roles 3 fields
FieldTypeDescription
roles[].idinteger or null

Role id. Resolved from slug when omitted.

Example 3.

roles[].slugstring

Example consumer.

roles[].enabledboolean

Example true.

defaultLanguage 2 fields
FieldTypeDescription
defaultLanguage.idinteger or string

Example 1.

defaultLanguage.labelstring or null

Example Example.

dateFormat 2 fields
FieldTypeDescription
dateFormat.idinteger or string

Example 1.

dateFormat.labelstring or null

Example Example.

startOfWeek 2 fields
FieldTypeDescription
startOfWeek.idinteger or string

Example 1.

startOfWeek.labelstring or null

Example Example.

preferredServiceLocations 2 fields
FieldTypeDescription
preferredServiceLocations.idinteger or string

Example 1.

preferredServiceLocations.labelstring or null

Example Example.

associatedClient 9 fields
FieldTypeDescription
associatedClient[].clientobject
associatedClient[].client.idinteger or string

Example 1.

associatedClient[].client.labelstring or null

Example Example.

associatedClient[].relationshipobject

Omit to keep the stored relationship; send null to clear it.

associatedClient[].relationship.idinteger or string

Example 1.

associatedClient[].relationship.labelstring or null

Example Example.

associatedClient[].allowPortalAccessboolean or null
associatedClient[].allowServiceRequestsboolean or null
associatedClient[].allowAssignmentChangesboolean or null
userPreferred 2 fields
FieldTypeDescription
userPreferred[].idinteger or string

Example 1.

userPreferred[].labelstring or null

Example Example.

userRestricted 2 fields
FieldTypeDescription
userRestricted[].idinteger or string

Example 1.

userRestricted[].labelstring or null

Example Example.

clientRestricted 2 fields
FieldTypeDescription
clientRestricted[].idinteger or string

Example 1.

clientRestricted[].labelstring or null

Example Example.

serviceTypes 2 fields
FieldTypeDescription
serviceTypes[].idinteger or string

Example 1.

serviceTypes[].labelstring or null

Example Example.

serviceProviderTypes 2 fields
FieldTypeDescription
serviceProviderTypes[].idinteger or string

Example 1.

serviceProviderTypes[].labelstring or null

Example Example.

providerTypes 2 fields
FieldTypeDescription
providerTypes[].idinteger or string

Example 1.

providerTypes[].labelstring or null

Example Example.

skills 2 fields
FieldTypeDescription
skills.idinteger or string

Example 1.

skills.labelstring or null

Example Example.

genderPreferences 2 fields
FieldTypeDescription
genderPreferences.idinteger or string

Example 1.

genderPreferences.labelstring or null

Example Example.

certifications 4 fields
FieldTypeDescription
certifications[].id requiredinteger or string

Example 1.

certifications[].filestring (binary) or null

Supporting document.

certifications[].startDatestring (date) or null
certifications[].endDatestring (date) or null
clearances 4 fields
FieldTypeDescription
clearances[].id requiredinteger or string

Example 1.

clearances[].filestring (binary) or null

Supporting document.

clearances[].startDatestring (date) or null
clearances[].endDatestring (date) or null
specializations 2 fields
FieldTypeDescription
specializations[].idinteger or string

Example 1.

specializations[].labelstring or null

Example Example.

restrictedClients 2 fields
FieldTypeDescription
restrictedClients[].idinteger or string

Example 1.

restrictedClients[].labelstring or null

Example Example.

consumerRestricted 2 fields
FieldTypeDescription
consumerRestricted[].idinteger or string

Example 1.

consumerRestricted[].labelstring or null

Example Example.

requirementAndPreferences 23 fields
FieldTypeDescription
requirementAndPreferences[].idinteger or null

Example 5.

requirementAndPreferences[].isDefaultboolean

Example false.

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

Example 1.

requirementAndPreferences[].serviceType.labelstring or null

Example Example.

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

Example 1.

requirementAndPreferences[].serviceProviderType.labelstring or null

Example Example.

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

Example 1.

requirementAndPreferences[].skill.labelstring or null

Example Example.

requirementAndPreferences[].genderobject
requirementAndPreferences[].gender.idinteger or string

Example 1.

requirementAndPreferences[].gender.labelstring or null

Example Example.

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

Example 1.

requirementAndPreferences[].certification[].labelstring or null

Example Example.

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

Example 1.

requirementAndPreferences[].clearance[].labelstring or null

Example Example.

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

Example 1.

requirementAndPreferences[].specialization[].labelstring or null

Example Example.

documents 9 fields
FieldTypeDescription
documents[].idinteger or null

Example 12.

documents[].filestring (binary) or null

The uploaded file. Omit when only the categories or tags of an existing document change.

documents[].fileNamestring or null

Example intake-form.pdf.

documents[].categoriesarray of object

Existing categories by id, or new ones by label.

documents[].categories[].idinteger or string

Example 1.

documents[].categories[].labelstring or null

Example Example.

documents[].tagsarray of object

Existing tags by id, or new ones by label.

documents[].tags[].idinteger or string

Example 1.

documents[].tags[].labelstring or null

Example Example.

Example

JSON
{
  "name": "Pat Doe",
  "email": "pat@example.test",
  "description": "string",
  "logo": "string",
  "isPublished": true,
  "dateOfBirth": "2014-05-01",
  "hasLegalGuardian": true,
  "independentMinorAck": true,
  "independentMinorReason": "string",
  "notifyMinorToo": true,
  "guardians": [
    {
      "id": "GRD-ABC123",
      "name": "Jane Doe",
      "email": "jane@example.com",
      "countryCode": "+1",
      "phone": "5551230000",
      "relationshipId": 1,
      "isPrimary": true,
      "receivesNotifications": true,
      "hasPortalAccess": true
    }
  ],
  "gender": {
    "id": 1,
    "label": "Example"
  },
  "countryCode": "+1",
  "phone": "2025550101",
  "phoneType": "sms_and_voice",
  "phoneExtension": "204",
  "videoPhoneCountryCode": "+1",
  "videoPhone": "string",
  "addressLine1": "101 Street",
  "addressLine2": "string",
  "city": "Austin",
  "state": {
    "id": 1,
    "label": "Example"
  },
  "postalCode": "78759",
  "status": {
    "id": 1,
    "label": "Example"
  },
  "priority": {
    "id": 1,
    "label": "Example"
  },
  "consumerType": {
    "id": 1,
    "label": "Example"
  },
  "hearingStatus": {
    "id": 1,
    "label": "Example"
  },
  "communicationModes": [
    {
      "id": 1,
      "label": "Example"
    }
  ],
  "portalAccess": false,
  "networkAccess": false,
  "roles": [
    {
      "id": 3,
      "slug": "consumer",
      "enabled": true
    }
  ],
  "enableCalendarIntegration": true,
  "assignmentUpdates": true,
  "serviceReminders": true,
  "receiveEmail": true,
  "receiveSms": true,
  "receiveInApp": true,
  "profileShareWithinOrganization": true,
  "defaultTimezone": "America/Chicago",
  "defaultLanguage": {
    "id": 1,
    "label": "Example"
  },
  "dateFormat": {
    "id": 1,
    "label": "Example"
  },
  "timeFormat": "string",
  "startOfWeek": {
    "id": 1,
    "label": "Example"
  },
  "startOfDay": "08:00",
  "endOfDay": "18:00",
  "preferredServiceLocations": {
    "id": 1,
    "label": "Example"
  },
  "associatedClient": [
    {
      "client": {
        "id": 1,
        "label": "Example"
      },
      "relationship": {
        "id": 1,
        "label": "Example"
      },
      "allowPortalAccess": true,
      "allowServiceRequests": true,
      "allowAssignmentChanges": true
    }
  ],
  "userPreferred": [
    {
      "id": 1,
      "label": "Example"
    }
  ],
  "userRestricted": [
    {
      "id": 1,
      "label": "Example"
    }
  ],
  "clientRestricted": [
    {
      "id": 1,
      "label": "Example"
    }
  ],
  "customizeRequirementPreferences": true,
  "serviceTypes": [
    {
      "id": 1,
      "label": "Example"
    }
  ],
  "serviceProviderTypes": [
    {
      "id": 1,
      "label": "Example"
    }
  ],
  "providerTypes": [
    {
      "id": 1,
      "label": "Example"
    }
  ],
  "skills": {
    "id": 1,
    "label": "Example"
  },
  "genderPreferences": {
    "id": 1,
    "label": "Example"
  },
  "certifications": [
    {
      "id": 1,
      "file": "string",
      "startDate": "string",
      "endDate": "string"
    }
  ],
  "clearances": [
    {
      "id": 1,
      "file": "string",
      "startDate": "string",
      "endDate": "string"
    }
  ],
  "specializations": [
    {
      "id": 1,
      "label": "Example"
    }
  ],
  "restrictedClients": [
    {
      "id": 1,
      "label": "Example"
    }
  ],
  "consumerRestricted": [
    {
      "id": 1,
      "label": "Example"
    }
  ],
  "assignmentRequest": true,
  "allowClientsToBroadcastImmediately": true,
  "requirementAndPreferences": [
    {
      "id": 5,
      "isDefault": false,
      "serviceType": {
        "id": 1,
        "label": "Example"
      },
      "serviceProviderType": {
        "id": 1,
        "label": "Example"
      },
      "skill": {
        "id": 1,
        "label": "Example"
      },
      "gender": {
        "id": 1,
        "label": "Example"
      },
      "certification": [
        {
          "id": 1,
          "label": "Example"
        }
      ],
      "clearance": [
        {
          "id": 1,
          "label": "Example"
        }
      ],
      "specialization": [
        {
          "id": 1,
          "label": "Example"
        }
      ]
    }
  ],
  "internalNotes": "string",
  "documents": [
    {
      "id": 12,
      "file": "string",
      "fileName": "intake-form.pdf",
      "categories": [
        {
          "id": 1,
          "label": "Example"
        }
      ],
      "tags": [
        {
          "id": 1,
          "label": "Example"
        }
      ]
    }
  ],
  "customFields": {},
  "externalCustomFields": {}
}

Example request

Shell
curl -X POST "https://api.fetchfido.ai/v1/consumers" \
  -H "Authorization: Bearer $FIDO_API_KEY" \
  -H "X-Tenant-ID: $FIDO_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{"name":"Pat Doe","email":"pat@example.test","description":"string","logo":"string","isPublished":true,"dateOfBirth":"2014-05-01","hasLegalGuardian":true,"independentMinorAck":true,"independentMinorReason":"string","notifyMinorToo":true,"guardians":[{"id":"GRD-ABC123","name":"Jane Doe","email":"jane@example.com","countryCode":"+1","phone":"5551230000","relationshipId":1,"isPrimary":true,"receivesNotifications":true,"hasPortalAccess":true}],"gender":{"id":1,"label":"Example"},"countryCode":"+1","phone":"2025550101","phoneType":"sms_and_voice","phoneExtension":"204","videoPhoneCountryCode":"+1","videoPhone":"string","addressLine1":"101 Street","addressLine2":"string","city":"Austin","state":{"id":1,"label":"Example"},"postalCode":"78759","status":{"id":1,"label":"Example"},"priority":{"id":1,"label":"Example"},"consumerType":{"id":1,"label":"Example"},"hearingStatus":{"id":1,"label":"Example"},"communicationModes":[{"id":1,"label":"Example"}],"portalAccess":false,"networkAccess":false,"roles":[{"id":3,"slug":"consumer","enabled":true}],"enableCalendarIntegration":true,"assignmentUpdates":true,"serviceReminders":true,"receiveEmail":true,"receiveSms":true,"receiveInApp":true,"profileShareWithinOrganization":true,"defaultTimezone":"America/Chicago","defaultLanguage":{"id":1,"label":"Example"},"dateFormat":{"id":1,"label":"Example"},"timeFormat":"string","startOfWeek":{"id":1,"label":"Example"},"startOfDay":"08:00","endOfDay":"18:00","preferredServiceLocations":{"id":1,"label":"Example"},"associatedClient":[{"client":{"id":1,"label":"Example"},"relationship":{"id":1,"label":"Example"},"allowPortalAccess":true,"allowServiceRequests":true,"allowAssignmentChanges":true}],"userPreferred":[{"id":1,"label":"Example"}],"userRestricted":[{"id":1,"label":"Example"}],"clientRestricted":[{"id":1,"label":"Example"}],"customizeRequirementPreferences":true,"serviceTypes":[{"id":1,"label":"Example"}],"serviceProviderTypes":[{"id":1,"label":"Example"}],"providerTypes":[{"id":1,"label":"Example"}],"skills":{"id":1,"label":"Example"},"genderPreferences":{"id":1,"label":"Example"},"certifications":[{"id":1,"file":"string","startDate":"string","endDate":"string"}],"clearances":[{"id":1,"file":"string","startDate":"string","endDate":"string"}],"specializations":[{"id":1,"label":"Example"}],"restrictedClients":[{"id":1,"label":"Example"}],"consumerRestricted":[{"id":1,"label":"Example"}],"assignmentRequest":true,"allowClientsToBroadcastImmediately":true,"requirementAndPreferences":[{"id":5,"isDefault":false,"serviceType":{"id":1,"label":"Example"},"serviceProviderType":{"id":1,"label":"Example"},"skill":{"id":1,"label":"Example"},"gender":{"id":1,"label":"Example"},"certification":[{"id":1,"label":"Example"}],"clearance":[{"id":1,"label":"Example"}],"specialization":[{"id":1,"label":"Example"}]}],"internalNotes":"string","documents":[{"id":12,"file":"string","fileName":"intake-form.pdf","categories":[{"id":1,"label":"Example"}],"tags":[{"id":1,"label":"Example"}]}],"customFields":{},"externalCustomFields":{}}'

Try it

Responses

201 Consumer created successfully

Consumer created successfully

JSON
{
  "success": true,
  "message": "Consumer created successfully.",
  "data": {
    "id": "CSM-000123"
  }
}
Response fields (4)
FieldTypeDescription
successboolean

Example true.

messagestring

Example Consumer created successfully..

dataobject
data.idstring

Example CSM-000123.

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

errorsany or null

Null on this status.

codestring

Always empty on this status.

Example .

422 Validation failed

Validation Error

JSON
{
  "success": false,
  "message": "The given data was invalid.",
  "errors": {
    "email": [
      "The email field is required."
    ]
  }
}
Response fields (4)
FieldTypeDescription
successboolean

Example false.

messagestring

Example The given data was invalid..

errorsobject
errors.emailarray of string
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

Internal Server Error

JSON
{
  "success": false,
  "message": "Something went wrong!",
  "errors": "Consumer creation failed: [error details]"
}
Response fields (3)
FieldTypeDescription
successboolean

Example false.

messagestring

Example Something went wrong!.

errorsstring or null

Null in production. The exception message only when the application runs with debug on.

Example Consumer creation failed: [error details].