Find location ids

Changed on Oct 20, 2026

Turns a place name into geo_ids for people search filters. Free, including a place this server has not seen before. The result is cached. This call never charges. An empty result includes a hint. A region name points at a city or the country.

Scope: sourcing:read.

get/v1/lookups/locations

Request

Base URL: https://api.recruitmcp.com
URL: https://api.recruitmcp.com/v1/lookups/locations
Auth: one of:
- HTTP bearer
- OAuth 2 (authorization code, authorization URL https://recruitmcp.com/oauth/authorize, token URL https://recruitmcp.com/oauth/token, scopes: sourcing:read)

Query parameters

qstring required

Place name, for example London.

prefer_areaboolean

Prefer the metropolitan area over the city.

limitinteger

How many items to return. Default 25, at most 100.

cursorstring

next_cursor from the previous response. An invalid cursor is 400 invalid_request, message Invalid cursor.

Headers

RecruitMCP-Version'2026-10-13'

API version. Defaults to the version the key was created with. Supported: 2026-10-13.

RecruitMCP-Customerstring

Act inside this customer (cus_…). Ignored for keys bound to a customer, which always act inside theirs.

Response

Matches, best first.

object'list' required

next_cursorstring nullable required

Pass as cursor for the next page. Null on the last page.

has_moreboolean required

hintstring

Set when the place has no city id. The country is not returned as a silent stand-in.

fallback'country'

country when the only match was a country. data stays empty.

Example response

{
  "object": "list",
  "data": [
    {
      "geo_id": "90009496",
      "title": "London Area, United Kingdom",
      "is_area": true
    },
    {
      "geo_id": "102257491",
      "title": "Greater London, England, United Kingdom",
      "is_area": false
    }
  ],
  "next_cursor": null,
  "has_more": false,
  "cost": {
    "credits": 0,
    "cached_items": 0,
    "live_items": 0,
    "upstream_calls": 0
  }
}

Changes

Oct 20, 2026ad27b35513a6 Revision changes
- warning
  added the new approval_forced enum value to the / response property for the response status
- warning
  added the new approval_forced enum value to the / response property for the response status
- warning
  added the new approval_forced enum value to the / response property for the response status
- warning
  added the new approval_forced enum value to the / response property for the response status
- warning
  added the new approval_forced enum value to the / response property for the response status
- warning
  added the new approval_forced enum value to the / response property for the response status
- warning
  added the new approval_forced enum value to the / response property for the response status

Operation history