---
title: "Get work location metadata"
method: POST
path: "/employers/work-locations/metadata/search"
tags: ["Work locations"]
---

# Get work location metadata

`POST /employers/work-locations/metadata/search`

## Request

- Base URL: `https://api.hibob.com/v1`
- URL: `https://api.hibob.com/v1/employers/work-locations/metadata/search`
- Auth: one of:
  - HTTP basic
  - HTTP bearer

Returns the field catalog for the `workLocation` object — the set of fields
a client can read, with their types, validations, and status. Use it to
discover the path-style field IDs (for example `/workLocation/name`) that
drive the work-location search endpoint. The catalog is the same across
employers, so this endpoint is not scoped to a specific employer.
Out-of-the-box fields are documented on the search endpoint; metadata search
is primarily useful for discovering custom fields.

**Before using this endpoint**

- Use this endpoint before the work-location search endpoint to discover the
  full field catalog — every readable field ID (including custom fields), its
  type, and status.
- Out-of-the-box field IDs are also listed as keys on the `WorkLocation`
  response schema on the search endpoint.
- Send an empty body (`{}`) to return the object with default properties and
  all active fields.

**Testing notes**

- Use the testing widget's **Try It!** option to test this endpoint.
- Open **Examples** and select **Request Example** to populate the request
  body.

**OAuth scope (app-user):** `employers:read`.
**IAM permission:** `Settings / Employers / View` (company-scoped).

## Request body

- SearchWorkLocationsMetadataInput: Request body for a work-location metadata search. All members are optional — send an empty body (`{}`) to return the object with its default properties.
  - `objectProperties` string[], nullable: Object properties to fetch. When empty, only `id` is returned.
  - `fields` MetadataFieldsSelector: Field-selection options for a metadata search.
    - `properties` string[], nullable: Field properties to fetch. When empty, only the default `id` and `type` are returned. Additional supported properties: `isRequired`, `status`, `displayName`, `description`, `validations`.
    - `filters` MetadataFilter[], nullable: Filters over fields. When empty, all active fields are returned. Supported filter properties: `status` and `id`.
      - `property` string, required: Field property to filter on. Supported: `status` and `id`.
      - `operator` string, required: Comparison operator. Commonly `equals`.
      - `values` string[], required: Values to compare against, as JSON strings.

## Response `200`

Metadata-search response. Follows the OOTB-object metadata-search guideline:
a list of object-metadata entries, each with its properties and (optionally)
its field definitions.

- SearchMetadataOutput: Metadata-search response. Follows the OOTB-object metadata-search guideline: a list of object-metadata entries, each with its properties and (optionally) its field definitions.
  - `items` ObjectMetadata[], required: Object-metadata entries. One entry per matching object type.
    - `id` string, required: Unique identifier of the object type (for example `employer` or `workLocation`).
    - `displayName` string, nullable: Human-readable name of the object.
    - `fields` FieldMetadata[], nullable: Field definitions. Present only when `fields` was requested.
      - `id` string, required: Path-style field ID (for example `/employer/legalName`). Use this value in the `fields` and `filters` of the matching search endpoint.
      - `type` FieldDataType, required: Data-type wrapper for a field, per the metadata guideline.
        - `dataType` string, required: Field data type. One of the basic types `text`, `date`, `short-date`, `boolean`, `number`, `time`, `currency`, or the reference types `objectReference`, `employee-reference`, `document`, `list`, `multi-list`, `hierarchy-list`.
        - `referenceId` string, nullable: Reference target. Present only when `dataType` is `objectReference` (the referenced object type) or `list` / `multi-list` / `hierarchy-list` (the referenced list ID, for example `countries`).
      - `displayName` string, nullable: Human-readable display name of the field.
      - `description` string, nullable: Field description / help text.
      - `isRequired` boolean, nullable: Whether the field must be supplied when creating the object. Reads in this API are read-only regardless of this flag.
      - `status` string, nullable: Field status — `active` or `archived`.
      - `validations` Validation[], nullable: Validation rules that apply to the field.
        - `type` string, nullable: Validation type (for example `regex`).
        - `value` string, nullable: Validation value (for example a regular-expression pattern).

## Other responses

- `400`: Bad request — the request was malformed, missing required parameters, or referenced an unknown field ID or unsupported filter operator
- `401`: Unauthorized — authentication credentials are missing or invalid
- `403`: Forbidden — the caller lacks the required permission, the `employers:read` scope, or its source IP is not on the company IP trust list
- `429`: Too many requests — rate limit exceeded, retry after the indicated delay
- `500`: Internal server error — an unexpected error occurred on the server

---

[API](https://skmtc.dev/hibob/apis/employer-api.md) - [All operations](https://skmtc.dev/hibob/apis/employer-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hibob/apis/employer-api/revisions/8d775537a41f?raw)