Skip to main content

​
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 & EndpointCapability
GET /locationsList all locations with optional organization filtering
POST /locationsCreate 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

PropertyValue
MethodGET
Endpoint/locations
Success200 OK
List all locations for the authenticated reseller, with optional organization filtering.

​
Query Parameters

​
organization_id
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

PropertyValue
MethodPOST
Endpoint/locations
Success201 Created
Create a new location for an organization.

​
Query Parameters

​
organization_id
integer
Organization to create the location for

​
Request Fields

FieldTypeRequiredNotes
namestring✔︎Display name for the business location
organization_idinteger✔︎*Organization ID (required via query param or body)
addressstring–Optional physical address
area_codestring–Optional area code hint for phone number provisioning
google_place_idstring–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

PropertyValue
MethodGET
Endpoint/locations/{location_id}
Success200 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

PropertyValue
MethodPATCH
Endpoint/locations/{location_id}
Success200 OK

​
Request Fields

FieldTypeRequiredNotes
namestring–Updated display name
addressstring–Updated physical address
google_place_idstring–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

PropertyValue
MethodDELETE
Endpoint/locations/{location_id}
Success200 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

CodeMeaningTypical Cause
401UnauthorizedMissing or invalid X-API-KEY
404Not FoundLocation or organization not found
422Validation ErrorMissing required fields or invalid data
500Internal Server ErrorPhone 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.