Locations

What is the Locations API?

The Locations API (v2) allows you to retrieve information about your organization’s locations (also known as cost centers or office sites). These locations can later be associated with users, transactions, cards, and policies.This API is typically used to:

Fetch a list of all available locations in your company
Get detailed data for a specific location by UUID
Integrate location metadata into internal tools or reporting systems

Available Endpoints

Operation	Endpoint	Method
Retrieve all locations	`/v2/locations`	GET
Get location by UUID	`/v2/locations/{uuid}`	GET

Retrieve all locations

Get a complete list of all locations associated with your company.

Endpoint

GET /v2/locations

cURL Request

cURL

curl -X GET \
"https://public-api.mx.clara.com/api/v2/locations" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Sample JSON Response

JSON

[
  {
    "uuid": "e8b5b764-f8d9-42d0-861a-f13aa2312734",
    "name": "Headquarters - CDMX",
    "code": "CDMX-HQ",
    "status": "ACTIVE"
  },
  {
    "uuid": "a2a8b29f-3c84-4d58-bcb1-b2dc3b23cf01",
    "name": "Warehouse - GDL",
    "code": "GDL-WHS",
    "status": "ACTIVE"
  }
]

Retrieve Location by UUID

Fetch detailed information about a specific location using its UUID.

Endpoint

GET /v2/locations/{uuid}

cURL Request

cURL

curl -X GET \
"https://public-api.mx.clara.com/api/v2/locations/e8b5b764-f8d9-42d0-861a-f13aa2312734" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Sample JSON Response

JSON

{
  "uuid": "e8b5b764-f8d9-42d0-861a-f13aa2312734",
  "name": "Headquarters - CDMX",
  "code": "CDMX-HQ",
  "status": "ACTIVE",
  "createdAt": "2023-10-15T10:30:00Z"
}

💡 Tip: Location UUIDs can be used when creating users, cards, or setting approval policies to associate activity with a specific office or department.⚠️ Note: Locations marked as INACTIVE are still returned, but should not be assigned to new resources.

Endpoint Reference

`GET /api/v2/locations`

Find all locationsParameters:

Parameter	In	Type	Required	Description
`page`	query	integer		Zero-based page index (0..N)
`size`	query	integer		The size of the page to be returned

`GET /api/v2/locations/{uuid}`

Find location by UUIDParameters:

Parameter	In	Type	Required	Description
`uuid`	path	string	✅	Location UUID

v1 is legacy and read-only. Migrate to v2 for full location management.

What is the Locations API?

The Locations API v1 allows you to retrieve the list of physical or organizational locations configured in your Clara account. Locations often represent cost centers, departments, office branches, or teams, and are used to organize users and expenses.This API can be used to:

Display location options when assigning users or filtering data
Map transactions or cards to specific business units
Support reporting or internal structure alignment

🆚 Note: This is a read-only version. To manage or create locations, use Locations API v2.

Available Endpoints

Operation	Endpoint	Method
List all locations	`/v1/locations`	GET
Get location by UUID	`/v1/locations/{uuid}`	GET

Find all locations

Use this endpoint to retrieve the full list of locations configured in your organization. Each location includes metadata such as name, code, and status.

Endpoint

GET /v1/locations

cURL Request

cURL

curl -X GET \
"https://public-api.mx.clara.com/api/v1/locations" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Sample JSON Response

JSON

[
  {
    "uuid": "loc-001",
    "name": "Headquarters - CDMX",
    "code": "CDMX-HQ",
    "status": "ACTIVE"
  },
  {
    "uuid": "loc-002",
    "name": "Warehouse - Monterrey",
    "code": "MTY-WHS",
    "status": "INACTIVE"
  }
]

Find Location by UUID

Use this endpoint to get detailed information about a specific location using its unique identifier (uuid).

Endpoint

GET /v1/locations/{uuid}

cURL Request

cURL

curl -X GET \
"https://public-api.mx.clara.com/api/v1/locations/loc-001" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Sample JSON Response

JSON

{
  "uuid": "loc-001",
  "name": "Headquarters - CDMX",
  "code": "CDMX-HQ",
  "status": "ACTIVE"
}

💡 Tip: Use the code field to link internal systems (e.g., ERP or HR) with Clara locations for consistency in reporting.⚠️ Note: This version of the API does not support creating or updating locations — only retrieval is available.

Endpoint Reference

`GET /api/v1/locations`

Find all locationsParameters:

Parameter	In	Type	Required	Description
`page`	query	integer		Zero-based page index (0..N)
`size`	query	integer		The size of the page to be returned

`GET /api/v1/locations/{uuid}`

Find location by UUIDParameters:

Parameter	In	Type	Required	Description
`uuid`	path	string	✅	Location UUID

Overview

Conventions

Guides

Resources

API Reference

MCP

VCN

What is the Locations API?

Available Endpoints

Retrieve all locations

Endpoint

cURL Request

Sample JSON Response

Retrieve Location by UUID

Endpoint

cURL Request

Sample JSON Response

Endpoint Reference

`GET /api/v2/locations`

`GET /api/v2/locations/{uuid}`

What is the Locations API?

Available Endpoints

Find all locations

Endpoint

cURL Request

Sample JSON Response

Find Location by UUID

Endpoint

cURL Request

Sample JSON Response

Endpoint Reference

`GET /api/v1/locations`

`GET /api/v1/locations/{uuid}`

​What is the Locations API?

​Available Endpoints

​Retrieve all locations

​Endpoint

​cURL Request

​Sample JSON Response

​Retrieve Location by UUID

​Endpoint

​cURL Request

​Sample JSON Response

​Endpoint Reference

​GET /api/v2/locations

​GET /api/v2/locations/{uuid}

​What is the Locations API?

​Available Endpoints

​Find all locations

​Endpoint

​cURL Request

​Sample JSON Response

​Find Location by UUID

​Endpoint

​cURL Request

​Sample JSON Response

​Endpoint Reference

​GET /api/v1/locations

​GET /api/v1/locations/{uuid}

What is the Locations API?

Available Endpoints

Retrieve all locations

Endpoint

cURL Request

Sample JSON Response

Retrieve Location by UUID

Endpoint

cURL Request

Sample JSON Response

Endpoint Reference

`GET /api/v2/locations`

`GET /api/v2/locations/{uuid}`

What is the Locations API?

Available Endpoints

Find all locations

Endpoint

cURL Request

Sample JSON Response

Find Location by UUID

Endpoint

cURL Request

Sample JSON Response

Endpoint Reference

`GET /api/v1/locations`

`GET /api/v1/locations/{uuid}`