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

# Locations

> Manage phone numbers and locations for customer organizations.

## Overview

Locations represent phone numbers with AI answering agents. Each location:

* Belongs to an organization
* Has its own phone number (auto-provisioned when you provide an area code)
* Receives and processes calls independently
* Can be customized with unique AI settings

<Tip>
  Many organizations have multiple locations - for example, a franchise with different store locations, or a business with department-specific phone numbers.
</Tip>

***

## Base URL

**Playground**: `https://playground.answeringagent.com/api/v1`
**Production**: `https://answeringagent.com/api/v1`

All requests must include the **X-API-KEY** header containing a valid API key.

***

## Resource Structure

The Locations API uses a **flat structure** for easy management across all your customer organizations:

| Method & Endpoint                 | Capability                                              |
| --------------------------------- | ------------------------------------------------------- |
| `GET /locations`                  | List all locations with optional organization filtering |
| `POST /locations`                 | Create a new location for an organization               |
| `GET /locations/{location_id}`    | Get details for a specific location                     |
| `PATCH /locations/{location_id}`  | Update a location                                       |
| `DELETE /locations/{location_id}` | Delete a location                                       |

***

## 1. List Locations

| Property     | Value        |
| ------------ | ------------ |
| **Method**   | `GET`        |
| **Endpoint** | `/locations` |
| **Success**  | `200 OK`     |

List all locations for the authenticated reseller, with optional organization filtering.

### Query Parameters

<ParamField query="organization_id" type="integer" optional>
  Filter locations by organization ID
</ParamField>

### Example

```bash theme={null}
# List all locations
curl -H "X-API-KEY: <your-api-key>" \
     https://answeringagent.com/api/v1/locations

# List locations for specific organization
curl -H "X-API-KEY: <your-api-key>" \
     https://answeringagent.com/api/v1/locations?organization_id=123
```

#### Success Response

```json theme={null}
200 OK
[
  {
    "id": 889,
    "name": "Main St Location",
    "phone_number": "+13035551234",
    "status": "active",
    "address": "123 Main St, Denver, CO",
    "google_place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4",
    "created_at": "2025-05-14T15:30:00Z",
    "updated_at": "2025-05-14T15:30:00Z"
  }
]
```

***

## 2. Create Location

| Property     | Value         |
| ------------ | ------------- |
| **Method**   | `POST`        |
| **Endpoint** | `/locations`  |
| **Success**  | `201 Created` |

Create a new location for an organization.

### Query Parameters

<ParamField query="organization_id" type="integer" optional>
  Organization to create the location for
</ParamField>

### Request Fields

| Field             | Type    | Required | Notes                                                 |
| ----------------- | ------- | -------- | ----------------------------------------------------- |
| `name`            | string  | ✔︎       | Display name for the business location                |
| `organization_id` | integer | ✔︎\*     | Organization ID (required via query param or body)    |
| `address`         | string  | –        | Optional physical address                             |
| `area_code`       | string  | –        | Optional area code hint for phone number provisioning |
| `google_place_id` | string  | –        | Optional Google Place ID for mapping integration      |

<Note>
  Either `organization_id` query parameter or `organization_id` in request body is required.
</Note>

### Example

```bash theme={null}
# Using query parameter
curl -X POST -H "X-API-KEY: <your-api-key>" \
     -H "Content-Type: application/json" \
     -d '{
           "name": "Downtown Office",
           "address": "456 Elm Ave, Denver, CO",
           "area_code": "303",
           "google_place_id": "ChIJrTLr-GyuEmsRBfy61i59si0"
         }' \
     "https://answeringagent.com/api/v1/locations?organization_id=123"

# Using body parameter
curl -X POST -H "X-API-KEY: <your-api-key>" \
     -H "Content-Type: application/json" \
     -d '{
           "name": "Downtown Office",
           "organization_id": 123,
           "address": "456 Elm Ave, Denver, CO",
           "area_code": "303"
         }' \
     https://answeringagent.com/api/v1/locations
```

#### Success Response

```json theme={null}
201 Created
{
  "location": {
    "id": 890,
    "name": "Downtown Office",
    "phone_number": "+13035559876", // Auto-provisioned if area_code provided
    "status": "active",             // or "pending" if no area_code
    "address": "456 Elm Ave, Denver, CO",
    "google_place_id": "ChIJrTLr-GyuEmsRBfy61i59si0",
    "created_at": "2025-05-14T16:10:00Z",
    "updated_at": "2025-05-14T16:10:00Z"
  }
}
```

***

## 3. Get Location

| Property     | Value                      |
| ------------ | -------------------------- |
| **Method**   | `GET`                      |
| **Endpoint** | `/locations/{location_id}` |
| **Success**  | `200 OK`                   |

### Example

```bash theme={null}
curl -H "X-API-KEY: <your-api-key>" \
     https://answeringagent.com/api/v1/locations/890
```

#### Success Response

```json theme={null}
200 OK
{
  "id": 890,
  "name": "Downtown Office",
  "phone_number": "+13035559876",
  "status": "active",
  "address": "456 Elm Ave, Denver, CO",
  "google_place_id": "ChIJrTLr-GyuEmsRBfy61i59si0",
  "created_at": "2025-05-14T16:10:00Z",
  "updated_at": "2025-05-14T16:10:00Z"
}
```

***

## 4. Update Location

| Property     | Value                      |
| ------------ | -------------------------- |
| **Method**   | `PATCH`                    |
| **Endpoint** | `/locations/{location_id}` |
| **Success**  | `200 OK`                   |

### Request Fields

| Field             | Type   | Required | Notes                    |
| ----------------- | ------ | -------- | ------------------------ |
| `name`            | string | –        | Updated display name     |
| `address`         | string | –        | Updated physical address |
| `google_place_id` | string | –        | Updated Google Place ID  |

### Example

```bash theme={null}
curl -X PATCH -H "X-API-KEY: <your-api-key>" \
     -H "Content-Type: application/json" \
     -d '{
           "name": "Downtown Office - Main",
           "address": "456 Elm Ave N, Denver, CO"
         }' \
     https://answeringagent.com/api/v1/locations/890
```

#### Success Response

```json theme={null}
200 OK
{
  "id": 890,
  "name": "Downtown Office - Main",
  "phone_number": "+13035559876",
  "status": "active",
  "address": "456 Elm Ave N, Denver, CO",
  "google_place_id": "ChIJrTLr-GyuEmsRBfy61i59si0",
  "created_at": "2025-05-14T16:10:00Z",
  "updated_at": "2025-05-14T16:15:00Z"
}
```

***

## 5. Delete Location

| Property     | Value                      |
| ------------ | -------------------------- |
| **Method**   | `DELETE`                   |
| **Endpoint** | `/locations/{location_id}` |
| **Success**  | `200 OK`                   |

### Example

```bash theme={null}
curl -X DELETE -H "X-API-KEY: <your-api-key>" \
     https://answeringagent.com/api/v1/locations/890
```

#### Success Response

```json theme={null}
200 OK
{
  "message": "Location deleted successfully"
}
```

***

## Phone Number Provisioning

When creating a location:

* **With `area_code`**: System attempts to auto-provision a phone number from Twilio
* **Without `area_code`**: Location created with `status: "pending"`, phone number can be assigned later
* **Status**: `"active"` when phone number assigned, `"pending"` when awaiting assignment

***

## Error Codes

| Code | Meaning               | Typical Cause                             |
| ---- | --------------------- | ----------------------------------------- |
| 401  | Unauthorized          | Missing or invalid `X-API-KEY`            |
| 404  | Not Found             | Location or organization not found        |
| 422  | Validation Error      | Missing required fields or invalid data   |
| 500  | Internal Server Error | Phone number provisioning or system error |

***

## Migration from Legacy API

If migrating from the nested `/users/{external_id}/locations` endpoints:

* **Old**: `GET /users/{external_id}/locations`

* **New**: `GET /locations?organization_id={org_id}`

* **Old**: `POST /users/{external_id}/locations`

* **New**: `POST /locations?organization_id={org_id}`

The flat structure provides better performance and cleaner resource management across all your customers.