API reference › Clients › Locations in the client portal

Create a new location in client portal

POST /v1/settings/portal/client/locations

Scope
clients:write
Roles
client

Creates a new location in client portal. Rate and billing fields are rejected here (422): adminFee, adminFeeMethod, adminFeeType, enableCustomRates, rates, singleRates, requireVerifiedTimeDocumentation and client are set by the organization, not the portal.

Parameters

None of its own.

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

Request body required

39 top-level fields; 6 hold nested fields, listed below.

FieldTypeDescription
name requiredstring

Example Acme East Coast Office.

descriptionstring or null

Example Primary location for Eastern US operations..

addressLine1string

Example 456 Industrial Rd.

addressLine2string or null

Example Building B.

citystring

Example Philadelphia.

stateobject (2 nested)
postalCodestring

Example 19103.

accessInstructionstring or null

Example Enter through Gate 3. Use intercom for access..

shiftCapacityboolean or null

Example true.

minimumCapacityinteger or null

Example 5.

maximumCapacityinteger or null

Example 20.

timezonestring or null

Example America/Chicago.

statusobject (2 nested)
isPublishedboolean or null

Example true.

reimbursableExpensesarray of object or null (2 nested)
departmentstring

Example Operations.

contactNamestring

Example Jane Doe.

rolestring or null

Example Operations Manager.

contactEmailstring (email)

Example jane.doe@acme.com.

countryCodestring

Contact phone country code

Example +1.

contactPhonestring or null

Contact phone number

Example 9888888888.

contactPhoneTypestring or null

One of: sms_and_voice, voice_only. Example sms_and_voice.

billingAddressDifferentboolean or null

Bill to the address below instead of the main address.

Example false.

billingStreetAddressstring or null

Example 12 Main St.

billingStreetAddressLine2string or null

Example Suite 4.

billingCitystring or null

Example Dover.

billingStateobject (2 nested)
billingPostalCodestring or null

Example 19901.

contactImagestring (binary) or null

Contact person photo. Send an empty value to remove the current one.

contactPhoneExtensionstring or null

Example 204.

customFieldsobject or null

Custom field values keyed by field id.

externalCustomFieldsobject or null

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

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

Example Gate code 1234.

logostring (binary) or null

Image file.

videoPhonestring or null

Example 9888888888.

contactVideoPhonestring or null

Location contact video phone.

priorityobject or null (2 nested)

Default priority for work at this location.

videoPhoneCountryCodestring or null

Example +1.

Nested fields

state 2 fields
FieldTypeDescription
state.idinteger

Example 1.

state.labelstring

Example Albama.

status 2 fields
FieldTypeDescription
status.id requiredinteger

Example 1.

status.label requiredstring

Example Active.

reimbursableExpenses 2 fields
FieldTypeDescription
reimbursableExpenses[].idinteger

Example 6.

reimbursableExpenses[].labelstring

Example example1.

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.

priority 2 fields
FieldTypeDescription
priority.idinteger or string

Example 1.

priority.labelstring or null

Example Example.

Example

JSON
{
  "name": "Acme East Coast Office",
  "description": "Primary location for Eastern US operations.",
  "addressLine1": "456 Industrial Rd",
  "addressLine2": "Building B",
  "city": "Philadelphia",
  "state": {
    "id": 1,
    "label": "Albama"
  },
  "postalCode": "19103",
  "accessInstruction": "Enter through Gate 3. Use intercom for access.",
  "shiftCapacity": true,
  "minimumCapacity": 5,
  "maximumCapacity": 20,
  "timezone": "America/Chicago",
  "status": {
    "id": 1,
    "label": "Active"
  },
  "isPublished": true,
  "reimbursableExpenses": [
    {
      "id": 6,
      "label": "example1"
    }
  ],
  "department": "Operations",
  "contactName": "Jane Doe",
  "role": "Operations Manager",
  "contactEmail": "jane.doe@acme.com",
  "countryCode": "+1",
  "contactPhone": "9888888888",
  "contactPhoneType": "sms_and_voice",
  "billingAddressDifferent": false,
  "billingStreetAddress": "12 Main St",
  "billingStreetAddressLine2": "Suite 4",
  "billingCity": "Dover",
  "billingState": {
    "id": 1,
    "label": "Example"
  },
  "billingPostalCode": "19901",
  "contactImage": "string",
  "contactPhoneExtension": "204",
  "customFields": {},
  "externalCustomFields": {},
  "documents": [
    {
      "id": 12,
      "file": "string",
      "fileName": "intake-form.pdf",
      "categories": [
        {
          "id": 1,
          "label": "Example"
        }
      ],
      "tags": [
        {
          "id": 1,
          "label": "Example"
        }
      ]
    }
  ],
  "internalNotes": "Gate code 1234",
  "logo": "string",
  "videoPhone": "9888888888",
  "contactVideoPhone": "string",
  "priority": {
    "id": 1,
    "label": "Example"
  },
  "videoPhoneCountryCode": "+1"
}

Example request

Shell
curl -X POST "https://api.fetchfido.ai/v1/settings/portal/client/locations" \
  -H "Authorization: Bearer $FIDO_API_KEY" \
  -H "X-Tenant-ID: $FIDO_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme East Coast Office","description":"Primary location for Eastern US operations.","addressLine1":"456 Industrial Rd","addressLine2":"Building B","city":"Philadelphia","state":{"id":1,"label":"Albama"},"postalCode":"19103","accessInstruction":"Enter through Gate 3. Use intercom for access.","shiftCapacity":true,"minimumCapacity":5,"maximumCapacity":20,"timezone":"America/Chicago","status":{"id":1,"label":"Active"},"isPublished":true,"reimbursableExpenses":[{"id":6,"label":"example1"}],"department":"Operations","contactName":"Jane Doe","role":"Operations Manager","contactEmail":"jane.doe@acme.com","countryCode":"+1","contactPhone":"9888888888","contactPhoneType":"sms_and_voice","billingAddressDifferent":false,"billingStreetAddress":"12 Main St","billingStreetAddressLine2":"Suite 4","billingCity":"Dover","billingState":{"id":1,"label":"Example"},"billingPostalCode":"19901","contactImage":"string","contactPhoneExtension":"204","customFields":{},"externalCustomFields":{},"documents":[{"id":12,"file":"string","fileName":"intake-form.pdf","categories":[{"id":1,"label":"Example"}],"tags":[{"id":1,"label":"Example"}]}],"internalNotes":"Gate code 1234","logo":"string","videoPhone":"9888888888","contactVideoPhone":"string","priority":{"id":1,"label":"Example"},"videoPhoneCountryCode":"+1"}'

Try it

Responses

201 Location created successfully

Location created successfully

JSON
{
  "success": true,
  "message": "Location created successfully",
  "data": {
    "id": "LOC-123"
  }
}
Response fields (4)
FieldTypeDescription
successboolean

Example true.

messagestring

Example Location created successfully.

dataobject
data.idstring

Example LOC-123.

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. Includes any org-owned location setting sent by the client, refused when present, even as null or empty: adminFee, adminFeeMethod, adminFeeType, singleRates, rates, client, requireVerifiedTimeDocumentation, enableCustomRates.

JSON
{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "addressLine1": [
      "The addressLine1 field is required."
    ],
    "status": [
      "The status field is required and must include an id."
    ],
    "contactEmail": [
      "The contactEmail must be a valid email address."
    ]
  }
}
Response fields (6)
FieldTypeDescription
successboolean

Example false.

messagestring

Example Validation failed.

errorsobject
errors.addressLine1array of string
errors.statusarray of string
errors.contactEmailarray 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

Server error

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

Example false.

messagestring

Example An unexpected error occurred — please try again..

errorstring

Example Internal server error..