> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sorce.jobs/llms.txt
> Use this file to discover all available pages before exploring further.

# Locations

> Search first, then reference by id. Never free-type a place.

Hybrid and in-person jobs carry office locations, and those locations power
job↔candidate matching. To keep matching exact, the API never accepts
free-typed place names: **every location must come from location search**,
which returns the canonical id (`locationId`) shared across the Sorce
platform.

## 1. Search

```bash theme={null}
curl "https://www.sorce.jobs/api/external/v1/locations/search?q=San+Francisco&country=United+States" \
  -H "Authorization: Bearer sk_ext_..."
```

```json theme={null}
{
  "items": [
    {
      "locationId": 17024,
      "displayName": "San Francisco, California, United States",
      "city": "San Francisco",
      "stateProvince": "California",
      "country": "United States"
    }
  ]
}
```

`country` defaults to `United States` (the only supported country today).

## 2. Reference

Include the chosen suggestion (id and strings together) in the job's
`locations` array:

```json theme={null}
{
  "remoteOption": "HYBRID",
  "locations": [
    {
      "locationId": 17024,
      "city": "San Francisco",
      "stateProvince": "California",
      "country": "United States"
    }
  ]
}
```

Entries without an `locationId` are rejected with
`422 VALIDATION_FAILED` ("Pick each location from the search suggestions.").

## Rules of thumb

* **REMOTE** jobs use `remoteCountry` (e.g. `"United States"`) instead of
  `locations`. Required at publish.
* **HYBRID / IN\_PERSON** jobs need at least one location at publish.
* `locations` is a replace-set: PATCH the full array you want; duplicates
  collapse to one.