For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
WebsiteStatusSupportDashboard
DocumentationAPI ReferenceMCPSDKsCLI (new)What's New?
DocumentationAPI ReferenceMCPSDKsCLI (new)What's New?
  • Assistants
    • GETList Assistants
    • POSTCreate Assistant
    • GETGet Assistant
    • DELDelete Assistant
    • PATCHUpdate Assistant
  • Squads
    • GETList Squads
    • POSTCreate Squad
    • GETGet Squad
    • DELDelete Squad
    • PATCHUpdate Squad
  • Calls
    • GETList Calls
    • POSTCreate Call
    • GETGet Call
    • DELDelete Call
    • PATCHUpdate Call
  • Chats
    • GETList Chats
    • POSTCreate Chat
    • GETGet Chat
    • DELDelete Chat
    • POSTCreate Chat (OpenAI Compatible)
  • Campaigns
    • GETList Campaigns
    • POSTCreate Campaign
    • GETGet Campaign
    • DELDelete Campaign
    • PATCHUpdate Campaign
  • Sessions
    • GETList Sessions
    • POSTCreate Session
    • GETGet Session
    • DELDelete Session
    • PATCHUpdate Session
  • Phone Numbers
    • GETList Phone Numbers
    • POSTCreate Phone Number
    • GETList Phone Numbers
    • GETGet Phone Number
    • DELDelete Phone Number
    • PATCHUpdate Phone Number
  • Tools
    • GETList Tools
    • POSTCreate Tool
    • GETGet Tool
    • DELDelete Tool
    • PATCHUpdate Tool
  • Files
    • GETList Files
    • POSTUpload File
    • GETGet File
    • DELDelete File
    • PATCHUpdate File
  • Structured Outputs
    • GETList Structured Outputs
    • POSTCreate Structured Output
    • GETGet Structured Output
    • DELDelete Structured Output
    • PATCHUpdate Structured Output
    • POSTRun Structured Output
  • Insight
    • GETGet Insights
    • POSTCreate Insight
    • GETGet Insight
    • DELDelete Insight
    • PATCHUpdate Insight
    • POSTRun Insight
    • POSTPreview Insight
  • Eval
    • GETList Evals
    • POSTCreate Eval
    • GETGet Eval
    • DELDelete Eval
    • PATCHUpdate Eval
    • GETGet Eval Run
    • DELDelete Eval Run
    • GETList Eval Runs
    • POSTCreate Eval Run
  • Observability Scorecard
    • GETGet Scorecard
    • DELDelete Scorecard
    • PATCHUpdate Scorecard
    • GETList Scorecards
    • POSTCreate Scorecard
  • Provider Resources
    • GETList Provider Resources
    • POSTCreate Provider Resource
    • GETGet Provider Resource
    • DELDelete Provider Resource
    • PATCHUpdate Provider Resource
  • Analytics
    • POSTCreate Analytics Queries
  • Webhooks
    • POSTServer Message
    • POSTClient Message
    • Swagger
    • OpenAPI
LogoLogo
WebsiteStatusSupportDashboard
Phone Numbers

List Phone Numbers

GET
https://api.vapi.ai/v2/phone-number
GET
/v2/phone-number
$curl https://api.vapi.ai/v2/phone-number \
>     -H "Authorization: Bearer <token>"
200Retrieved
1{
2  "results": [
3    {
4      "fallbackDestination": {
5        "message": "string",
6        "type": "number",
7        "numberE164CheckEnabled": true,
8        "number": "string",
9        "extension": "string",
10        "callerId": "string",
11        "transferPlan": {
12          "mode": "blind-transfer",
13          "message": "string",
14          "timeout": 60,
15          "sipVerb": "refer",
16          "dialTimeout": 60,
17          "holdAudioUrl": "string",
18          "transferCompleteAudioUrl": "string",
19          "contextEngineeringPlan": {
20            "type": "lastNMessages",
21            "maxMessages": 1.1
22          },
23          "twiml": "string",
24          "summaryPlan": {
25            "messages": [
26              {}
27            ],
28            "enabled": true,
29            "timeoutSeconds": 1.1
30          },
31          "sipHeadersInReferToEnabled": true,
32          "fallbackPlan": {
33            "message": "string",
34            "endCallEnabled": true
35          }
36        },
37        "description": "string"
38      },
39      "hooks": [
40        {
41          "on": "call.ringing",
42          "filters": [
43            {
44              "type": "startsWith",
45              "key": "number",
46              "startsWith": [
47                "91",
48                "86",
49                "7"
50              ]
51            }
52          ],
53          "do": [
54            {
55              "type": "transfer",
56              "destination": {
57                "message": "string",
58                "type": "number",
59                "numberE164CheckEnabled": true,
60                "number": "string",
61                "extension": "string",
62                "callerId": "string",
63                "transferPlan": {
64                  "mode": "blind-transfer",
65                  "message": {
66                    "contents": {},
67                    "type": {},
68                    "content": {}
69                  },
70                  "timeout": 60,
71                  "sipVerb": "refer",
72                  "dialTimeout": 60,
73                  "holdAudioUrl": "string",
74                  "transferCompleteAudioUrl": "string",
75                  "contextEngineeringPlan": {
76                    "type": {},
77                    "maxMessages": {}
78                  },
79                  "twiml": "string",
80                  "summaryPlan": {
81                    "messages": {},
82                    "enabled": {},
83                    "timeoutSeconds": {}
84                  },
85                  "sipHeadersInReferToEnabled": true,
86                  "fallbackPlan": {
87                    "message": {},
88                    "endCallEnabled": {}
89                  }
90                },
91                "description": "string"
92              }
93            }
94          ]
95        }
96      ],
97      "provider": "byo-phone-number",
98      "numberE164CheckEnabled": true,
99      "id": "string",
100      "orgId": "string",
101      "createdAt": "2024-01-15T09:30:00Z",
102      "updatedAt": "2024-01-15T09:30:00Z",
103      "status": "active",
104      "name": "string",
105      "assistantId": "string",
106      "workflowId": "string",
107      "squadId": "string",
108      "server": {
109        "timeoutSeconds": 20,
110        "credentialId": "550e8400-e29b-41d4-a716-446655440000",
111        "staticIpAddressesEnabled": false,
112        "encryptedPaths": [
113          "string"
114        ],
115        "url": "string",
116        "headers": {},
117        "backoffPlan": {
118          "type": "fixed",
119          "maxRetries": 0,
120          "baseDelaySeconds": 1,
121          "excludedStatusCodes": [
122            400,
123            401,
124            403,
125            404
126          ]
127        }
128      },
129      "number": "string",
130      "credentialId": "string"
131    }
132  ],
133  "metadata": {
134    "itemsPerPage": 1.1,
135    "totalItems": 1.1,
136    "currentPage": 1.1,
137    "itemsBeyondRetention": true,
138    "createdAtLe": "2024-01-15T09:30:00Z",
139    "createdAtGe": "2024-01-15T09:30:00Z"
140  }
141}
Was this page helpful?
Previous

Get Phone Number

Next
Built with

Authentication

AuthorizationBearer

Retrieve your API Key from Dashboard.

Query parameters

searchstringOptional<=100 characters

This will search phone numbers by name, number, or SIP URI (partial match, case-insensitive).

pagedoubleOptional>=1
This is the page number to return. Defaults to 1.
sortOrderenumOptional
This is the sort order for pagination. Defaults to 'DESC'.
Allowed values:
limitdoubleOptional0-1000
This is the maximum number of items to return. Defaults to 100.
createdAtGtdatetimeOptional
This will return items where the createdAt is greater than the specified value.
createdAtLtdatetimeOptional
This will return items where the createdAt is less than the specified value.
createdAtGedatetimeOptional
This will return items where the createdAt is greater than or equal to the specified value.
createdAtLedatetimeOptional
This will return items where the createdAt is less than or equal to the specified value.
updatedAtGtdatetimeOptional
This will return items where the updatedAt is greater than the specified value.
updatedAtLtdatetimeOptional
This will return items where the updatedAt is less than the specified value.
updatedAtGedatetimeOptional
This will return items where the updatedAt is greater than or equal to the specified value.
updatedAtLedatetimeOptional
This will return items where the updatedAt is less than or equal to the specified value.

Response

resultslist of objects
A list of phone numbers, which can be of any provider type.
metadataobject
Metadata about the pagination.