---
updatedAt: 2026-07-21T10:22:34.000Z
---

Fetch the complete documentation index at: https://apidocs.hibob.com/llms.txt. Use this file to discover all available pages before exploring further.

# Get work location metadata

Discover the readable work-location field catalog, including custom fields.

# OpenAPI definition

```json
{
  "openapi": "3.1.1",
  "info": {
    "title": "Employer API",
    "contact": {
      "name": "Hi Bob, Inc."
    },
    "description": "Public read API for the employer domain — legal employers and their work\nlocations. All endpoints are read-only and search-based; there are no\nsingle-object endpoints, which keeps integrations bulk-first.\n\nAll endpoints support both service-user (basic auth) and Marketplace app\n(OAuth 2.0) callers. App-user callers must hold the `employers:read` scope.\nEvery endpoint is company-scoped and requires the IAM permission\n`Settings / Employers / View`.",
    "license": {
      "name": "Proprietary",
      "url": "https://apidocs.hibob.com/docs/api-terms-of-use"
    },
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.hibob.com/v1",
      "description": "Production"
    },
    {
      "url": "https://api.sandbox.hibob.com/v1",
      "description": "Sandbox"
    }
  ],
  "x-readme": {
    "metrics-enabled": false
  },
  "tags": [
    {
      "name": "Work locations",
      "description": "Operations for managing Work locations"
    }
  ],
  "security": [
    {
      "basic": []
    },
    {
      "bearer": []
    }
  ],
  "paths": {
    "/employers/work-locations/metadata/search": {
      "post": {
        "operationId": "post_employers-work-locations-metadata-search",
        "tags": [
          "Work locations"
        ],
        "summary": "Get work location metadata",
        "description": "Discover the readable work-location field catalog, including custom fields.",
        "requestBody": {
          "required": true,
          "description": "Request body for a work-location metadata search. All members are optional —\nsend an empty body (`{}`) to return the object with its default properties.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SearchWorkLocationsMetadataInput"
              },
              "examples": {
                "default": {
                  "summary": "Object with default properties and all active fields",
                  "value": {
                    "fields": {
                      "properties": [],
                      "filters": []
                    }
                  }
                },
                "activeFields": {
                  "summary": "Only active fields, selected field properties",
                  "value": {
                    "fields": {
                      "properties": [
                        "id",
                        "type",
                        "isRequired",
                        "status"
                      ],
                      "filters": [
                        {
                          "property": "status",
                          "operator": "equals",
                          "values": [
                            "active"
                          ]
                        }
                      ]
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Metadata-search response. Follows the OOTB-object metadata-search guideline:\na list of object-metadata entries, each with its properties and (optionally)\nits field definitions.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchMetadataOutput"
                },
                "examples": {
                  "catalog": {
                    "summary": "Field catalog response",
                    "value": {
                      "items": [
                        {
                          "id": "workLocation",
                          "displayName": "Work location",
                          "fields": [
                            {
                              "id": "/workLocation/name",
                              "type": {
                                "dataType": "text"
                              },
                              "displayName": "Name",
                              "isRequired": true,
                              "status": "active"
                            },
                            {
                              "id": "/workLocation/status",
                              "type": {
                                "dataType": "text"
                              },
                              "displayName": "Status",
                              "isRequired": true,
                              "status": "active"
                            },
                            {
                              "id": "/workLocation/createdBy",
                              "type": {
                                "dataType": "employee-reference"
                              },
                              "displayName": "Created by",
                              "isRequired": false,
                              "status": "active"
                            }
                          ]
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request — the request was malformed, missing required parameters, or referenced an unknown field ID or unsupported filter operator",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized — authentication credentials are missing or invalid",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorResponse"
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the caller lacks the required permission, the `employers:read` scope, or its source IP is not on the company IP trust list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorResponse"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests — rate limit exceeded, retry after the indicated delay",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error — an unexpected error occurred on the server",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorResponse"
                }
              }
            }
          }
        },
        "x-internal": false
      }
    }
  },
  "components": {
    "securitySchemes": {
      "basic": {
        "type": "http",
        "scheme": "basic"
      },
      "bearer": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "OAuth 2.0",
        "description": "OAuth 2.0 access token. <a href=\"https://apidocs.hibob.com/reference/oauth-20\" target=\"_blank\">Learn more about OAuth 2.0 in HiBob</a>"
      }
    },
    "schemas": {
      "ApiErrorResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "Stable machine-readable error code"
          },
          "message": {
            "type": "string",
            "description": "Human-readable error message"
          },
          "details": {
            "type": "object",
            "additionalProperties": true,
            "description": "Structured error context keyed by field or domain identifier"
          },
          "request_id": {
            "type": "string",
            "description": "Request identifier for support and tracing"
          }
        }
      },
      "FieldDataType": {
        "description": "Data-type wrapper for a field, per the metadata guideline.",
        "type": "object",
        "properties": {
          "dataType": {
            "type": "string",
            "description": "Field data type. One of the basic types `text`, `date`, `short-date`,\n`boolean`, `number`, `time`, `currency`, or the reference types\n`objectReference`, `employee-reference`, `document`, `list`,\n`multi-list`, `hierarchy-list`."
          },
          "referenceId": {
            "type": [
              "string",
              "null"
            ],
            "description": "Reference target. Present only when `dataType` is `objectReference`\n(the referenced object type) or `list` / `multi-list` / `hierarchy-list`\n(the referenced list ID, for example `countries`)."
          }
        },
        "required": [
          "dataType"
        ]
      },
      "FieldMetadata": {
        "description": "Metadata for a single readable field on an object.",
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Path-style field ID (for example `/employer/legalName`). Use this value\nin the `fields` and `filters` of the matching search endpoint."
          },
          "type": {
            "$ref": "#/components/schemas/FieldDataType",
            "description": "Data-type wrapper for the field."
          },
          "displayName": {
            "type": [
              "string",
              "null"
            ],
            "description": "Human-readable display name of the field."
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "description": "Field description / help text."
          },
          "isRequired": {
            "type": [
              "boolean",
              "null"
            ],
            "description": "Whether the field must be supplied when creating the object. Reads in\nthis API are read-only regardless of this flag."
          },
          "status": {
            "type": [
              "string",
              "null"
            ],
            "description": "Field status — `active` or `archived`."
          },
          "validations": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "$ref": "#/components/schemas/Validation"
            },
            "description": "Validation rules that apply to the field."
          }
        },
        "required": [
          "id",
          "type"
        ]
      },
      "MetadataFieldsSelector": {
        "description": "Field-selection options for a metadata search.",
        "type": "object",
        "properties": {
          "properties": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            },
            "description": "Field properties to fetch. When empty, only the default `id` and `type`\nare returned. Additional supported properties: `isRequired`, `status`,\n`displayName`, `description`, `validations`."
          },
          "filters": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "$ref": "#/components/schemas/MetadataFilter"
            },
            "description": "Filters over fields. When empty, all active fields are returned.\nSupported filter properties: `status` and `id`."
          }
        }
      },
      "MetadataFilter": {
        "description": "A single field filter — narrows the returned fields by a field property.",
        "type": "object",
        "properties": {
          "property": {
            "type": "string",
            "description": "Field property to filter on. Supported: `status` and `id`."
          },
          "operator": {
            "type": "string",
            "description": "Comparison operator. Commonly `equals`."
          },
          "values": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Values to compare against, as JSON strings."
          }
        },
        "required": [
          "property",
          "operator",
          "values"
        ]
      },
      "ObjectMetadata": {
        "description": "Metadata for a single object type.",
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier of the object type (for example `employer` or\n`workLocation`)."
          },
          "displayName": {
            "type": [
              "string",
              "null"
            ],
            "description": "Human-readable name of the object."
          },
          "fields": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "$ref": "#/components/schemas/FieldMetadata"
            },
            "description": "Field definitions. Present only when `fields` was requested."
          }
        },
        "required": [
          "id"
        ]
      },
      "SearchMetadataOutput": {
        "description": "Metadata-search response. Follows the OOTB-object metadata-search guideline:\na list of object-metadata entries, each with its properties and (optionally)\nits field definitions.",
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ObjectMetadata"
            },
            "description": "Object-metadata entries. One entry per matching object type."
          }
        },
        "required": [
          "items"
        ]
      },
      "SearchWorkLocationsMetadataInput": {
        "description": "Request body for a work-location metadata search. All members are optional —\nsend an empty body (`{}`) to return the object with its default properties.",
        "type": "object",
        "properties": {
          "objectProperties": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "string"
            },
            "description": "Object properties to fetch. When empty, only `id` is returned."
          },
          "fields": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/MetadataFieldsSelector"
              },
              {
                "type": "null"
              }
            ],
            "description": "Field-selection options. When omitted, the response does not include the\n`fields` array."
          }
        },
        "default": {
          "objectProperties": [],
          "fields": {
            "properties": [],
            "filters": []
          }
        }
      },
      "Validation": {
        "description": "A single field validation rule.",
        "type": "object",
        "properties": {
          "type": {
            "type": [
              "string",
              "null"
            ],
            "description": "Validation type (for example `regex`)."
          },
          "value": {
            "type": [
              "string",
              "null"
            ],
            "description": "Validation value (for example a regular-expression pattern)."
          }
        }
      }
    }
  }
}
```