API reference › General settings › Organization details

Update a client portal

POST /v1/settings/portal/client-portal/{tab}

Scope
settings_general:write
Roles
client

Updates a client portal by auth user for the given payload.

Parameters

Path parameters

NameTypeDescription
tab requiredstring

The tab to save. rates_billing is read-only in the client portal and is refused with a 403.

One of: details, notification, associated_consumers, requirement_and_preferences, restrictions, rates_billing. Example details.

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

Request body required

Fields for the tab named in the path; each tab writes only its own fields. On details and notification, these org-owned keys are refused with a 422 when present at all: status, priority, clientType, portalAccess, isPublished, shiftCapacity, adminFee, adminFeeMethod, adminFeeType, customizeRateBilling, formId, customizeRequirementPreferences, allowClientsToBroadcastImmediately, assignmentRequest. minimumCapacity and maximumCapacity are dropped silently.

64 top-level fields; 13 hold nested fields, listed below.

FieldTypeDescription
namestring

details tab. Required once the client is published.

Example Demo Client.

descriptionstring or null

details tab.

emailstring (email)

details tab. Must be unique among clients.

Example client@example.com.

logostring (binary) or null

details tab. jpg, jpeg, png or gif, max 2 MB.

industryarray of object or null (2 nested)

details tab. Replaces the client's industries.

countryCodestring or null

details tab.

Example +1.

phonestring or null

details tab.

Example 9876543210.

phoneTypestring or null

details tab.

Example voice_only.

phoneExtensionstring or null

details tab.

Example 204.

videoPhoneCountryCodestring or null

details tab.

Example +1.

videoPhonestring or null

details tab.

genderobject (2 nested)

details tab.

hearingStatusobject (2 nested)

details tab.

dateOfBirthstring (date) or null

details tab.

internalNotesstring or null

details tab.

enableCalendarIntegrationboolean or null

details tab.

locationNamestring or null

details tab. Name of the primary location.

addressLine1string

details tab. Primary location. Required once published.

addressLine2string or null

details tab. Primary location.

citystring

details tab. Primary location. Required once published.

stateobject (2 nested)

details tab. Primary location.

postalCodestring

details tab. Primary location. Required once published.

accessInstructionstring or null

details tab. Primary location.

timezonestring or null

details tab. Primary location.

Example America/New_York.

billingAddressDifferentboolean or null

details tab. When true, the billing street, city, state and postal code are required.

billingStreetAddressstring or null

details tab.

billingStreetAddressLine2string or null

details tab.

billingCitystring or null

details tab.

billingStateobject (2 nested)

details tab.

billingPostalCodestring or null

details tab. 12345 or 12345-6789 when billingAddressDifferent is true.

Example 19901.

contactNamestring or null

details tab. Primary location contact.

contactEmailstring (email) or null

details tab. Primary location contact.

rolestring or null

details tab. Primary location contact's role.

departmentstring or null

details tab. Primary location contact.

contactImagestring (binary) or null

details tab. Primary location contact photo.

contactPhoneCountryCodestring or null

details tab.

Example +1.

contactPhonestring or null

details tab.

contactPhoneTypestring or null

details tab.

Example voice_only.

contactPhoneExtensionstring or null

details tab.

contactVideoPhoneCountryCodestring or null

details tab.

Example +1.

contactVideoPhonestring or null

details tab.

documentsarray of object or null (9 nested)

details tab. Saved against the primary location.

customFieldsobject or null

details tab. Custom field values keyed by field id.

externalCustomFieldsobject or null

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

defaultTimezonestring or null

details tab. Localization.

defaultLanguagestring or null

details tab. Localization.

dateFormatobject (2 nested)

details tab. Localization.

timeFormatstring or null

details tab. Localization.

startOfWeekstring or null

details tab. Localization.

Example monday.

startOfDaystring or null

details tab. Localization.

Example 08:00.

endOfDaystring or null

details tab. Localization.

Example 18:00.

preferredServiceLocationsobject (2 nested)

details tab. Localization.

assignmentUpdatesboolean or null

notification tab.

serviceRemindersboolean or null

notification tab.

receiveEmailboolean or null

notification tab.

receiveSmsboolean or null

notification tab.

receiveInAppboolean or null

notification tab.

profileShareWithinOrganizationboolean or null

notification tab.

associatedConsumerarray of object or null (9 nested)

associated_consumers tab. Replaces the client's consumer associations.

requirementAndPreferencesarray of object or null (23 nested)

requirement_and_preferences tab.

customizeRequirementPreferencesboolean or null

requirement_and_preferences tab only; refused on details and notification.

userRestrictedarray of object or null (2 nested)

restrictions tab.

userPreferredarray of object or null (2 nested)

restrictions tab.

consumerRestrictedarray of object or null (2 nested)

restrictions tab.

Nested fields

industry 2 fields
FieldTypeDescription
industry[].idinteger or string

Example 1.

industry[].labelstring or null

Example Example.

gender 2 fields
FieldTypeDescription
gender.idinteger or string

Example 1.

gender.labelstring or null

Example Example.

hearingStatus 2 fields
FieldTypeDescription
hearingStatus.idinteger or string

Example 1.

hearingStatus.labelstring or null

Example Example.

state 2 fields
FieldTypeDescription
state.idinteger or string

Example 1.

state.labelstring or null

Example Example.

billingState 2 fields
FieldTypeDescription
billingState.idinteger or string

Example 1.

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

dateFormat 2 fields
FieldTypeDescription
dateFormat.idinteger or string

Example 1.

dateFormat.labelstring or null

Example Example.

preferredServiceLocations 2 fields
FieldTypeDescription
preferredServiceLocations.idinteger or string

Example 1.

preferredServiceLocations.labelstring or null

Example Example.

associatedConsumer 9 fields
FieldTypeDescription
associatedConsumer[].consumerobject
associatedConsumer[].consumer.idinteger or string

Example 1.

associatedConsumer[].consumer.labelstring or null

Example Example.

associatedConsumer[].relationshipobject
associatedConsumer[].relationship.idinteger or string

Example 1.

associatedConsumer[].relationship.labelstring or null

Example Example.

associatedConsumer[].allowPortalAccessboolean or null
associatedConsumer[].allowServiceRequestsboolean or null
associatedConsumer[].allowAssignmentChangesboolean or null
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.

userRestricted 2 fields
FieldTypeDescription
userRestricted[].idinteger or string

Example 1.

userRestricted[].labelstring or null

Example Example.

userPreferred 2 fields
FieldTypeDescription
userPreferred[].idinteger or string

Example 1.

userPreferred[].labelstring or null

Example Example.

consumerRestricted 2 fields
FieldTypeDescription
consumerRestricted[].idinteger or string

Example 1.

consumerRestricted[].labelstring or null

Example Example.

Example

JSON
{
  "name": "Demo Client",
  "description": "string",
  "email": "client@example.com",
  "logo": "string",
  "industry": [
    {
      "id": 1,
      "label": "Example"
    }
  ],
  "countryCode": "+1",
  "phone": "9876543210",
  "phoneType": "voice_only",
  "phoneExtension": "204",
  "videoPhoneCountryCode": "+1",
  "videoPhone": "string",
  "gender": {
    "id": 1,
    "label": "Example"
  },
  "hearingStatus": {
    "id": 1,
    "label": "Example"
  },
  "dateOfBirth": "string",
  "internalNotes": "string",
  "enableCalendarIntegration": true,
  "locationName": "string",
  "addressLine1": "string",
  "addressLine2": "string",
  "city": "string",
  "state": {
    "id": 1,
    "label": "Example"
  },
  "postalCode": "string",
  "accessInstruction": "string",
  "timezone": "America/New_York",
  "billingAddressDifferent": true,
  "billingStreetAddress": "string",
  "billingStreetAddressLine2": "string",
  "billingCity": "string",
  "billingState": {
    "id": 1,
    "label": "Example"
  },
  "billingPostalCode": "19901",
  "contactName": "string",
  "contactEmail": "string",
  "role": "string",
  "department": "string",
  "contactImage": "string",
  "contactPhoneCountryCode": "+1",
  "contactPhone": "string",
  "contactPhoneType": "voice_only",
  "contactPhoneExtension": "string",
  "contactVideoPhoneCountryCode": "+1",
  "contactVideoPhone": "string",
  "documents": [
    {
      "id": 12,
      "file": "string",
      "fileName": "intake-form.pdf",
      "categories": [
        {
          "id": 1,
          "label": "Example"
        }
      ],
      "tags": [
        {
          "id": 1,
          "label": "Example"
        }
      ]
    }
  ],
  "customFields": {},
  "externalCustomFields": {},
  "defaultTimezone": "string",
  "defaultLanguage": "string",
  "dateFormat": {
    "id": 1,
    "label": "Example"
  },
  "timeFormat": "string",
  "startOfWeek": "monday",
  "startOfDay": "08:00",
  "endOfDay": "18:00",
  "preferredServiceLocations": {
    "id": 1,
    "label": "Example"
  },
  "assignmentUpdates": true,
  "serviceReminders": true,
  "receiveEmail": true,
  "receiveSms": true,
  "receiveInApp": true,
  "profileShareWithinOrganization": true,
  "associatedConsumer": [
    {
      "consumer": {
        "id": 1,
        "label": "Example"
      },
      "relationship": {
        "id": 1,
        "label": "Example"
      },
      "allowPortalAccess": true,
      "allowServiceRequests": true,
      "allowAssignmentChanges": 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"
        }
      ]
    }
  ],
  "customizeRequirementPreferences": true,
  "userRestricted": [
    {
      "id": 1,
      "label": "Example"
    }
  ],
  "userPreferred": [
    {
      "id": 1,
      "label": "Example"
    }
  ],
  "consumerRestricted": [
    {
      "id": 1,
      "label": "Example"
    }
  ]
}

Example request

Shell
curl -X POST "https://api.fetchfido.ai/v1/settings/portal/client-portal/{tab}" \
  -H "Authorization: Bearer $FIDO_API_KEY" \
  -H "X-Tenant-ID: $FIDO_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{"name":"Demo Client","description":"string","email":"client@example.com","logo":"string","industry":[{"id":1,"label":"Example"}],"countryCode":"+1","phone":"9876543210","phoneType":"voice_only","phoneExtension":"204","videoPhoneCountryCode":"+1","videoPhone":"string","gender":{"id":1,"label":"Example"},"hearingStatus":{"id":1,"label":"Example"},"dateOfBirth":"string","internalNotes":"string","enableCalendarIntegration":true,"locationName":"string","addressLine1":"string","addressLine2":"string","city":"string","state":{"id":1,"label":"Example"},"postalCode":"string","accessInstruction":"string","timezone":"America/New_York","billingAddressDifferent":true,"billingStreetAddress":"string","billingStreetAddressLine2":"string","billingCity":"string","billingState":{"id":1,"label":"Example"},"billingPostalCode":"19901","contactName":"string","contactEmail":"string","role":"string","department":"string","contactImage":"string","contactPhoneCountryCode":"+1","contactPhone":"string","contactPhoneType":"voice_only","contactPhoneExtension":"string","contactVideoPhoneCountryCode":"+1","contactVideoPhone":"string","documents":[{"id":12,"file":"string","fileName":"intake-form.pdf","categories":[{"id":1,"label":"Example"}],"tags":[{"id":1,"label":"Example"}]}],"customFields":{},"externalCustomFields":{},"defaultTimezone":"string","defaultLanguage":"string","dateFormat":{"id":1,"label":"Example"},"timeFormat":"string","startOfWeek":"monday","startOfDay":"08:00","endOfDay":"18:00","preferredServiceLocations":{"id":1,"label":"Example"},"assignmentUpdates":true,"serviceReminders":true,"receiveEmail":true,"receiveSms":true,"receiveInApp":true,"profileShareWithinOrganization":true,"associatedConsumer":[{"consumer":{"id":1,"label":"Example"},"relationship":{"id":1,"label":"Example"},"allowPortalAccess":true,"allowServiceRequests":true,"allowAssignmentChanges":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"}]}],"customizeRequirementPreferences":true,"userRestricted":[{"id":1,"label":"Example"}],"userPreferred":[{"id":1,"label":"Example"}],"consumerRestricted":[{"id":1,"label":"Example"}]}'

Try it

Responses

200 Client portal updated successfully

Client portal updated successfully

JSON
{
  "success": true,
  "message": "Changes to 'Demo Client' were saved.",
  "data": {
    "id": "CLT-WJT26R"
  }
}
Response fields (4)
FieldTypeDescription
successboolean

Example true.

messagestring

Example Changes to 'Demo Client' were saved..

dataobject
data.idstring

Example CLT-WJT26R.

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

The rates_billing tab is read-only in the client portal and managed by the service organization.

JSON
{
  "success": false,
  "message": "You don't have permission to access this endpoint. This API key is missing the 'settings_general: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 'settings_general: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 setting sent by the client (refused when present, even as null or empty). Details tab: status, priority, clientType, portalAccess, isPublished, shiftCapacity, adminFee, adminFeeMethod, adminFeeType, customizeRateBilling, formId, customizeRequirementPreferences. Notifications tab: allowClientsToBroadcastImmediately, assignmentRequest, customizeRequirementPreferences. minimumCapacity and maximumCapacity are ignored rather than refused; the stored values are kept.

JSON
{
  "status": "error",
  "message": "Unable to save. Please check the highlighted fields.",
  "errors": {
    "adminFee": [
      "The admin fee is managed by your organization."
    ]
  }
}
Response fields (3)
FieldTypeDescription
statusstring

Example error.

messagestring

Example Unable to save. Please check the highlighted fields..

errorsobject
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

Unexpected error occurred

JSON
{
  "success": false,
  "errors": "Detailed error message",
  "message": "An unexpected error occurred — please try again."
}
Response fields (3)
FieldTypeDescription
successboolean

Example false.

errorsstring or null

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

Example Detailed error message.

messagestring

Example An unexpected error occurred — please try again..