API reference › Clients › Consumers in the client portal

Update an existing consumer in client portal

POST /v1/settings/portal/client/consumers/{consumer}

Scope
clients:write
Roles
client

Parameters

Path parameters

NameTypeDescription
consumer requiredstring

Consumer ID to update

Example CSM-000123.

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

Request body required

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

FieldTypeDescription
namestring

Example Updated consumer name.

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 Updated description.

logostring (binary) or null
emailstring (email)

Example user@example.com.

countryCodestring or null

Example +1.

videoPhoneCountryCodestring or null

Example +1.

videoPhonestring or null

Example 9777777777.

phonestring or null

Example 9666666666.

phoneTypestring or null

One of: voice_only, sms_and_voice. Example voice_only.

addressLine1string

Example 202 Updated Street.

addressLine2string or null

Example Updated Lane.

citystring

Example Dallas.

stateobject (2 nested)
postalCodestring

Example 75201.

portalAccessboolean

Example true.

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

Example America/New_York.

defaultTimezonestring

Example America/New_York.

startOfWeekstring

Example sunday.

startOfDaystring

Example 09:00:00.

endOfDaystring

Example 18:00:00.

dateFormatarray of object (2 nested)
timeFormatstring

Example h:i A.

defaultLanguagestring or null

Example en.

isPublishedboolean or null

Example true.

internalNotesstring or null

Example Updated internal notes.

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.

customizeRequirementPreferencesboolean or null

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

requirementAndPreferences requiredarray of object (26 nested)
assignmentUpdatesboolean or null

Example true.

serviceRemindersboolean

Example true.

receiveEmailboolean or null

Example true.

receiveSmsboolean or null

Example true.

receiveInAppboolean or null

Example true.

allowServiceRequestsboolean or null

Example true.

allowAssignmentChangesboolean or null

Example true.

allowPortalAccessboolean or null

Lets the consumer use the portal for this client.

clientRestrictedarray of object or null (2 nested)

Clients the consumer is restricted from, by id.

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.

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

state.labelstring

Example Texas.

status 2 fields
FieldTypeDescription
status.idinteger

Example 2.

status.labelstring

Example Active.

priority 2 fields
FieldTypeDescription
priority.idinteger

Example 2.

priority.labelstring

Example Medium.

hearingStatus 2 fields
FieldTypeDescription
hearingStatus.idstring

Example hard_of_hearing.

hearingStatus.labelstring

Example Hard of Hearing.

communicationModes 2 fields
FieldTypeDescription
communicationModes[].idinteger

Example 2.

communicationModes[].labelstring

Example ASL.

preferredServiceLocations 2 fields
FieldTypeDescription
preferredServiceLocations[].idstring

Example remote_only.

preferredServiceLocations[].labelstring

Example Remote only.

dateFormat 2 fields
FieldTypeDescription
dateFormat[].idstring

Example d/m/Y.

dateFormat[].labelstring

Example DD/MM/YYYY.

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 26 fields
FieldTypeDescription
requirementAndPreferences[].serviceTypeobject
requirementAndPreferences[].serviceType.idinteger

Example 2.

requirementAndPreferences[].serviceType.labelstring

Example CART.

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

Example 4.

requirementAndPreferences[].serviceProviderType.labelstring

Example Captioner.

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

Example 4.

requirementAndPreferences[].certification[].labelstring

Example RID.

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

Example 2.

requirementAndPreferences[].specialization[].labelstring

Example Medical.

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

Example 4.

requirementAndPreferences[].clearance[].labelstring

Example HIPAA Training.

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

Example 2.

requirementAndPreferences[].skill.labelstring

Example Intermediate.

requirementAndPreferences[].skill.isCustomboolean

Example false.

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

Example female.

requirementAndPreferences[].gender.labelstring

Example Female.

requirementAndPreferences[].gender.isCustomboolean

Example false.

requirementAndPreferences[].isDefaultboolean

Example true.

clientRestricted 2 fields
FieldTypeDescription
clientRestricted[].idinteger or string

Example 1.

clientRestricted[].labelstring or null

Example Example.

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": "Updated consumer name",
  "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": "Updated description",
  "logo": null,
  "email": "user@example.com",
  "countryCode": "+1",
  "videoPhoneCountryCode": "+1",
  "videoPhone": "9777777777",
  "phone": "9666666666",
  "phoneType": "voice_only",
  "addressLine1": "202 Updated Street",
  "addressLine2": "Updated Lane",
  "city": "Dallas",
  "state": {
    "id": 2,
    "label": "Texas"
  },
  "postalCode": "75201",
  "portalAccess": true,
  "status": {
    "id": 2,
    "label": "Active"
  },
  "priority": {
    "id": 2,
    "label": "Medium"
  },
  "hearingStatus": {
    "id": "hard_of_hearing",
    "label": "Hard of Hearing"
  },
  "communicationModes": [
    {
      "id": 2,
      "label": "ASL"
    }
  ],
  "preferredServiceLocations": [
    {
      "id": "remote_only",
      "label": "Remote only"
    }
  ],
  "timezone": "America/New_York",
  "defaultTimezone": "America/New_York",
  "startOfWeek": "sunday",
  "startOfDay": "09:00:00",
  "endOfDay": "18:00:00",
  "dateFormat": [
    {
      "id": "d/m/Y",
      "label": "DD/MM/YYYY"
    }
  ],
  "timeFormat": "h:i A",
  "defaultLanguage": "en",
  "isPublished": true,
  "internalNotes": "Updated internal notes",
  "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,
  "customizeRequirementPreferences": true,
  "requirementAndPreferences": [
    {
      "serviceType": {
        "id": 2,
        "label": "CART"
      },
      "serviceProviderType": {
        "id": 4,
        "label": "Captioner"
      },
      "certification": [
        {
          "id": 4,
          "label": "RID",
          "isCustom": null
        }
      ],
      "specialization": [
        {
          "id": 2,
          "label": "Medical"
        }
      ],
      "clearance": [
        {
          "id": 4,
          "label": "HIPAA Training",
          "isCustom": null
        }
      ],
      "skill": {
        "id": 2,
        "label": "Intermediate",
        "isCustom": false
      },
      "gender": {
        "id": "female",
        "label": "Female",
        "isCustom": false
      },
      "isDefault": true
    }
  ],
  "assignmentUpdates": true,
  "serviceReminders": true,
  "receiveEmail": true,
  "receiveSms": true,
  "receiveInApp": true,
  "allowServiceRequests": true,
  "allowAssignmentChanges": true,
  "allowPortalAccess": true,
  "clientRestricted": [
    {
      "id": 1,
      "label": "Example"
    }
  ],
  "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"
    }
  ]
}

Example request

Shell
curl -X POST "https://api.fetchfido.ai/v1/settings/portal/client/consumers/{consumer}" \
  -H "Authorization: Bearer $FIDO_API_KEY" \
  -H "X-Tenant-ID: $FIDO_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{"name":"Updated consumer name","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":"Updated description","logo":null,"email":"user@example.com","countryCode":"+1","videoPhoneCountryCode":"+1","videoPhone":"9777777777","phone":"9666666666","phoneType":"voice_only","addressLine1":"202 Updated Street","addressLine2":"Updated Lane","city":"Dallas","state":{"id":2,"label":"Texas"},"postalCode":"75201","portalAccess":true,"status":{"id":2,"label":"Active"},"priority":{"id":2,"label":"Medium"},"hearingStatus":{"id":"hard_of_hearing","label":"Hard of Hearing"},"communicationModes":[{"id":2,"label":"ASL"}],"preferredServiceLocations":[{"id":"remote_only","label":"Remote only"}],"timezone":"America/New_York","defaultTimezone":"America/New_York","startOfWeek":"sunday","startOfDay":"09:00:00","endOfDay":"18:00:00","dateFormat":[{"id":"d/m/Y","label":"DD/MM/YYYY"}],"timeFormat":"h:i A","defaultLanguage":"en","isPublished":true,"internalNotes":"Updated internal notes","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,"customizeRequirementPreferences":true,"requirementAndPreferences":[{"serviceType":{"id":2,"label":"CART"},"serviceProviderType":{"id":4,"label":"Captioner"},"certification":[{"id":4,"label":"RID","isCustom":null}],"specialization":[{"id":2,"label":"Medical"}],"clearance":[{"id":4,"label":"HIPAA Training","isCustom":null}],"skill":{"id":2,"label":"Intermediate","isCustom":false},"gender":{"id":"female","label":"Female","isCustom":false},"isDefault":true}],"assignmentUpdates":true,"serviceReminders":true,"receiveEmail":true,"receiveSms":true,"receiveInApp":true,"allowServiceRequests":true,"allowAssignmentChanges":true,"allowPortalAccess":true,"clientRestricted":[{"id":1,"label":"Example"}],"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"}]}'

Try it

Responses

200 Consumer updated successfully

Consumer updated successfully

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

Example true.

messagestring

Example Consumer updated 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 failed. Includes any org-owned consumer setting sent by the client, refused when present, even as null or empty: allowClientsToBroadcastImmediately, assignmentRequest, isSkillOverridden, isCertificationOverridden, isClearanceOverridden, isGenderOverridden, isServiceOverridden, isServiceProviderTypeOverridden, isCommunicationModeOverridden, consumerInternalNotes.

JSON
{
  "success": false,
  "message": "The given data was invalid.",
  "errors": {
    "email": [
      "The email has already been taken."
    ]
  }
}
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 update 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 update failed: [error details].