API reference › Clients › Consumers in the client portal

Create a new consumer in client portal

POST /v1/settings/portal/client/consumers

Scope
clients:write
Roles
client

Parameters

None of its own.

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

Request body required

67 top-level fields; 25 hold nested fields, listed below.

FieldTypeDescription
name requiredstring

Example demo consumer 20august-4.

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

descriptionstring or null

Example Test description for demo consumer 20august.

logostring (binary) or null
email requiredstring (email)

Example user@example.com.

countryCodestring or null

Example +1.

videoPhoneCountryCodestring or null

Example +1.

videoPhonestring or null

Example 9888888888.

phonestring or null

Example 9888888888.

phoneTypestring or null

One of: voice_only, sms_and_voice. Example sms_and_voice.

addressLine1string

Example 101 Street.

addressLine2string or null

Example Beagle Run.

citystring

Example Austin.

stateobject (2 nested)
postalCodestring

Example 78759.

portalAccess requiredboolean

Example false.

statusobject (2 nested)
priorityobject or null (2 nested)
hearingStatusobject (2 nested)
communicationModesarray of object (2 nested)
preferredServiceLocationsarray of object (2 nested)
timezonestring or null
defaultTimezonestring

Example America/Juneau.

startOfWeekstring

Example monday.

startOfDaystring

Example 08:00:00.

endOfDaystring

Example 17:00:00.

dateFormatarray of object (2 nested)
timeFormatstring

Example H:i.

defaultLanguagestring or null
isPublishedboolean or null

Example false.

internalNotesstring or null

Example ABCDE.

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.

clientRestrictedarray of object or null (2 nested)

Client users restricted from this consumer.

customizeRequirementPreferencesboolean or null

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

requirementAndPreferencesarray of object (26 nested)
assignmentUpdatesboolean or null

Example false.

serviceRemindersboolean

Example false.

receiveEmailboolean or null

Example false.

receiveSmsboolean or null

Example false.

receiveInAppboolean or null

Example false.

allowServiceRequestsboolean or null

Example false.

allowAssignmentChangesboolean or null

Example false.

allowClientsToBroadcastImmediatelyboolean or null

Notification preference.

allowPortalAccessboolean or null

Lets the consumer use the portal for this client.

assignmentRequestboolean or null

Notification preference: assignment requests.

consumerTypeobject (2 nested)
documentsarray of object or null (9 nested)
genderobject (2 nested)
phoneExtensionstring or null

Max 10.

userPreferredarray of object or null (2 nested)

Users the consumer prefers, by id.

userRestrictedarray of object or null (2 nested)

Users the consumer is restricted from, by id.

isDuplicatedboolean or null

Set when this create duplicates an existing record; records a duplication audit event instead of a plain create

Example false.

duplicateIdstring or null

The record being duplicated. Read only with isDuplicated=true

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

state 2 fields
FieldTypeDescription
state.idinteger

Example 1.

state.labelstring

Example Texas.

status 2 fields
FieldTypeDescription
status.idinteger

Example 1.

status.labelstring

Example InActive.

priority 2 fields
FieldTypeDescription
priority.idinteger

Example 1.

priority.labelstring

Example High.

hearingStatus 2 fields
FieldTypeDescription
hearingStatus.idstring

Example deaf.

hearingStatus.labelstring

Example Deaf.

communicationModes 2 fields
FieldTypeDescription
communicationModes[].idinteger

Example 1.

communicationModes[].labelstring

Example Oral.

preferredServiceLocations 2 fields
FieldTypeDescription
preferredServiceLocations[].idstring

Example on_site_only.

preferredServiceLocations[].labelstring

Example On site only.

dateFormat 2 fields
FieldTypeDescription
dateFormat[].idstring

Example Y/m/d.

dateFormat[].labelstring

Example YYYY/MM/DD.

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.

clientRestricted 2 fields
FieldTypeDescription
clientRestricted[].idinteger or string

Example 1.

clientRestricted[].labelstring or null

Example Example.

requirementAndPreferences 26 fields
FieldTypeDescription
requirementAndPreferences[].serviceTypeobject
requirementAndPreferences[].serviceType.idinteger

Example 1.

requirementAndPreferences[].serviceType.labelstring

Example ASL.

requirementAndPreferences[].serviceProviderTypeobject
requirementAndPreferences[].serviceProviderType.idinteger

Example 1.

requirementAndPreferences[].serviceProviderType.labelstring

Example Deaf.

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

Example 2.

requirementAndPreferences[].certification[].labelstring

Example CDI.

requirementAndPreferences[].certification[].isCustomboolean
requirementAndPreferences[].specializationarray of object
requirementAndPreferences[].specialization[].idinteger

Example 1.

requirementAndPreferences[].specialization[].labelstring

Example Legal.

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

Example 3.

requirementAndPreferences[].clearance[].labelstring

Example FERPA Training.

requirementAndPreferences[].clearance[].isCustomboolean
requirementAndPreferences[].skillobject
requirementAndPreferences[].skill.idinteger

Example 1.

requirementAndPreferences[].skill.labelstring

Example Basic.

requirementAndPreferences[].skill.isCustomboolean

Example false.

requirementAndPreferences[].genderobject
requirementAndPreferences[].gender.idstring

Example male.

requirementAndPreferences[].gender.labelstring

Example Male.

requirementAndPreferences[].gender.isCustomboolean

Example false.

requirementAndPreferences[].isDefaultboolean

Example false.

consumerType 2 fields
FieldTypeDescription
consumerType.idinteger or string

Example 1.

consumerType.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.

gender 2 fields
FieldTypeDescription
gender.idinteger or string

Example 1.

gender.labelstring or null

Example Example.

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.

Example

JSON
{
  "name": "demo consumer 20august-4",
  "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
    }
  ],
  "description": "Test description for demo consumer 20august",
  "logo": null,
  "email": "user@example.com",
  "countryCode": "+1",
  "videoPhoneCountryCode": "+1",
  "videoPhone": "9888888888",
  "phone": "9888888888",
  "phoneType": "sms_and_voice",
  "addressLine1": "101 Street",
  "addressLine2": "Beagle Run",
  "city": "Austin",
  "state": {
    "id": 1,
    "label": "Texas"
  },
  "postalCode": "78759",
  "portalAccess": false,
  "status": {
    "id": 1,
    "label": "InActive"
  },
  "priority": {
    "id": 1,
    "label": "High"
  },
  "hearingStatus": {
    "id": "deaf",
    "label": "Deaf"
  },
  "communicationModes": [
    {
      "id": 1,
      "label": "Oral"
    }
  ],
  "preferredServiceLocations": [
    {
      "id": "on_site_only",
      "label": "On site only"
    }
  ],
  "timezone": null,
  "defaultTimezone": "America/Juneau",
  "startOfWeek": "monday",
  "startOfDay": "08:00:00",
  "endOfDay": "17:00:00",
  "dateFormat": [
    {
      "id": "Y/m/d",
      "label": "YYYY/MM/DD"
    }
  ],
  "timeFormat": "H:i",
  "defaultLanguage": null,
  "isPublished": false,
  "internalNotes": "ABCDE",
  "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"
    }
  ],
  "clientRestricted": [
    {
      "id": 1,
      "label": "Example"
    }
  ],
  "customizeRequirementPreferences": true,
  "requirementAndPreferences": [
    {
      "serviceType": {
        "id": 1,
        "label": "ASL"
      },
      "serviceProviderType": {
        "id": 1,
        "label": "Deaf"
      },
      "certification": [
        {
          "id": 2,
          "label": "CDI",
          "isCustom": null
        }
      ],
      "specialization": [
        {
          "id": 1,
          "label": "Legal"
        }
      ],
      "clearance": [
        {
          "id": 3,
          "label": "FERPA Training",
          "isCustom": null
        }
      ],
      "skill": {
        "id": 1,
        "label": "Basic",
        "isCustom": false
      },
      "gender": {
        "id": "male",
        "label": "Male",
        "isCustom": false
      },
      "isDefault": false
    }
  ],
  "assignmentUpdates": false,
  "serviceReminders": false,
  "receiveEmail": false,
  "receiveSms": false,
  "receiveInApp": false,
  "allowServiceRequests": false,
  "allowAssignmentChanges": false,
  "allowClientsToBroadcastImmediately": true,
  "allowPortalAccess": true,
  "assignmentRequest": true,
  "consumerType": {
    "id": 1,
    "label": "Example"
  },
  "documents": [
    {
      "id": 12,
      "file": "string",
      "fileName": "intake-form.pdf",
      "categories": [
        {
          "id": 1,
          "label": "Example"
        }
      ],
      "tags": [
        {
          "id": 1,
          "label": "Example"
        }
      ]
    }
  ],
  "gender": {
    "id": 1,
    "label": "Example"
  },
  "phoneExtension": "string",
  "userPreferred": [
    {
      "id": 1,
      "label": "Example"
    }
  ],
  "userRestricted": [
    {
      "id": 1,
      "label": "Example"
    }
  ],
  "isDuplicated": false,
  "duplicateId": "string"
}

Example request

Shell
curl -X POST "https://api.fetchfido.ai/v1/settings/portal/client/consumers" \
  -H "Authorization: Bearer $FIDO_API_KEY" \
  -H "X-Tenant-ID: $FIDO_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{"name":"demo consumer 20august-4","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}],"description":"Test description for demo consumer 20august","logo":null,"email":"user@example.com","countryCode":"+1","videoPhoneCountryCode":"+1","videoPhone":"9888888888","phone":"9888888888","phoneType":"sms_and_voice","addressLine1":"101 Street","addressLine2":"Beagle Run","city":"Austin","state":{"id":1,"label":"Texas"},"postalCode":"78759","portalAccess":false,"status":{"id":1,"label":"InActive"},"priority":{"id":1,"label":"High"},"hearingStatus":{"id":"deaf","label":"Deaf"},"communicationModes":[{"id":1,"label":"Oral"}],"preferredServiceLocations":[{"id":"on_site_only","label":"On site only"}],"timezone":null,"defaultTimezone":"America/Juneau","startOfWeek":"monday","startOfDay":"08:00:00","endOfDay":"17:00:00","dateFormat":[{"id":"Y/m/d","label":"YYYY/MM/DD"}],"timeFormat":"H:i","defaultLanguage":null,"isPublished":false,"internalNotes":"ABCDE","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"}],"clientRestricted":[{"id":1,"label":"Example"}],"customizeRequirementPreferences":true,"requirementAndPreferences":[{"serviceType":{"id":1,"label":"ASL"},"serviceProviderType":{"id":1,"label":"Deaf"},"certification":[{"id":2,"label":"CDI","isCustom":null}],"specialization":[{"id":1,"label":"Legal"}],"clearance":[{"id":3,"label":"FERPA Training","isCustom":null}],"skill":{"id":1,"label":"Basic","isCustom":false},"gender":{"id":"male","label":"Male","isCustom":false},"isDefault":false}],"assignmentUpdates":false,"serviceReminders":false,"receiveEmail":false,"receiveSms":false,"receiveInApp":false,"allowServiceRequests":false,"allowAssignmentChanges":false,"allowClientsToBroadcastImmediately":true,"allowPortalAccess":true,"assignmentRequest":true,"consumerType":{"id":1,"label":"Example"},"documents":[{"id":12,"file":"string","fileName":"intake-form.pdf","categories":[{"id":1,"label":"Example"}],"tags":[{"id":1,"label":"Example"}]}],"gender":{"id":1,"label":"Example"},"phoneExtension":"string","userPreferred":[{"id":1,"label":"Example"}],"userRestricted":[{"id":1,"label":"Example"}],"isDuplicated":false,"duplicateId":"string"}'

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 'clients: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 'clients: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].