Get locations

curl --request GET \
  --url https://api.wellapp.ai/v1/locations \
  --header 'Authorization: <authorization>'

{
  "data": [
    {
      "type": "location",
      "id": "loc1",
      "attributes": {
        "full_address": "123 Turing Way, London, Greater London, E1 6AN, GB",
        "address_line1": "123 Turing Way",
        "address_line2": "",
        "city": "London",
        "region": "Greater London",
        "postal_code": "E1 6AN",
        "country": "GB",
        "latitude": 37.7749,
        "longitude": -122.4194,
        "is_primary": true,
        "is_registered": true,
        "created_at": "2025-06-01T10:00:00Z",
        "updated_at": "2025-06-01T10:00:00Z"
      },
      "relationships": {
        "persons": {
          "data": [
            {
              "type": "people",
              "id": "people1"
            }
          ]
        },
        "companies": {
          "data": [
            {
              "type": "company",
              "id": "company_tenant"
            }
          ]
        },
        "workspaces": {
          "data": [
            {
              "type": "workspace",
              "id": "workspace_tenant"
            }
          ]
        }
      }
    }
  ],
  "included": [
    {
      "type": "people",
      "id": "people1",
      "attributes": {
        "first_name": "Alan",
        "last_name": "Turing",
        "full_name": "Alan Turing",
        "created_at": "2025-06-01T09:00:00Z",
        "updated_at": "2025-06-01T09:00:00Z"
      }
    },
    {
      "type": "company",
      "id": "company_tenant",
      "attributes": {
        "name": "Tech Innovations Ltd",
        "description": "Leading technology research company",
        "locale": "en",
        "domain_name_primary_link_url": "techinnovations.com",
        "tax_id": {
          "value": "GB123456789",
          "type": "VAT"
        },
        "registration": {
          "trade_name": "Tech Innovations",
          "registered_name": "Tech Innovations Limited"
        },
        "registration_number": {
          "business_type": "Ltd",
          "value": "12345678",
          "registry_name": "Companies House",
          "registry_country": "GB"
        },
        "created_at": "2025-05-15T08:00:00Z",
        "updated_at": "2025-05-15T08:00:00Z"
      }
    },
    {
      "type": "workspace",
      "id": "workspace_tenant",
      "attributes": {
        "name": "UK Operations Workspace",
        "description": "Workspace for UK-based operations and teams",
        "avatar_color": "#2E86AB",
        "external_workspace_id": "uk_ops_ws_001",
        "auto_extract_enabled": true,
        "created_at": "2025-05-20T10:00:00Z",
        "updated_at": "2025-05-20T10:00:00Z"
      }
    }
  ],
  "meta": {
    "pagination": {
      "total": 1,
      "count": 1,
      "per_page": 20,
      "current_page": 1,
      "total_pages": 1
    }
  }
}

Location

Get Location

Retrieve a list of locations with advanced filtering, sorting, and include capabilities. This endpoint supports:

Default behavior: Returns locations with basic information (IDs only for relationships).

Include functionality: Use the include parameter to get detailed relationship data.

Date filtering: Filter by creation, update, or deletion date ranges.

Relationship filtering: Filter by related entities using various identifiers.

Location filtering: Filter by registration and primary status.

Sorting: Sort results by date fields in ascending or descending order.

GET

locations

Get locations

curl --request GET \
  --url https://api.wellapp.ai/v1/locations \
  --header 'Authorization: <authorization>'

{
  "data": [
    {
      "type": "location",
      "id": "loc1",
      "attributes": {
        "full_address": "123 Turing Way, London, Greater London, E1 6AN, GB",
        "address_line1": "123 Turing Way",
        "address_line2": "",
        "city": "London",
        "region": "Greater London",
        "postal_code": "E1 6AN",
        "country": "GB",
        "latitude": 37.7749,
        "longitude": -122.4194,
        "is_primary": true,
        "is_registered": true,
        "created_at": "2025-06-01T10:00:00Z",
        "updated_at": "2025-06-01T10:00:00Z"
      },
      "relationships": {
        "persons": {
          "data": [
            {
              "type": "people",
              "id": "people1"
            }
          ]
        },
        "companies": {
          "data": [
            {
              "type": "company",
              "id": "company_tenant"
            }
          ]
        },
        "workspaces": {
          "data": [
            {
              "type": "workspace",
              "id": "workspace_tenant"
            }
          ]
        }
      }
    }
  ],
  "included": [
    {
      "type": "people",
      "id": "people1",
      "attributes": {
        "first_name": "Alan",
        "last_name": "Turing",
        "full_name": "Alan Turing",
        "created_at": "2025-06-01T09:00:00Z",
        "updated_at": "2025-06-01T09:00:00Z"
      }
    },
    {
      "type": "company",
      "id": "company_tenant",
      "attributes": {
        "name": "Tech Innovations Ltd",
        "description": "Leading technology research company",
        "locale": "en",
        "domain_name_primary_link_url": "techinnovations.com",
        "tax_id": {
          "value": "GB123456789",
          "type": "VAT"
        },
        "registration": {
          "trade_name": "Tech Innovations",
          "registered_name": "Tech Innovations Limited"
        },
        "registration_number": {
          "business_type": "Ltd",
          "value": "12345678",
          "registry_name": "Companies House",
          "registry_country": "GB"
        },
        "created_at": "2025-05-15T08:00:00Z",
        "updated_at": "2025-05-15T08:00:00Z"
      }
    },
    {
      "type": "workspace",
      "id": "workspace_tenant",
      "attributes": {
        "name": "UK Operations Workspace",
        "description": "Workspace for UK-based operations and teams",
        "avatar_color": "#2E86AB",
        "external_workspace_id": "uk_ops_ws_001",
        "auto_extract_enabled": true,
        "created_at": "2025-05-20T10:00:00Z",
        "updated_at": "2025-05-20T10:00:00Z"
      }
    }
  ],
  "meta": {
    "pagination": {
      "total": 1,
      "count": 1,
      "per_page": 20,
      "current_page": 1,
      "total_pages": 1
    }
  }
}

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"

Headers

Authorization

string

required

Bearer token for authentication

Query Parameters

include

string

Comma-separated list of related resources to include with detailed attributes. Available options: persons, companies, workspaces

created_at_from

string<date-time>

Filter locations created on or after this datetime (ISO 8601 format)

created_at_to

string<date-time>

Filter locations created on or before this datetime (ISO 8601 format)

updated_at_from

string<date-time>

Filter locations updated on or after this datetime (ISO 8601 format)

updated_at_to

string<date-time>

Filter locations updated on or before this datetime (ISO 8601 format)

workspace_id

string<uuid>

Filter locations by workspace UUID

external_workspace_id

string

Filter locations by external workspace identifier

people_id

string<uuid>

Filter locations by person UUID

company_id

string<uuid>

Filter locations by company UUID

is_registered

boolean

Filter locations by registration status (true/false)

is_primary

boolean

Filter locations by primary status (true/false)

sort

enum<string>

Sort locations by date field. Use '-' prefix for descending order (e.g., '-created_at' for newest first)

Available options:

created_at,

updated_at,

-created_at

page[limit]

integer

default:20

Number of locations per page (1-100)

Required range: 1 <= x <= 100

page[cursor]

string

Cursor for pagination to get next set of results

Response

Locations retrieved successfully

data

object

Show child attributes

data.type

string

Example:

"location"

data.id

string<uuid>

data.attributes

object

Show child attributes

data.attributes.full_address

string

Complete formatted address

data.attributes.address_line1

string

Primary address line

data.attributes.address_line2

string

Secondary address line

data.attributes.city

string

City name

data.attributes.region

string

State, province, or region

data.attributes.postal_code

string

Postal or ZIP code

data.attributes.country

string

Two-letter ISO country code

data.attributes.latitude

number<float>

Geographic latitude coordinate

data.attributes.longitude

number<float>

Geographic longitude coordinate

data.attributes.is_primary

boolean

Whether this is the primary location

data.attributes.is_registered

boolean

Whether this is a registered business address

data.attributes.label

string

Custom label for the location

data.attributes.created_at

string<date-time>

Date and time when the location was created

data.attributes.updated_at

string<date-time>

Date and time when the location was last updated

data.relationships

object

Show child attributes

data.relationships.persons

object

Show child attributes

data.relationships.persons.data

object[]

Show child attributes

data.relationships.persons.data.type

enum<string>

Available options:

people

data.relationships.persons.data.id

string

Person ID

data.relationships.persons.data.attributes

object

Person attribute data

Show child attributes

data.relationships.persons.data.attributes.first_name

string

required

Person's first name

Required string length: 1 - 100

Example:

"Marie"

data.relationships.persons.data.attributes.last_name

string

required

Person's last name

Required string length: 1 - 100

Example:

"Dubois"

data.relationships.persons.data.attributes.created_at

string<date-time>

required

Person creation timestamp (UTC)

Example:

"2024-01-15T10:30:00Z"

data.relationships.persons.data.attributes.full_name

string

Auto-computed full name (first + last)

Example:

"Marie Dubois"

data.relationships.persons.data.attributes.updated_at

string<date-time> | null

Last modification timestamp (UTC)

Example:

"2024-01-16T14:20:00Z"

data.relationships.companies

object

Show child attributes

data.relationships.companies.data

object[]

Show child attributes

data.relationships.companies.data.type

enum<string>

Available options:

company

data.relationships.companies.data.id

string

Company ID

data.relationships.companies.data.attributes

object

Show child attributes

data.relationships.companies.data.attributes.description

string

data.relationships.companies.data.attributes.domain_name_primary_link_url

string<url>

The domain url from the website or email address of the company. Used as unique identifier in some cases.

Maximum string length: 500

data.relationships.companies.data.attributes.tax_id

object

Show child attributes

data.relationships.companies.data.attributes.tax_id.value

string

Tax ID issued by local or national tax authority.

data.relationships.companies.data.attributes.tax_id.type

string

Type of tax ID, useful for applying formatting and validation rules.

data.relationships.companies.data.attributes.registration

object

Show child attributes

data.relationships.companies.data.attributes.registration.trade_name

string

Commercial or branding name (if different from registered name).

data.relationships.companies.data.attributes.registration.registered_name

string

Legal company name.

Required string length: 1 - 100

data.relationships.companies.data.attributes.registration_number

object

Show child attributes

data.relationships.companies.data.attributes.registration_number.business_type

string

Legal entity structure type.

data.relationships.companies.data.attributes.registration_number.value

string

Official company registration number.

data.relationships.companies.data.attributes.registration_number.registry_name

string

Name of the official registration body.

data.relationships.companies.data.attributes.registration_number.registry_country

string

Country of the registry authority. (string (ISO 3166-1 alpha-2))

data.relationships.companies.data.attributes.workspace_id

string<uuid>

UUID of the workspace associated with this company

data.relationships.companies.data.attributes.created_at

string<date-time>

data.relationships.companies.data.attributes.updated_at

string<date-time>

data.relationships.workspaces

object

Show child attributes

data.relationships.workspaces.data

object[]

Show child attributes

data.relationships.workspaces.data.type

enum<string>

Available options:

workspace

data.relationships.workspaces.data.id

string

Workspace ID

data.relationships.workspaces.data.attributes

object

Show child attributes

data.relationships.workspaces.data.attributes.name

string

Workspace name

data.relationships.workspaces.data.attributes.desription

string

Workspace description

data.relationships.workspaces.data.attributes.external_workspace_id

string<uuid>

external workspace id

data.relationships.workspaces.data.attributes.avatar_color

string<colors>

Color of the avatar

data.relationships.workspaces.data.attributes.created_at

string<date-time>

Timestamp when the workspace was created

data.relationships.workspaces.data.attributes.updated_at

string<date-time>

Timestamp when the workspace was last updated

Create Location Get Location by id

⌘I

Main Resources

Atomic Resources

System

Get Location

Complex Usage Example

Advanced Location Filtering with Full Context

Headers

Query Parameters

Response

Main Resources

Atomic Resources

System

​Complex Usage Example

​Advanced Location Filtering with Full Context

Headers

Query Parameters

Response

Complex Usage Example

Advanced Location Filtering with Full Context