Locations

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

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

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

integer

Filter locations by organization ID

Example

# 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

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

integer

Organization to create the location for

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

Either organization_id query parameter or organization_id in request body is required.

Example

# 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

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

curl -H "X-API-KEY: <your-api-key>" \
     https://answeringagent.com/api/v1/locations/890

Success Response

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

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

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

curl -X DELETE -H "X-API-KEY: <your-api-key>" \
     https://answeringagent.com/api/v1/locations/890

Success Response

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.

Getting Started

Guides

POS Integrations

API Reference

API Playground

Overview

Base URL

Resource Structure

1. List Locations

Query Parameters

Example

Success Response

2. Create Location

Query Parameters

Request Fields

Example

Success Response

3. Get Location

Example

Success Response

4. Update Location

Request Fields

Example

Success Response

5. Delete Location

Example

Success Response

Phone Number Provisioning

Error Codes

Migration from Legacy API

​Overview

​Base URL

​Resource Structure

​1. List Locations

​Query Parameters

​Example

​Success Response

​2. Create Location

​Query Parameters

​Request Fields

​Example

​Success Response

​3. Get Location

​Example

​Success Response

​4. Update Location

​Request Fields

​Example

​Success Response

​5. Delete Location

​Example

​Success Response

​Phone Number Provisioning

​Error Codes

​Migration from Legacy API

Overview

Base URL

Resource Structure

1. List Locations

Query Parameters

Example

Success Response

2. Create Location

Query Parameters

Request Fields

Example

Success Response

3. Get Location

Example

Success Response

4. Update Location

Request Fields

Example

Success Response

5. Delete Location

Example

Success Response

Phone Number Provisioning

Error Codes

Migration from Legacy API