API reference › Organization locations

Update an existing organization location

POST /v1/organization-location/{id}

Scope
settings_locations:edit
Roles
admin, scheduler

Update an organization location with the provided details, including skills, certifications, and specializations.

Parameters

Path parameters

NameTypeDescription
id requiredstring

ID of the organization location to update

Example ORGLOC-1RED2.

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

Request body required

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

FieldTypeDescription
name requiredstring

Name of the organization Location

Example Location 1.

descriptionstring or null

Brief description of the organization location

Example This is a demo tenant for showcasing purposes..

logostring or null

Organization Location Logo

departmentstring

Enter organization departments OR units

Example Test.

contactImagestring or null

Organization's contact person image

contactNamestring (string)

Organization's contact name

Example Contact Name.

contactEmailstring (email)

Organization's contact email

Example contact@demotenant.com.

rolestring or null

contact person role

Example Role.

countryCodestring or null

Organization's contact phone country code

Example +1.

phonestring or null

Organization's contact phone number

Example 9888888888.

videoPhoneCountryCodestring or null

Video phone country code

Example +1.

videoPhonestring or null

Video phone number

Example 9888888888.

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.

phoneTypestring or null

Organization's contact phone type

Example voice_only.

addressLine1string

Enter street address line1.

Example addressLine1.

addressLine2string or null

Enter street address line2.

Example addressLine2.

citystring

Enter organization location city

Example City.

stateobject (2 nested)

Organization location state

postalCodestring

Enter organization location postal code

Example 12345.

accessInstructionstring

Enter organization location access instructions

Example Access instructions text.

skillsarray of object (2 nested)

Skills associated with the organization location, including predefined and custom skills

certificationsarray of object (2 nested)

Certifications associated with the organization location

clearancesarray of object (2 nested)

Security clearances assigned to the organization location

specializationsarray of object (2 nested)

Specializations assigned to the organization location

internalNotesstring or null

Internal notes for administrators

Example Confidential information regarding tenant..

statusobject (2 nested)

Status of the location. Required when publishing.

phoneExtensionstring or null

Example 204.

timezonestring or null

IANA timezone of the location

Example America/New_York.

shiftCapacityboolean or null

The location tracks shift capacity

Example false.

minimumCapacityinteger or null

Must not exceed maximumCapacity

min 0. Example 1.

maximumCapacityinteger or null

Must be at least minimumCapacity

min 1. Example 10.

isPublishedboolean

Publishing makes the address, contact and status fields required

Example true.

enableCustomRatesboolean or null

Example false.

requireVerifiedTimeDocumentationboolean or null

Example false.

customizeRequirementPreferencesboolean or null

Example false.

adminFeenumber (float) or null

Example 5.

adminFeeMethodstring or null

Defaults to flat

Example flat.

adminFeeTypestring or null

What the admin fee applies to

One of: assignment, shift, both. Example assignment.

documentsarray of object (9 nested)
ratesarray of object (24 nested)
singleRatesarray of object (12 nested)
reimbursableExpensesarray of object (2 nested)

Reimbursable expenses offered at this location, by id. Ones not sent are removed.

requirementAndPreferencesarray of object (23 nested)

Nested fields

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.

state 2 fields
FieldTypeDescription
state.idinteger

Example 8.

state.labelstring

Example Delaware.

skills 2 fields
FieldTypeDescription
skills[].idinteger or null
skills[].labelstring

Example Custom1.

certifications 2 fields
FieldTypeDescription
certifications[].idinteger or null
certifications[].labelstring

Example Custom1.

clearances 2 fields
FieldTypeDescription
clearances[].idinteger or null
clearances[].labelstring

Example Custom1.

specializations 2 fields
FieldTypeDescription
specializations[].idinteger or null
specializations[].labelstring

Example Custom1.

status 2 fields
FieldTypeDescription
status.idinteger

Example 1.

status.labelstring

Example Active.

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.

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.

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.

Example

JSON
{
  "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"
        }
      ]
    }
  ]
}

Example request

Shell
curl -X POST "https://api.fetchfido.ai/v1/organization-location/{id}" \
  -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"}]}]}'

Try it

Responses

200 Organization location updated successfully

Organization location updated successfully

JSON
{
  "success": true,
  "message": "Organization location updated successfully",
  "data": {
    "id": "ORGLOC-123ET"
  }
}
Response fields (4)
FieldTypeDescription
successboolean

Example true.

messagestring

Example Organization location updated successfully.

dataobject
data.idstring

Example ORGLOC-123ET.

401 Not signed in

Unauthorized - Authentication required

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

Forbidden. The payload carries a Rates & Billing field (rates, single rates, admin fee, billing and cancellation terms) and the role has no Finance Edit, so nothing is saved. A payload without those fields follows the record's own permission alone.

JSON
{
  "success": false,
  "message": "You don't have permission to access this endpoint. This API key is missing the 'settings_locations:edit' 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_locations:edit' scope..

errorsany or null

Null on this status.

codestring

Always empty on this status.

Example .

422 Validation failed

Validation error - Missing or invalid parameters. A rate unit other than Per Hour or Per Minute (for example weekly) in a rate or single-rate row is refused and nothing is saved: the same 422 body with errors.unit, errors.assignmentRateUnit or errors.shiftRateUnit (no row index).

JSON
{
  "success": false,
  "message": "Organization location name is required.",
  "errors": {
    "name": [
      "Organization location name is required."
    ]
  }
}
Response fields (4)
FieldTypeDescription
successboolean

Example false.

messagestring

Example Organization location name is required..

errorsobject
errors.namearray 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

Internal server error

JSON
{
  "success": false,
  "message": "An unexpected error occurred. Please try again later."
}
Response fields (2)
FieldTypeDescription
successboolean

Example false.

messagestring

Example An unexpected error occurred. Please try again later..