API reference › Clients › Locations

Create a new client location

POST /v1/clients/{client}/locations

Scope
clients:write
Roles
admin, scheduler

Creates a new client location with address, preferences, rates, reimbursable expenses, contact information, and documents. Rates & Billing fields (rates, single rates, admin fee, billing and cancellation terms) need Finance Write: without it they are left out and the new record takes the organization's.

Parameters

Path parameters

NameTypeDescription
client requiredstring

Unique identifier of the client

Example CLT-VX6R0.

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

Request body required

51 top-level fields; 10 hold nested fields, listed below.

FieldTypeDescription
name requiredstring

max length 255. Example Downtown Office.

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.

statusobject (2 nested)
timezonestring or null

Example America/New_York.

addressLine1string or null

max length 255.

addressLine2string or null

max length 255.

citystring or null

max length 100.

stateobject (2 nested)
postalCodestring or null

12345 or 12345-6789.

Example 19901.

accessInstructionstring or null
preferredServiceLocationsobject (2 nested)

Onsite, remote or both.

shiftCapacityboolean or null
minimumCapacityinteger or null

At most maximumCapacity.

min 0.

maximumCapacityinteger or null

At least minimumCapacity.

min 1.

departmentstring or null

Location contact.

max length 255.

contactNamestring or null

max length 255.

rolestring or null

max length 255.

contactEmailstring (email) or null

max length 255.

contactImagestring (binary) or null

jpg, jpeg, png or gif, max 2 MB. Send an empty value to remove the current one.

countryCodestring or null

Contact phone country code.

Example +1.

contactPhonestring or null
contactPhoneTypestring or null

One of: sms_and_voice, voice_only.

contactPhoneExtensionstring or null
videoPhoneCountryCodestring or null

Example +1.

videoPhonestring or null

max length 20.

contactVideoPhonestring or null

Location contact video phone.

dateOfBirthstring (date) or null
genderobject or null (2 nested)

Required when the location is published.

priorityobject or null (2 nested)

Default priority for work at this location.

billingAddressDifferentboolean or null
billingStreetAddressstring or null
billingStreetAddressLine2string or null
billingCitystring or null
billingStateobject (2 nested)
billingPostalCodestring or null
internalNotesstring or null

min length 2, max length 2000.

enableCustomRatesboolean or null

Use this location's own rates instead of the client's.

ratesarray of object or null (24 nested)
singleRatesarray of object or null (12 nested)
adminFeenumber or null
adminFeeMethodstring or null

Example flat.

adminFeeTypestring or null

One of: assignment, shift, both.

requireVerifiedTimeDocumentationboolean or null
reimbursableExpensesarray of object or null (2 nested)
documentsarray of object or null (9 nested)

pdf, doc, docx, xls, xlsx, csv, png or jpg, max 2 MB each.

customFieldsobject or null

Custom field values keyed by field id.

externalCustomFieldsobject or null

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

isDuplicatedboolean or null

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

Example false.

duplicateIdstring or null

The location being duplicated. Read only with isDuplicated=true.

Nested fields

status 2 fields
FieldTypeDescription
status.idinteger or string

Example 1.

status.labelstring or null

Example Example.

state 2 fields
FieldTypeDescription
state.idinteger or string

Example 1.

state.labelstring or null

Example Example.

preferredServiceLocations 2 fields
FieldTypeDescription
preferredServiceLocations.idinteger or string

Example 1.

preferredServiceLocations.labelstring or null

Example Example.

gender 2 fields
FieldTypeDescription
gender.idinteger or string

Example 1.

gender.labelstring or null

Example Example.

priority 2 fields
FieldTypeDescription
priority.idinteger or string

Example 1.

priority.labelstring or null

Example Example.

billingState 2 fields
FieldTypeDescription
billingState.idinteger or string

Example 1.

billingState.labelstring or null

Example Example.

rates 24 fields
FieldTypeDescription
rates[].idinteger or null

Example 31.

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

Example 1.

rates[].serviceType.labelstring or null

Example Example.

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

Example 1.

rates[].serviceProviderType.labelstring or null

Example Example.

rates[].siteTypeobject
rates[].siteType.idinteger or string

Example 1.

rates[].siteType.labelstring or null

Example Example.

rates[].rateTypeobject
rates[].rateType.idinteger or string

Example 1.

rates[].rateType.labelstring or null

Example Example.

rates[].certificationobject
rates[].certification.idinteger or string

Example 1.

rates[].certification.labelstring or null

Example Example.

rates[].specializationobject
rates[].specialization.idinteger or string

Example 1.

rates[].specialization.labelstring or null

Example Example.

rates[].assignmentboolean

The rate applies to assignments.

Example true.

rates[].shiftboolean

The rate applies to shifts.

Example false.

rates[].ratenumber (float)

Example 45.

rates[].unitstring or null

Example hour.

rates[].minimumDurationnumber or null

Example 2.

singleRates 12 fields
FieldTypeDescription
singleRates[].serviceTypeobject
singleRates[].serviceType.idinteger or string

Example 1.

singleRates[].serviceType.labelstring or null

Example Example.

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

Example 1.

singleRates[].serviceProviderType.labelstring or null

Example Example.

singleRates[].assignmentEnabledboolean

Example true.

singleRates[].assignmentRatenumber (float) or null

Example 50.

singleRates[].assignmentRateUnitstring or null

Example hour.

singleRates[].shiftEnabledboolean

Example false.

singleRates[].shiftRatenumber (float) or null

Example 40.

singleRates[].shiftRateUnitstring or null

Example hour.

reimbursableExpenses 2 fields
FieldTypeDescription
reimbursableExpenses[].idinteger or string

Example 1.

reimbursableExpenses[].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": "Downtown Office",
  "description": "string",
  "logo": "string",
  "isPublished": true,
  "status": {
    "id": 1,
    "label": "Example"
  },
  "timezone": "America/New_York",
  "addressLine1": "string",
  "addressLine2": "string",
  "city": "string",
  "state": {
    "id": 1,
    "label": "Example"
  },
  "postalCode": "19901",
  "accessInstruction": "string",
  "preferredServiceLocations": {
    "id": 1,
    "label": "Example"
  },
  "shiftCapacity": true,
  "minimumCapacity": 0,
  "maximumCapacity": 0,
  "department": "string",
  "contactName": "string",
  "role": "string",
  "contactEmail": "string",
  "contactImage": "string",
  "countryCode": "+1",
  "contactPhone": "string",
  "contactPhoneType": "sms_and_voice",
  "contactPhoneExtension": "string",
  "videoPhoneCountryCode": "+1",
  "videoPhone": "string",
  "contactVideoPhone": "string",
  "dateOfBirth": "string",
  "gender": {
    "id": 1,
    "label": "Example"
  },
  "priority": {
    "id": 1,
    "label": "Example"
  },
  "billingAddressDifferent": true,
  "billingStreetAddress": "string",
  "billingStreetAddressLine2": "string",
  "billingCity": "string",
  "billingState": {
    "id": 1,
    "label": "Example"
  },
  "billingPostalCode": "string",
  "internalNotes": "string",
  "enableCustomRates": true,
  "rates": [
    {
      "id": 31,
      "serviceType": {
        "id": 1,
        "label": "Example"
      },
      "serviceProviderType": {
        "id": 1,
        "label": "Example"
      },
      "siteType": {
        "id": 1,
        "label": "Example"
      },
      "rateType": {
        "id": 1,
        "label": "Example"
      },
      "certification": {
        "id": 1,
        "label": "Example"
      },
      "specialization": {
        "id": 1,
        "label": "Example"
      },
      "assignment": true,
      "shift": false,
      "rate": 45,
      "unit": "hour",
      "minimumDuration": 2
    }
  ],
  "singleRates": [
    {
      "serviceType": {
        "id": 1,
        "label": "Example"
      },
      "serviceProviderType": {
        "id": 1,
        "label": "Example"
      },
      "assignmentEnabled": true,
      "assignmentRate": 50,
      "assignmentRateUnit": "hour",
      "shiftEnabled": false,
      "shiftRate": 40,
      "shiftRateUnit": "hour"
    }
  ],
  "adminFee": 0,
  "adminFeeMethod": "flat",
  "adminFeeType": "assignment",
  "requireVerifiedTimeDocumentation": true,
  "reimbursableExpenses": [
    {
      "id": 1,
      "label": "Example"
    }
  ],
  "documents": [
    {
      "id": 12,
      "file": "string",
      "fileName": "intake-form.pdf",
      "categories": [
        {
          "id": 1,
          "label": "Example"
        }
      ],
      "tags": [
        {
          "id": 1,
          "label": "Example"
        }
      ]
    }
  ],
  "customFields": {},
  "externalCustomFields": {},
  "isDuplicated": false,
  "duplicateId": "string"
}

Example request

Shell
curl -X POST "https://api.fetchfido.ai/v1/clients/{client}/locations" \
  -H "Authorization: Bearer $FIDO_API_KEY" \
  -H "X-Tenant-ID: $FIDO_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{"name":"Downtown Office","description":"string","logo":"string","isPublished":true,"status":{"id":1,"label":"Example"},"timezone":"America/New_York","addressLine1":"string","addressLine2":"string","city":"string","state":{"id":1,"label":"Example"},"postalCode":"19901","accessInstruction":"string","preferredServiceLocations":{"id":1,"label":"Example"},"shiftCapacity":true,"minimumCapacity":0,"maximumCapacity":0,"department":"string","contactName":"string","role":"string","contactEmail":"string","contactImage":"string","countryCode":"+1","contactPhone":"string","contactPhoneType":"sms_and_voice","contactPhoneExtension":"string","videoPhoneCountryCode":"+1","videoPhone":"string","contactVideoPhone":"string","dateOfBirth":"string","gender":{"id":1,"label":"Example"},"priority":{"id":1,"label":"Example"},"billingAddressDifferent":true,"billingStreetAddress":"string","billingStreetAddressLine2":"string","billingCity":"string","billingState":{"id":1,"label":"Example"},"billingPostalCode":"string","internalNotes":"string","enableCustomRates":true,"rates":[{"id":31,"serviceType":{"id":1,"label":"Example"},"serviceProviderType":{"id":1,"label":"Example"},"siteType":{"id":1,"label":"Example"},"rateType":{"id":1,"label":"Example"},"certification":{"id":1,"label":"Example"},"specialization":{"id":1,"label":"Example"},"assignment":true,"shift":false,"rate":45,"unit":"hour","minimumDuration":2}],"singleRates":[{"serviceType":{"id":1,"label":"Example"},"serviceProviderType":{"id":1,"label":"Example"},"assignmentEnabled":true,"assignmentRate":50,"assignmentRateUnit":"hour","shiftEnabled":false,"shiftRate":40,"shiftRateUnit":"hour"}],"adminFee":0,"adminFeeMethod":"flat","adminFeeType":"assignment","requireVerifiedTimeDocumentation":true,"reimbursableExpenses":[{"id":1,"label":"Example"}],"documents":[{"id":12,"file":"string","fileName":"intake-form.pdf","categories":[{"id":1,"label":"Example"}],"tags":[{"id":1,"label":"Example"}]}],"customFields":{},"externalCustomFields":{},"isDuplicated":false,"duplicateId":"string"}'

Try it

Responses

201 Location created successfully

Location created successfully

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

Example true.

messagestring

Example Location created successfully.

dataobject
data.idstring

Example LOC-123.

data.clientIdstring

Example CLT-ABC123.

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": "Validation failed",
  "errors": {
    "addressLine1": [
      "The addressLine1 field is required."
    ],
    "status": [
      "The status field is required and must include an id."
    ],
    "rates.0.serviceId": [
      "The serviceId field is required for each rate."
    ],
    "customRates.1.value": [
      "The value must be a number."
    ],
    "contactEmail": [
      "The contactEmail must be a valid email address."
    ]
  }
}
Response fields (8)
FieldTypeDescription
successboolean

Example false.

messagestring

Example Validation failed.

errorsobject
errors.addressLine1array of string
errors.statusarray of string
errors.rates.0.serviceIdarray of string
errors.customRates.1.valuearray 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..