API reference › Organization locations
Create a new organization location
POST /v1/organization-location
- Scope
settings_locations:write- Roles
- admin, scheduler
Creates a new organization location with the provided details, including skills, certifications, and specializations. 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
None of its own.
Every call also sends Authorization and X-Tenant-ID; see Getting started.
Request body required
47 top-level fields; 13 hold nested fields, listed below.
| Field | Type | Description |
|---|---|---|
name required | string | Name of the organization Location Example |
description | string or null | Brief description of the organization location Example |
logo | string or null | Organization Location Logo |
department | string | Enter organization departments OR units Example |
contactImage | string or null | Organization's contact person image |
contactName | string (string) | Organization's contact name Example |
contactEmail | string (email) | Organization's contact email Example |
role | string or null | contact person role Example |
countryCode | string or null | Organization's contact phone country code Example |
phone | string or null | Organization's contact phone number Example |
videoPhoneCountryCode | string or null | Video phone country code Example |
videoPhone | string or null | Video phone number Example |
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. |
phoneType | string or null | Organization's contact phone type Example |
addressLine1 | string | Enter street address line1. Example |
addressLine2 | string or null | Enter street address line2. Example |
city | string | Enter organization location city Example |
state | object (2 nested) | Organization location state |
postalCode | string | Enter organization location postal code Example |
accessInstruction | string | Enter organization location access instructions Example |
skills | array of object (2 nested) | Skills associated with the organization location, including predefined and custom skills |
certifications | array of object (2 nested) | Certifications associated with the organization location |
clearances | array of object (2 nested) | Security clearances assigned to the organization location |
specializations | array of object (2 nested) | Specializations assigned to the organization location |
internalNotes | string or null | Internal notes for administrators Example |
status | object (2 nested) | Status of the location. Required when publishing. |
phoneExtension | string or null | Example |
timezone | string or null | IANA timezone of the location Example |
shiftCapacity | boolean or null | The location tracks shift capacity Example |
minimumCapacity | integer or null | Must not exceed maximumCapacity min 0. Example |
maximumCapacity | integer or null | Must be at least minimumCapacity min 1. Example |
isPublished | boolean | Publishing makes the address, contact and status fields required Example |
enableCustomRates | boolean or null | Example |
requireVerifiedTimeDocumentation | boolean or null | Example |
customizeRequirementPreferences | boolean or null | Example |
adminFee | number (float) or null | Example |
adminFeeMethod | string or null | Defaults to flat Example |
adminFeeType | string or null | What the admin fee applies to One of: |
documents | array of object (9 nested) | |
rates | array of object (24 nested) | |
singleRates | array of object (12 nested) | |
reimbursableExpenses | array of object (2 nested) | Reimbursable expenses offered at this location, by id. Ones not sent are removed. |
requirementAndPreferences | array of object (23 nested) | |
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 Example |
Nested fields
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 |
state 2 fields
| Field | Type | Description |
|---|---|---|
state.id | integer | Example |
state.label | string | Example |
skills 2 fields
| Field | Type | Description |
|---|---|---|
skills[].id | integer or null | |
skills[].label | string | Example |
certifications 2 fields
| Field | Type | Description |
|---|---|---|
certifications[].id | integer or null | |
certifications[].label | string | Example |
clearances 2 fields
| Field | Type | Description |
|---|---|---|
clearances[].id | integer or null | |
clearances[].label | string | Example |
specializations 2 fields
| Field | Type | Description |
|---|---|---|
specializations[].id | integer or null | |
specializations[].label | string | Example |
status 2 fields
| Field | Type | Description |
|---|---|---|
status.id | integer | Example |
status.label | string | 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 |
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 |
requirementAndPreferences 23 fields
| Field | Type | Description |
|---|---|---|
requirementAndPreferences[].id | integer or null | Example |
requirementAndPreferences[].isDefault | boolean | Example |
requirementAndPreferences[].serviceType | object | |
requirementAndPreferences[].serviceType.id | integer or string | Example |
requirementAndPreferences[].serviceType.label | string or null | Example |
requirementAndPreferences[].serviceProviderType | object | |
requirementAndPreferences[].serviceProviderType.id | integer or string | Example |
requirementAndPreferences[].serviceProviderType.label | string or null | Example |
requirementAndPreferences[].skill | object | |
requirementAndPreferences[].skill.id | integer or string | Example |
requirementAndPreferences[].skill.label | string or null | Example |
requirementAndPreferences[].gender | object | |
requirementAndPreferences[].gender.id | integer or string | Example |
requirementAndPreferences[].gender.label | string or null | Example |
requirementAndPreferences[].certification | array of object | |
requirementAndPreferences[].certification[].id | integer or string | Example |
requirementAndPreferences[].certification[].label | string or null | Example |
requirementAndPreferences[].clearance | array of object | |
requirementAndPreferences[].clearance[].id | integer or string | Example |
requirementAndPreferences[].clearance[].label | string or null | Example |
requirementAndPreferences[].specialization | array of object | |
requirementAndPreferences[].specialization[].id | integer or string | Example |
requirementAndPreferences[].specialization[].label | string or null | Example |
Example
{
"name": "Location 1",
"description": "This is a demo tenant for showcasing purposes.",
"logo": null,
"department": "Test",
"contactImage": null,
"contactName": "Contact Name",
"contactEmail": "contact@demotenant.com",
"role": "Role",
"countryCode": "+1",
"phone": "9888888888",
"videoPhoneCountryCode": "+1",
"videoPhone": "9888888888",
"dateOfBirth": "string",
"gender": {
"id": 1,
"label": "Example"
},
"priority": {
"id": 1,
"label": "Example"
},
"phoneType": "voice_only",
"addressLine1": "addressLine1",
"addressLine2": "addressLine2",
"city": "City",
"state": {
"id": 8,
"label": "Delaware"
},
"postalCode": "12345",
"accessInstruction": "Access instructions text",
"skills": [
{
"id": 1,
"label": "Skill1"
},
{
"id": 2,
"label": "Skill2"
},
{
"id": null,
"label": "Custom1"
},
{
"id": null,
"label": "Custom2"
}
],
"certifications": [
{
"id": 1,
"label": "Certifications1"
},
{
"id": 2,
"label": "Certifications2"
},
{
"id": null,
"label": "Custom1"
},
{
"id": null,
"label": "Custom2"
}
],
"clearances": [
{
"id": 1,
"label": "Clearances1"
},
{
"id": 2,
"label": "Clearances2"
},
{
"id": null,
"label": "Custom1"
},
{
"id": null,
"label": "Custom2"
}
],
"specializations": [
{
"id": 1,
"label": "Specializations1"
},
{
"id": 2,
"label": "Specializations2"
},
{
"id": null,
"label": "Custom1"
},
{
"id": null,
"label": "Custom2"
}
],
"internalNotes": "Confidential information regarding tenant.",
"status": {
"id": 1,
"label": "Active"
},
"phoneExtension": "204",
"timezone": "America/New_York",
"shiftCapacity": false,
"minimumCapacity": 1,
"maximumCapacity": 10,
"isPublished": true,
"enableCustomRates": false,
"requireVerifiedTimeDocumentation": false,
"customizeRequirementPreferences": false,
"adminFee": 5,
"adminFeeMethod": "flat",
"adminFeeType": "assignment",
"documents": [
{
"id": 12,
"file": "string",
"fileName": "intake-form.pdf",
"categories": [
{
"id": 1,
"label": "Example"
}
],
"tags": [
{
"id": 1,
"label": "Example"
}
]
}
],
"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"
}
],
"reimbursableExpenses": [
{
"id": 1,
"label": "Example"
}
],
"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"
}
]
}
],
"isDuplicated": false,
"duplicateId": "ORGLOC-123ET"
}Example request
curl -X POST "https://api.fetchfido.ai/v1/organization-location" \
-H "Authorization: Bearer $FIDO_API_KEY" \
-H "X-Tenant-ID: $FIDO_TENANT_ID" \
-H "Content-Type: application/json" \
-d '{"name":"Location 1","description":"This is a demo tenant for showcasing purposes.","logo":null,"department":"Test","contactImage":null,"contactName":"Contact Name","contactEmail":"contact@demotenant.com","role":"Role","countryCode":"+1","phone":"9888888888","videoPhoneCountryCode":"+1","videoPhone":"9888888888","dateOfBirth":"string","gender":{"id":1,"label":"Example"},"priority":{"id":1,"label":"Example"},"phoneType":"voice_only","addressLine1":"addressLine1","addressLine2":"addressLine2","city":"City","state":{"id":8,"label":"Delaware"},"postalCode":"12345","accessInstruction":"Access instructions text","skills":[{"id":1,"label":"Skill1"},{"id":2,"label":"Skill2"},{"id":null,"label":"Custom1"},{"id":null,"label":"Custom2"}],"certifications":[{"id":1,"label":"Certifications1"},{"id":2,"label":"Certifications2"},{"id":null,"label":"Custom1"},{"id":null,"label":"Custom2"}],"clearances":[{"id":1,"label":"Clearances1"},{"id":2,"label":"Clearances2"},{"id":null,"label":"Custom1"},{"id":null,"label":"Custom2"}],"specializations":[{"id":1,"label":"Specializations1"},{"id":2,"label":"Specializations2"},{"id":null,"label":"Custom1"},{"id":null,"label":"Custom2"}],"internalNotes":"Confidential information regarding tenant.","status":{"id":1,"label":"Active"},"phoneExtension":"204","timezone":"America/New_York","shiftCapacity":false,"minimumCapacity":1,"maximumCapacity":10,"isPublished":true,"enableCustomRates":false,"requireVerifiedTimeDocumentation":false,"customizeRequirementPreferences":false,"adminFee":5,"adminFeeMethod":"flat","adminFeeType":"assignment","documents":[{"id":12,"file":"string","fileName":"intake-form.pdf","categories":[{"id":1,"label":"Example"}],"tags":[{"id":1,"label":"Example"}]}],"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"}],"reimbursableExpenses":[{"id":1,"label":"Example"}],"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"}]}],"isDuplicated":false,"duplicateId":"ORGLOC-123ET"}'Try it
Responses
201 Organization location created successfully
Organization location created successfully
{
"success": true,
"message": "Organization location created successfully",
"data": {
"id": "ORGLOC-123ET"
}
}Response fields (4)
| Field | Type | Description |
|---|---|---|
success | boolean | Example |
message | string | Example |
data | object | |
data.id | string | Example |
401 Not signed in
Unauthorized - Authentication required
{
"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 'settings_locations: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 - Missing or invalid parameters
{
"success": false,
"message": "Organization location name is required.",
"errors": {
"name": [
"Organization location name is required."
]
}
}Response fields (4)
| Field | Type | Description |
|---|---|---|
success | boolean | Example |
message | string | Example |
errors | object | |
errors.name | 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
Internal server error
{
"success": false,
"message": "An unexpected error occurred. Please try again later."
}Response fields (2)
| Field | Type | Description |
|---|---|---|
success | boolean | Example |
message | string | Example |