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
| Name | Type | Description |
|---|---|---|
client required | string | Unique identifier of the client Example |
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.
| Field | Type | Description |
|---|---|---|
name required | string | max length 255. Example |
description | string or null | min length 5, max length 2000. |
logo | string (binary) or null | jpg, jpeg or png, max 2 MB. |
isPublished | boolean or null | Example |
status | object (2 nested) | |
timezone | string or null | Example |
addressLine1 | string or null | max length 255. |
addressLine2 | string or null | max length 255. |
city | string or null | max length 100. |
state | object (2 nested) | |
postalCode | string or null | 12345 or 12345-6789. Example |
accessInstruction | string or null | |
preferredServiceLocations | object (2 nested) | Onsite, remote or both. |
shiftCapacity | boolean or null | |
minimumCapacity | integer or null | At most maximumCapacity. min 0. |
maximumCapacity | integer or null | At least minimumCapacity. min 1. |
department | string or null | Location contact. max length 255. |
contactName | string or null | max length 255. |
role | string or null | max length 255. |
contactEmail | string (email) or null | max length 255. |
contactImage | string (binary) or null | jpg, jpeg, png or gif, max 2 MB. Send an empty value to remove the current one. |
countryCode | string or null | Contact phone country code. Example |
contactPhone | string or null | |
contactPhoneType | string or null | One of: |
contactPhoneExtension | string or null | |
videoPhoneCountryCode | string or null | Example |
videoPhone | string or null | max length 20. |
contactVideoPhone | string or null | Location contact video phone. |
dateOfBirth | string (date) or null | |
gender | object or null (2 nested) | Required when the location is published. |
priority | object or null (2 nested) | Default priority for work at this location. |
billingAddressDifferent | boolean or null | |
billingStreetAddress | string or null | |
billingStreetAddressLine2 | string or null | |
billingCity | string or null | |
billingState | object (2 nested) | |
billingPostalCode | string or null | |
internalNotes | string or null | min length 2, max length 2000. |
enableCustomRates | boolean or null | Use this location's own rates instead of the client's. |
rates | array of object or null (24 nested) | |
singleRates | array of object or null (12 nested) | |
adminFee | number or null | |
adminFeeMethod | string or null | Example |
adminFeeType | string or null | One of: |
requireVerifiedTimeDocumentation | boolean or null | |
reimbursableExpenses | array of object or null (2 nested) | |
documents | array of object or null (9 nested) | pdf, doc, docx, xls, xlsx, csv, png or jpg, max 2 MB each. |
customFields | object or null | Custom field values keyed by field id. |
externalCustomFields | object or null | Values for the external custom fields, keyed by field id. |
isDuplicated | boolean or null | Set when this create duplicates an existing location; records a duplication audit event instead of a plain create. Example |
duplicateId | string or null | The location being duplicated. Read only with isDuplicated=true. |
Nested fields
status 2 fields
| Field | Type | Description |
|---|---|---|
status.id | integer or string | Example |
status.label | string or null | Example |
state 2 fields
| Field | Type | Description |
|---|---|---|
state.id | integer or string | Example |
state.label | string or null | Example |
preferredServiceLocations 2 fields
| Field | Type | Description |
|---|---|---|
preferredServiceLocations.id | integer or string | Example |
preferredServiceLocations.label | string or null | Example |
gender 2 fields
| Field | Type | Description |
|---|---|---|
gender.id | integer or string | Example |
gender.label | string or null | Example |
priority 2 fields
| Field | Type | Description |
|---|---|---|
priority.id | integer or string | Example |
priority.label | string or null | Example |
billingState 2 fields
| Field | Type | Description |
|---|---|---|
billingState.id | integer or string | Example |
billingState.label | string or null | Example |
rates 24 fields
| Field | Type | Description |
|---|---|---|
rates[].id | integer or null | Example |
rates[].serviceType | object | |
rates[].serviceType.id | integer or string | Example |
rates[].serviceType.label | string or null | Example |
rates[].serviceProviderType | object | |
rates[].serviceProviderType.id | integer or string | Example |
rates[].serviceProviderType.label | string or null | Example |
rates[].siteType | object | |
rates[].siteType.id | integer or string | Example |
rates[].siteType.label | string or null | Example |
rates[].rateType | object | |
rates[].rateType.id | integer or string | Example |
rates[].rateType.label | string or null | Example |
rates[].certification | object | |
rates[].certification.id | integer or string | Example |
rates[].certification.label | string or null | Example |
rates[].specialization | object | |
rates[].specialization.id | integer or string | Example |
rates[].specialization.label | string or null | Example |
rates[].assignment | boolean | The rate applies to assignments. Example |
rates[].shift | boolean | The rate applies to shifts. Example |
rates[].rate | number (float) | Example |
rates[].unit | string or null | Example |
rates[].minimumDuration | number or null | Example |
singleRates 12 fields
| Field | Type | Description |
|---|---|---|
singleRates[].serviceType | object | |
singleRates[].serviceType.id | integer or string | Example |
singleRates[].serviceType.label | string or null | Example |
singleRates[].serviceProviderType | object | |
singleRates[].serviceProviderType.id | integer or string | Example |
singleRates[].serviceProviderType.label | string or null | Example |
singleRates[].assignmentEnabled | boolean | Example |
singleRates[].assignmentRate | number (float) or null | Example |
singleRates[].assignmentRateUnit | string or null | Example |
singleRates[].shiftEnabled | boolean | Example |
singleRates[].shiftRate | number (float) or null | Example |
singleRates[].shiftRateUnit | string or null | Example |
reimbursableExpenses 2 fields
| Field | Type | Description |
|---|---|---|
reimbursableExpenses[].id | integer or string | Example |
reimbursableExpenses[].label | string or null | Example |
documents 9 fields
| Field | Type | Description |
|---|---|---|
documents[].id | integer or null | Example |
documents[].file | string (binary) or null | The uploaded file. Omit when only the categories or tags of an existing document change. |
documents[].fileName | string or null | Example |
documents[].categories | array of object | Existing categories by |
documents[].categories[].id | integer or string | Example |
documents[].categories[].label | string or null | Example |
documents[].tags | array of object | Existing tags by |
documents[].tags[].id | integer or string | Example |
documents[].tags[].label | string or null | Example |
Example
{
"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
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
{
"success": true,
"message": "Location created successfully",
"data": {
"id": "LOC-123",
"clientId": "CLT-ABC123"
}
}Response fields (5)
| Field | Type | Description |
|---|---|---|
success | boolean | Example |
message | string | Example |
data | object | |
data.id | string | Example |
data.clientId | string | Example |
401 Not signed in
Missing, invalid or expired API key.
{
"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)
| Field | Type | Description |
|---|---|---|
success | boolean | Example |
message | string | Example |
errors | any or null | Null on this status. |
code | string | Machine-readable reason, for branching on in client code. One of: |
403 Not allowed
Scope, tenant, IP allow-list or RBAC check failed.
{
"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)
| Field | Type | Description |
|---|---|---|
success | boolean | Example |
message | string | Example |
errors | any or null | Null on this status. |
code | string | Always empty on this status. Example |
422 Validation failed
Validation error
{
"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)
| Field | Type | Description |
|---|---|---|
success | boolean | Example |
message | string | Example |
errors | object | |
errors.addressLine1 | array of string | |
errors.status | array of string | |
errors.rates.0.serviceId | array of string | |
errors.customRates.1.value | array of string | |
errors.contactEmail | array of string |
429 Too many requests
Rate limit exceeded. See Retry-After.
{
"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)
| Field | Type | Description |
|---|---|---|
success | boolean | Example |
message | string | Example |
errors | any or null | Null on this status. |
code | string | Machine-readable reason, for branching on in client code. One of: |
500 Server error
Server error
{
"success": false,
"message": "An unexpected error occurred — please try again.",
"error": "Internal server error."
}Response fields (3)
| Field | Type | Description |
|---|---|---|
success | boolean | Example |
message | string | Example |
error | string | Example |