# Get Location

Retrieves the full details of a single location, including address, tender type settings, and current metadata.

#### Endpoint

`GET /Locations/{id}`

#### Path parameters

| Name | Type   | Required | Description                                             |
| ---- | ------ | -------- | ------------------------------------------------------- |
| `id` | string | Yes      | The `locationId` returned when the location was created |

#### Request headers

| Header          | Value                   |
| --------------- | ----------------------- |
| `Authorization` | `Bearer <access_token>` |
| `Accept`        | `application/json`      |

#### Example request

```bash
curl -X GET "https://api.test.devs.beadpay.io/Locations/loc_bfdc6a7f" \
     -H "Authorization: Bearer $TOKEN"
```

#### Successful response 200

```json
{
  "id": "loc_bfdc6a7f",
  "created": "2025-09-02T16:08:03.226Z",
  "updated": "2025-09-02T16:08:03.226Z",
  "merchantId": "mer_4e5a13aa",
  "name": "Downtown Flagship",
  "externalId": "store-001",
  "address": {
    "address1": "123 Main St",
    "address2": "Suite 200",
    "city": "Springfield",
    "region": "MA",
    "country": "US",
    "postalCode": "01109"
  },
  "businessType": "physical",
  "merchantCategoryCode": "5812",
  "additionalMerchantCategoryCodes": [],
  "descriptionOfServices": "Quick service restaurant",
  "grossAnnualVolume": 1200000,
  "highestMonthlyVolume": 150000,
  "averageTicketSize": 25.0,
  "maximumTicketSize": 2000.0,
  "contactPhone": "508-555-1234",
  "contactEmail": "ops@downtownflagship.com",
  "website": null,
  "tenderTypes": ["usdcBase", "ethereum"],
  "terminals": ["term_123", "term_456"]
}
```

#### Field reference

| Field                             | Description                                                                                           |
| --------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `id`                              | Unique `locationId`                                                                                   |
| `created`, `updated`              | ISO 8601 timestamps in UTC                                                                            |
| `merchantId`                      | Parent merchant identifier                                                                            |
| `name`                            | Friendly display name                                                                                 |
| `externalId`                      | Optional external reference used by your system                                                       |
| `address.*`                       | Full postal address object                                                                            |
| `businessType`                    | `physical` or `virtual`                                                                               |
| `merchantCategoryCode`            | Four digit MCC such as `5812`                                                                         |
| `additionalMerchantCategoryCodes` | Optional list of additional MCCs, can be empty                                                        |
| `descriptionOfServices`           | What the merchant sells or provides                                                                   |
| `grossAnnualVolume`               | Estimated annual processing volume                                                                    |
| `highestMonthlyVolume`            | Peak expected monthly volume if known                                                                 |
| `averageTicketSize`               | Typical transaction amount                                                                            |
| `maximumTicketSize`               | Maximum expected transaction amount                                                                   |
| `contactPhone`, `contactEmail`    | Primary contact details for the location                                                              |
| `website`                         | Required when `businessType` is `virtual`, otherwise optional                                         |
| `tenderTypes`                     | Enabled rails for this location                                                                       |
| `terminals`                       | Array of terminal identifiers under this location. For details, call `GET /Locations/{id}/terminals`. |

#### Error responses

| Code | Condition                                                    |
| ---- | ------------------------------------------------------------ |
| 401  | Missing or invalid token                                     |
| 403  | Authenticated but not permitted to view this location        |
| 404  | Location `id` does not exist or is not visible to your token |

#### Best practices

* Cache the response to avoid redundant calls when rendering dashboards
* Use the `updated` timestamp to decide when to refresh local copies
* If the terminal list is large, use `GET /Locations/{id}/terminals` for a paginated view

#### Related endpoints

* Update Location — `PUT /Locations/{id}`
* Delete Location — `DELETE /Locations/{id}`
* List Locations — `GET /Merchants/{id}/locations`


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.bead.xyz/entity-management/location-management/get-location.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.