AgentPhone numbers API
The numbers API from AgentPhone — 3 operation(s) for numbers.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/agentphone-numbers-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Reference agent-webhooks Numbers API
version: 1.0.0
servers:
- url: https://api.agentphone.ai
description: Production
tags:
- name: numbers
paths:
/v1/numbers:
get:
operationId: list-numbers-v-1-numbers-get
summary: List Numbers
description: 'List the active phone numbers for this account.
Released (deleted) numbers are excluded so the count reflects the numbers
the account actually holds. Fetch a single number via GET /{number_id}
(which returns it regardless of status).'
tags:
- numbers
parameters:
- name: offset
in: query
required: false
schema:
type: integer
default: 0
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
- name: X-Sub-Account-Id
in: header
description: Target a sub-account. Pass a sub-account ID to scope this request. Omit to use the master account.
required: false
schema:
type: string
default: 20
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/PhoneNumberListResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
post:
operationId: create-number-v-1-numbers-post
summary: Create Number
description: 'Provision a new SMS-enabled phone number.
1. Check number limit (lifetime limit)
2. Search the account''s configured SMS provider for available numbers
3. Purchase the first available one
4. Configure messaging and voice routing
5. Store the number in our database'
tags:
- numbers
parameters:
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
- name: X-Sub-Account-Id
in: header
description: Target a sub-account. Pass a sub-account ID to scope this request. Omit to use the master account.
required: false
schema:
type: string
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/PhoneNumberResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateNumberRequest'
/v1/numbers/{number_id}:
get:
operationId: get-number-v-1-numbers-number-id-get
summary: Get Number
description: 'Get a single phone number owned by this account.
Returns the number regardless of status (including released) so detail
pages still load for numbers that are no longer active.'
tags:
- numbers
parameters:
- name: number_id
in: path
required: true
schema:
type: string
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/PhoneNumberResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
delete:
operationId: delete-number-v-1-numbers-number-id-delete
summary: Delete Number
description: 'Release (delete) a phone number.
This will:
1. Release the number from its upstream provider when supported
2. Mark the number as "released" in the database
3. Keep all messages and conversation history (for audit purposes)
WARNING: This action is irreversible! The number cannot be recovered.'
tags:
- numbers
parameters:
- name: number_id
in: path
required: true
schema:
type: string
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
- name: X-Sub-Account-Id
in: header
description: Target a sub-account. Pass a sub-account ID to scope this request. Omit to use the master account.
required: false
schema:
type: string
responses:
'200':
description: Successful Response
content:
application/json:
schema:
description: Any type
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/v1/numbers/{number_id}/messages:
get:
operationId: get-messages-v-1-numbers-number-id-messages-get
summary: Get Messages
description: 'Get messages for a specific phone number.
Supports cursor-based pagination via before/after timestamps.'
tags:
- numbers
parameters:
- name: number_id
in: path
required: true
schema:
type: string
- name: limit
in: query
required: false
schema:
type: integer
default: 50
- name: before
in: query
required: false
schema:
type:
- string
- 'null'
format: date-time
- name: after
in: query
required: false
schema:
type:
- string
- 'null'
format: date-time
- name: Authorization
in: header
description: Bearer authentication
required: true
schema:
type: string
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/MessageListResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
MessageListResponse:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/MessageResponse'
hasMore:
type: boolean
required:
- data
- hasMore
title: MessageListResponse
ValidationError:
type: object
properties:
loc:
type: array
items:
$ref: '#/components/schemas/ValidationErrorLocItems'
msg:
type: string
type:
type: string
required:
- loc
- msg
- type
title: ValidationError
PhoneNumberListResponse:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/PhoneNumberResponse'
hasMore:
type: boolean
total:
type: integer
required:
- data
- hasMore
- total
title: PhoneNumberListResponse
PhoneNumberResponse:
type: object
properties:
id:
type: string
phoneNumber:
type: string
country:
type: string
status:
type: string
type:
type: string
default: sms
agentId:
type:
- string
- 'null'
createdAt:
type: string
format: date-time
required:
- id
- phoneNumber
- country
- status
- createdAt
title: PhoneNumberResponse
MessageResponse:
type: object
properties:
id:
type: string
from_:
type: string
to:
type: string
body:
type: string
direction:
type: string
channel:
type:
- string
- 'null'
receivedAt:
type: string
format: date-time
required:
- id
- from_
- to
- body
- direction
- receivedAt
title: MessageResponse
ValidationErrorLocItems:
oneOf:
- type: string
- type: integer
title: ValidationErrorLocItems
HTTPValidationError:
type: object
properties:
detail:
type: array
items:
$ref: '#/components/schemas/ValidationError'
title: HTTPValidationError
CreateNumberRequest:
type: object
properties:
country:
type: string
default: US
areaCode:
type:
- string
- 'null'
agentId:
type:
- string
- 'null'
title: CreateNumberRequest
securitySchemes:
HTTPBearer:
type: http
scheme: bearer