> ## Documentation Index
> Fetch the complete documentation index at: https://developers.clara.team/llms.txt
> Use this file to discover all available pages before exploring further.

# Locations

> Retrieve company cost centers and locations.

<Tabs>
  <Tab title="v2">
    ## 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

    <br />

    ## Available Endpoints

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

    <br />

    ## Retrieve all locations

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

    ### Endpoint

    `GET /v2/locations`

    ### cURL Request

    ```curl cURL theme={null}
    curl -X GET \
    "https://public-api.mx.clara.com/api/v2/locations" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
    ```

    ### Sample JSON Response

    ```json JSON theme={null}
    [
      {
        "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"
      }
    ]

    ```

    <br />

    ## Retrieve Location by UUID

    Fetch detailed information about a specific location using its UUID.

    ### Endpoint

    `GET /v2/locations/{uuid}`

    ### cURL Request

    ```curl cURL theme={null}
    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 JSON theme={null}
    {
      "uuid": "e8b5b764-f8d9-42d0-861a-f13aa2312734",
      "name": "Headquarters - CDMX",
      "code": "CDMX-HQ",
      "status": "ACTIVE",
      "createdAt": "2023-10-15T10:30:00Z"
    }

    ```

    <br />

    **💡 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 locations

    **Parameters:**

    | 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 UUID

    **Parameters:**

    | Parameter | In   | Type   | Required | Description   |
    | --------- | ---- | ------ | -------- | ------------- |
    | `uuid`    | path | string | ✅        | Location UUID |
  </Tab>

  <Tab title="v1">
    <Warning>v1 is legacy and read-only. Migrate to v2 for full location management.</Warning>

    ## 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](#).

    <br />

    ## Available Endpoints

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

    <br />

    ## 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 theme={null}
    curl -X GET \
    "https://public-api.mx.clara.com/api/v1/locations" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
    ```

    ### Sample JSON Response

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

    <br />

    ## 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 theme={null}
    curl -X GET \
    "https://public-api.mx.clara.com/api/v1/locations/loc-001" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
    ```

    ### Sample JSON Response

    ```json JSON theme={null}
    {
      "uuid": "loc-001",
      "name": "Headquarters - CDMX",
      "code": "CDMX-HQ",
      "status": "ACTIVE"
    }

    ```

    <br />

    **💡 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 locations

    **Parameters:**

    | 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 UUID

    **Parameters:**

    | Parameter | In   | Type   | Required | Description   |
    | --------- | ---- | ------ | -------- | ------------- |
    | `uuid`    | path | string | ✅        | Location UUID |
  </Tab>
</Tabs>