Roark Phone Number API
The Phone Number API from Roark — 4 operation(s) for phone number.
The Phone Number API from Roark — 4 operation(s) for phone number.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
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.curl "https://apis.io/api/v1/apis/roark:roark-phone-number-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a 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: 3.2.0
info:
title: Roark Analytics Phone Number API
description: The Roark Analytics API gives you access to the same API that powers the award winning Roark Analytics platform.
version: 1.0.0
servers:
- description: Production
url: https://api.roark.ai
security:
- Bearer: []
tags:
- name: Phone Number
paths:
/v1/phone-number:
get:
responses:
'200':
description: The phone numbers the project owns
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/PhoneNumberResponse'
required:
- data
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Validation error
example:
type: validation
code: invalid_parameter
message: The request was invalid
param: email
description: Bad Request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Authentication error
example:
type: authentication
code: unauthorized
message: Authentication required
description: Unauthorized
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Permission error
example:
type: forbidden
code: permission_denied
message: You do not have permission to access this resource
description: Forbidden
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Server error
example:
type: internal
code: internal_error
message: Internal server error
description: Internal Server Error
operationId: getV1Phone-number
tags:
- Phone Number
summary: List phone numbers
description: Returns the phone numbers the project owns, oldest first, with the agent each is assigned to.
parameters:
- in: query
name: agentId
schema:
type: string
format: uuid
description: Only the numbers assigned to this agent
post:
responses:
'201':
description: The purchased phone number
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/PhoneNumberResponse'
required:
- data
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Validation error
example:
type: validation
code: invalid_parameter
message: The request was invalid
param: email
description: Bad Request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Authentication error
example:
type: authentication
code: unauthorized
message: Authentication required
description: Unauthorized
'402':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Insufficient credit
example:
type: payment_required
code: insufficient_credits
message: Not enough credit to start this work. Add credit and try again.
description: Payment Required
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Permission error
example:
type: forbidden
code: permission_denied
message: You do not have permission to access this resource
description: Forbidden
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Not found error
example:
type: not_found
code: resource_not_found
message: The requested resource could not be found
description: Not Found
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Conflict error
example:
type: conflict
code: resource_in_use
message: The resource is in use and cannot be deleted
description: Conflict
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Server error
example:
type: internal
code: internal_error
message: Internal server error
description: Internal Server Error
operationId: postV1Phone-number
tags:
- Phone Number
summary: Buy a phone number
description: 'Buys a number from the carrier for this project: the one named by e164, or one Roark picks to match autoPick (trying the next match if the carrier has just sold one). Free inside the plan allowance; past it, the first month of rent is charged now and monthly after that.'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePhoneNumberInput'
/v1/phone-number/available:
get:
responses:
'200':
description: Numbers available to buy
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/AvailablePhoneNumberResponse'
required:
- data
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Validation error
example:
type: validation
code: invalid_parameter
message: The request was invalid
param: email
description: Bad Request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Authentication error
example:
type: authentication
code: unauthorized
message: Authentication required
description: Unauthorized
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Permission error
example:
type: forbidden
code: permission_denied
message: You do not have permission to access this resource
description: Forbidden
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Server error
example:
type: internal
code: internal_error
message: Internal server error
description: Internal Server Error
operationId: getV1Phone-numberAvailable
tags:
- Phone Number
summary: Search available phone numbers
description: Returns US or Canadian numbers the carrier has for sale, local or toll-free, narrowed by area code or by digits the number must contain. When an area code has no numbers, nearby ones are returned flagged bestEffort; an empty list means nothing matched. Buy one with POST /v1/phone-number, or let Roark pick with autoPick.
parameters:
- in: query
name: country
schema:
type: string
enum:
- US
- CA
description: 'ISO 3166-1 alpha-2 country of the number: US or CA'
example: US
default: US
- in: query
name: numberType
schema:
type: string
enum:
- LOCAL
- TOLL_FREE
description: LOCAL for a number in an area code, TOLL_FREE for one from the shared US and Canada toll-free pool
example: LOCAL
default: LOCAL
- in: query
name: areaCode
schema:
type: string
pattern: ^\d{3}$
description: Three-digit area code, or a toll-free prefix such as 800. When it has no numbers, nearby ones are returned instead, flagged bestEffort.
example: '415'
- in: query
name: contains
schema:
type: string
pattern: ^[0-9A-Za-z*]{1,7}$
description: Digits or letters the number must contain (1 to 7, * matches any digit)
example: '555'
- in: query
name: limit
schema:
type: integer
minimum: 1
maximum: 100
default: 20
description: 'Maximum number of results (default: 20, max: 100)'
/v1/phone-number/allowance:
get:
responses:
'200':
description: The phone number allowance
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/PhoneNumberAllowanceResponse'
required:
- data
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Authentication error
example:
type: authentication
code: unauthorized
message: Authentication required
description: Unauthorized
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Permission error
example:
type: forbidden
code: permission_denied
message: You do not have permission to access this resource
description: Forbidden
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Server error
example:
type: internal
code: internal_error
message: Internal server error
description: Internal Server Error
operationId: getV1Phone-numberAllowance
tags:
- Phone Number
summary: Get the phone number allowance
description: Returns how many numbers the organization gets for free, how many it holds, what a paid number costs a month, and whether a purchase would be admitted right now.
/v1/phone-number/{phoneNumberId}:
put:
responses:
'200':
description: The updated phone number
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/PhoneNumberResponse'
required:
- data
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Validation error
example:
type: validation
code: invalid_parameter
message: The request was invalid
param: email
description: Bad Request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Authentication error
example:
type: authentication
code: unauthorized
message: Authentication required
description: Unauthorized
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Permission error
example:
type: forbidden
code: permission_denied
message: You do not have permission to access this resource
description: Forbidden
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Not found error
example:
type: not_found
code: resource_not_found
message: The requested resource could not be found
description: Not Found
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Server error
example:
type: internal
code: internal_error
message: Internal server error
description: Internal Server Error
operationId: putV1Phone-numberByPhoneNumberId
tags:
- Phone Number
summary: Update a phone number
description: Relabels a number or changes which agent it is assigned to. A field left out is untouched; null clears it.
parameters:
- in: path
name: phoneNumberId
schema:
type: string
format: uuid
description: Phone number ID
required: true
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdatePhoneNumberInput'
delete:
responses:
'200':
description: The number was released
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/ReleasePhoneNumberResponse'
required:
- data
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Validation error
example:
type: validation
code: invalid_parameter
message: The request was invalid
param: email
description: Bad Request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Authentication error
example:
type: authentication
code: unauthorized
message: Authentication required
description: Unauthorized
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Permission error
example:
type: forbidden
code: permission_denied
message: You do not have permission to access this resource
description: Forbidden
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Not found error
example:
type: not_found
code: resource_not_found
message: The requested resource could not be found
description: Not Found
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Server error
example:
type: internal
code: internal_error
message: Internal server error
description: Internal Server Error
operationId: deleteV1Phone-numberByPhoneNumberId
tags:
- Phone Number
summary: Release a phone number
description: 'Gives the number back to the carrier. This cannot be undone: rent stops today and nothing is refunded.'
parameters:
- in: path
name: phoneNumberId
schema:
type: string
format: uuid
description: Phone number ID
required: true
components:
schemas:
UpdatePhoneNumberInput:
type: object
properties:
name:
type:
- string
- 'null'
minLength: 1
maxLength: 80
description: New label; null clears it, omit to leave it alone
agentId:
type:
- string
- 'null'
format: uuid
description: Agent to assign the number to; null unassigns, omit to leave it alone
description: Input for relabelling or reassigning a phone number
PhoneNumberAllowanceResponse:
type: object
properties:
plan:
type: string
enum:
- PAYG
- TEAM
- ENTERPRISE
description: The billing plan the allowance comes from
freeLimit:
type: integer
description: Numbers included at no charge
used:
type: integer
description: Numbers the organization holds right now
paidCount:
type: integer
description: How many of those sit outside the free allowance
monthlyRentMicros:
type: integer
description: What one paid number costs a month, in micro-dollars
nextIsFree:
type: boolean
description: Whether the next number would be free
canPurchase:
type: boolean
description: Whether a purchase would be admitted right now
blockedReason:
type:
- string
- 'null'
enum:
- PAYMENT_METHOD_REQUIRED
- INSUFFICIENT_CREDITS
- SPEND_CAP_REACHED
- PLAN_LIMIT_REACHED
description: Why a purchase would be refused; null when canPurchase is true
isOverridden:
type: boolean
description: True when the free allowance comes from a per-organization override
required:
- plan
- freeLimit
- used
- paidCount
- monthlyRentMicros
- nextIsFree
- canPurchase
- blockedReason
- isOverridden
description: How many numbers the organization gets for free and whether it may buy the next one
PhoneNumberAutoPickInput:
type: object
properties:
country:
type: string
enum:
- US
- CA
description: 'ISO 3166-1 alpha-2 country of the number: US or CA'
example: US
default: US
numberType:
type: string
enum:
- LOCAL
- TOLL_FREE
description: LOCAL for a number in an area code, TOLL_FREE for one from the shared US and Canada toll-free pool
example: LOCAL
default: LOCAL
areaCode:
type: string
pattern: ^\d{3}$
description: Three-digit area code, or a toll-free prefix such as 800. When it has no numbers, nearby ones are returned instead, flagged bestEffort.
example: '415'
contains:
type: string
pattern: ^[0-9A-Za-z*]{1,7}$
description: Digits or letters the number must contain (1 to 7, * matches any digit)
example: '555'
description: What the number Roark picks should look like. Roark buys the first matching number the carrier will sell, preferring the area code and falling back to a nearby one.
ErrorResponse:
type: object
properties:
type:
type: string
enum:
- validation
- authentication
- forbidden
- not_found
- conflict
- payment_required
- rate_limit
- internal
description: The error type category
examples:
- validation
- authentication
code:
type: string
description: Machine-readable error code identifier
examples:
- invalid_parameter
- missing_required_field
- unauthorized
message:
type: string
description: Human-readable error message
examples:
- The request was invalid
- Authentication required
param:
type: string
description: The parameter that caused the error (if applicable)
examples:
- email
- user_id
details:
description: Additional error context information
required:
- type
- code
- message
CreatePhoneNumberInput:
type: object
properties:
e164:
type: string
pattern: ^\+[1-9]\d{1,14}$
description: The number to buy, in E.164 format, from a search result. Give this or autoPick.
example: '+14155550123'
autoPick:
$ref: '#/components/schemas/PhoneNumberAutoPickInput'
description: Let Roark pick a matching number instead of naming one. Give this or e164.
country:
type: string
enum:
- US
- CA
description: 'The country of the number given by e164 (default: US). An auto-picked number uses autoPick.country.'
example: US
name:
type: string
minLength: 1
maxLength: 80
description: A label for the number
agentId:
type: string
format: uuid
description: The agent to assign the number to
expectFree:
type: boolean
description: Whether you expect this number to be free (from the allowance). The purchase is refused with 409 if that has changed since you checked.
expectMonthlyRentMicros:
type: integer
minimum: 0
description: The monthly rent you expect for a paid number, in micros (from the allowance). The purchase is refused with 409 if that has changed since you checked.
example: 2000000
description: Input for buying a phone number
ReleasePhoneNumberResponse:
type: object
properties:
id:
type: string
format: uuid
description: Phone number ID
released:
type: boolean
const: true
description: Always true; the number is gone and rent has stopped
required:
- id
- released
description: Confirmation that a phone number was released
PhoneNumberResponse:
type: object
properties:
id:
type: string
format: uuid
description: Phone number ID
e164:
type: string
description: The number in E.164 format
example: '+14155550123'
name:
type:
- string
- 'null'
description: Label the project gave the number
localityCode:
type:
- string
- 'null'
description: ISO 3166-2 code of the region the number is from, when the carrier gave one
purchasedAt:
type: string
description: When the number was bought (ISO 8601)
rentNextChargeAt:
type: string
description: When the next month of rent is due (ISO 8601)
isFree:
type: boolean
description: Whether the number sits inside the plan free allowance right now
monthlyRentMicros:
type: integer
description: What a month of this number costs in micro-dollars; 0 while it is free
agentId:
type:
- string
- 'null'
format: uuid
description: The agent the number is assigned to, if any
required:
- id
- e164
- name
- localityCode
- purchasedAt
- rentNextChargeAt
- isFree
- monthlyRentMicros
- agentId
description: A phone number the project owns
AvailablePhoneNumberResponse:
type: object
properties:
e164:
type: string
description: The number in E.164 format
example: '+14155550123'
region:
type:
- string
- 'null'
description: Region the carrier lists, e.g. a state code
locality:
type:
- string
- 'null'
description: Locality the carrier lists, e.g. a city
bestEffort:
type: boolean
description: True when the area code asked for had no numbers and the carrier offered this nearby one instead
required:
- e164
- region
- locality
- bestEffort
description: A number the carrier has for sale
securitySchemes:
Bearer:
type: http
scheme: bearer
bearerFormat: JWT