Get Location

get/v1/locations

Returns a cursor-paginated, workspace-scoped list of location rows from the records pipeline. Read-only; no side effects. Locations are created and deleted as sub-resources of a person or company. ## Filtering & sorting Filter via `POST /v1/records/query` (root `locations`) or the `filters` model; operators are gated by each field's data type. See [Filtering & sorting](../filtering-and-sorting). **Filterable fields** | Field | Type | Allowed operators | |---|---|---| | `address_line1` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `address_line2` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `city` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `composite_companies_list` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `composite_location_summary` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `composite_people_list` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `country` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `created_at` | date | `eq` `lt` `gt` `is_null` `is_not_null` | | `deleted_at` | date | `eq` `lt` `gt` `is_null` `is_not_null` | | `full_address` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `location_id` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `pk` | number | `eq` `neq` `gt` `gte` `lt` `lte` `is_null` `is_not_null` | | `postal_code` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `region` | text | `contains` `eq` `neq` `starts_with` `ends_with` `is_null` `is_not_null` | | `updated_at` | date | `eq` `lt` `gt` `is_null` `is_not_null` | **Sortable fields:** `address_line1`, `address_line2`, `city`, `composite_companies_list`, `composite_location_summary`, `composite_people_list`, `country`, `created_at`, `deleted_at`, `full_address`, `location_id`, `pk`, `postal_code`, `region`, `updated_at` (via `orderBy` / `sort`, `asc`|`desc`).

Requires a bearer token: Authorization: Bearer <token>.

Query parameters

Name	Type	Required	Description
limit	string	No	Page size, 1 to 200.e.g. 50
cursor	string	No	Opaque cursor from a prior page's links.next.e.g. eyJwayI6OTl9
orderBy	string	No	Column to order by.e.g. created_at
direction	string	No	Sort direction.e.g. desc
workspaceId	string <uuid>	No	Workspace to scope to; defaults to the token's workspace.e.g. 8f6b2c10-4a1e-4d2b-9c3a-1f0e7a5b6c21

Request

cURL

curl -X GET https://api.wellapp.ai/v1/locations \
  -H "Authorization: Bearer $WELL_API_TOKEN"

Responses

200 — A page of location rows.

{
  "data": [
    {
      "type": "location",
      "id": "0a1b2c3d-4e5f-4607-8819-2a3b4c5d6e7f",
      "attributes": {
        "full_address": "548 Market St, San Francisco, CA 94104, US",
        "address_line1": "548 Market St",
        "address_line2": "Suite 320",
        "city": "San Francisco",
        "region": "CA",
        "postal_code": "94104",
        "country": "US"
      },
      "relationships": {
        "company_locations": {
          "data": [
            {
              "type": "company_location",
              "id": "00000000-0000-4000-8000-000000000001"
            }
          ]
        },
        "person_locations": {
          "data": [
            {
              "type": "person_location",
              "id": "00000000-0000-4000-8000-000000000001"
            }
          ]
        }
      }
    }
  ],
  "meta": {
    "total": 12,
    "count": 1
  },
  "links": {
    "next": null
  }
}

401 — Unauthorized

{
  "code": "UNAUTHORIZED",
  "status": 401,
  "title": "Unauthorized",
  "message": "See title.",
  "meta": {
    "trace_id": "a1b2c3",
    "log_id": "a1b2c3"
  }
}

403 — Forbidden

{
  "code": "FORBIDDEN",
  "status": 403,
  "title": "Forbidden",
  "message": "See title.",
  "meta": {
    "trace_id": "a1b2c3",
    "log_id": "a1b2c3"
  }
}

Complex Usage Example

Advanced Location Filtering with Full Context

This example demonstrates advanced filtering with multiple parameters, relationship inclusion, status filtering, and sorting for retrieving locations:

curl -X GET "https://api.well.com/v1/locations?include=persons,companies,workspaces&workspace_id=550e8400-e29b-41d4-a716-446655440000&company_id=550e8400-e29b-41d4-a716-446655440001&is_registered=true&is_primary=true&created_at_from=2023-01-01T00:00:00Z&created_at_to=2023-12-31T23:59:59Z&updated_at_from=2023-06-01T00:00:00Z&sort=-created_at&page[limit]=20&page[cursor]=eyJjcmVhdGVkX2F0IjoiMjAyMy0xMS0wMlQxMDozMDowMFoiLCJpZCI6ImxvY2F0aW9uOS11dWlkIn0=" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"