> ## 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 Many organizations have multiple locations - for example, a franchise with different store locations, or a business with department-specific phone numbers. *** ## Base URL `https://answeringagent.com/api/v1` All requests must include the **X-API-KEY** header containing a valid API key. This is the Partner API. It accepts keys from reseller accounts only. A regular team's key gets `401`. To read your own team's conversations, tasks, contacts, and reports, use the [Customer API](/api/overview). *** ## 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 Filter locations by organization ID ### Example ```bash cURL theme={null} # List all locations curl -H "X-API-KEY: " \ https://answeringagent.com/api/v1/locations # List locations for specific organization curl -H "X-API-KEY: " \ https://answeringagent.com/api/v1/locations?organization_id=123 ``` ```javascript JavaScript theme={null} // List all locations const allRes = await fetch('https://answeringagent.com/api/v1/locations', { headers: { 'X-API-KEY': process.env.ANSWERING_AGENT_API_KEY }, }); if (!allRes.ok) throw new Error(`${allRes.status}: ${await allRes.text()}`); const locations = await allRes.json(); // List locations for specific organization const orgRes = await fetch('https://answeringagent.com/api/v1/locations?organization_id=123', { headers: { 'X-API-KEY': process.env.ANSWERING_AGENT_API_KEY }, }); if (!orgRes.ok) throw new Error(`${orgRes.status}: ${await orgRes.text()}`); const orgLocations = await orgRes.json(); ``` #### 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 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 ```bash cURL theme={null} # Using query parameter curl -X POST -H "X-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: " \ -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 ``` ```javascript JavaScript theme={null} // Using query parameter const queryRes = await fetch('https://answeringagent.com/api/v1/locations?organization_id=123', { method: 'POST', headers: { 'X-API-KEY': process.env.ANSWERING_AGENT_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ name: 'Downtown Office', address: '456 Elm Ave, Denver, CO', area_code: '303', google_place_id: 'ChIJrTLr-GyuEmsRBfy61i59si0', }), }); if (!queryRes.ok) throw new Error(`${queryRes.status}: ${await queryRes.text()}`); const queryLocation = await queryRes.json(); // Using body parameter const bodyRes = await fetch('https://answeringagent.com/api/v1/locations', { method: 'POST', headers: { 'X-API-KEY': process.env.ANSWERING_AGENT_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ name: 'Downtown Office', organization_id: 123, address: '456 Elm Ave, Denver, CO', area_code: '303', }), }); if (!bodyRes.ok) throw new Error(`${bodyRes.status}: ${await bodyRes.text()}`); const bodyLocation = await bodyRes.json(); ``` #### 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 cURL theme={null} curl -H "X-API-KEY: " \ https://answeringagent.com/api/v1/locations/890 ``` ```javascript JavaScript theme={null} const res = await fetch('https://answeringagent.com/api/v1/locations/890', { headers: { 'X-API-KEY': process.env.ANSWERING_AGENT_API_KEY }, }); if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`); const location = await res.json(); ``` #### 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 cURL theme={null} curl -X PATCH -H "X-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 ``` ```javascript JavaScript theme={null} const res = await fetch('https://answeringagent.com/api/v1/locations/890', { method: 'PATCH', headers: { 'X-API-KEY': process.env.ANSWERING_AGENT_API_KEY, 'Content-Type': 'application/json', }, body: JSON.stringify({ name: 'Downtown Office - Main', address: '456 Elm Ave N, Denver, CO' }), }); if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`); const location = await res.json(); ``` #### 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 cURL theme={null} curl -X DELETE -H "X-API-KEY: " \ https://answeringagent.com/api/v1/locations/890 ``` ```javascript JavaScript theme={null} const res = await fetch('https://answeringagent.com/api/v1/locations/890', { method: 'DELETE', headers: { 'X-API-KEY': process.env.ANSWERING_AGENT_API_KEY }, }); if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`); const { message } = await res.json(); ``` #### 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.