📍 Locations API: How to Use It

🔍 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

1️⃣ 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"
  }
]

2️⃣ 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.