Phone numbers
Provision managed numbers, import SIP-trunk numbers, update routing, manage phone-number business verification, and verify your own numbers as caller IDs.
Authorization
bearerAuth In: header
Response Body
application/json
application/json
[
{
"id": "string",
"organizationId": "string",
"e164": "+12015551234",
"source": "managed",
"providerResourceId": "string",
"telnyxPhoneNumberId": "string",
"sipTrunkId": "string",
"sipConnectionInstallationId": "string",
"sipProviderName": "string",
"direction": "inbound",
"dispatchMetadataTemplate": {},
"agentId": "string",
"routeToBrokerId": "string",
"label": "string",
"callerName": "string",
"callerNameUpdatedAt": "2019-08-24T14:15:22Z",
"callerNameSupported": true,
"voicemailGreeting": "string",
"sms10dlcProfileId": "string",
"smsCampaignId": "string",
"smsAssignmentStatus": "string",
"smsAssignmentUpdatedAt": "2019-08-24T14:15:22Z",
"telnyxMessagingProfileId": "string",
"smsMessagingProfileStatus": "pending",
"smsMessagingProfileUpdatedAt": "2019-08-24T14:15:22Z",
"smsMessagingProfileError": "string",
"smsAutomationEnabled": true,
"setupStatus": {
"status": "ready",
"inboundReady": true,
"outboundReady": true,
"agentReady": true,
"forwardingRequired": true,
"forwardingSipUri": "string",
"sipConnectionReady": true,
"issues": [
"string"
]
},
"nextChargeAt": "2019-08-24T14:15:22Z",
"lastChargedAt": "2019-08-24T14:15:22Z",
"suspendedAt": "2019-08-24T14:15:22Z",
"billingSuspendedAt": "2019-08-24T14:15:22Z",
"complianceSuspendedAt": "2019-08-24T14:15:22Z",
"suspensionReason": "billing",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]{
"error": "Unauthorized",
"code": "UNAUTHORIZED"
}Authorization
bearerAuth In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
{
"id": "string",
"organizationId": "string",
"e164": "+12015551234",
"source": "managed",
"providerResourceId": "string",
"telnyxPhoneNumberId": "string",
"sipTrunkId": "string",
"sipConnectionInstallationId": "string",
"sipProviderName": "string",
"direction": "inbound",
"dispatchMetadataTemplate": {},
"agentId": "string",
"routeToBrokerId": "string",
"label": "string",
"callerName": "string",
"callerNameUpdatedAt": "2019-08-24T14:15:22Z",
"callerNameSupported": true,
"voicemailGreeting": "string",
"sms10dlcProfileId": "string",
"smsCampaignId": "string",
"smsAssignmentStatus": "string",
"smsAssignmentUpdatedAt": "2019-08-24T14:15:22Z",
"telnyxMessagingProfileId": "string",
"smsMessagingProfileStatus": "pending",
"smsMessagingProfileUpdatedAt": "2019-08-24T14:15:22Z",
"smsMessagingProfileError": "string",
"smsAutomationEnabled": true,
"setupStatus": {
"status": "ready",
"inboundReady": true,
"outboundReady": true,
"agentReady": true,
"forwardingRequired": true,
"forwardingSipUri": "string",
"sipConnectionReady": true,
"issues": [
"string"
]
},
"nextChargeAt": "2019-08-24T14:15:22Z",
"lastChargedAt": "2019-08-24T14:15:22Z",
"suspendedAt": "2019-08-24T14:15:22Z",
"billingSuspendedAt": "2019-08-24T14:15:22Z",
"complianceSuspendedAt": "2019-08-24T14:15:22Z",
"suspensionReason": "billing",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}{
"error": "Invalid request",
"code": "VALIDATION_ERROR",
"issues": [
{
"path": "to",
"message": "Required"
}
],
"retryable": false,
"docs_url": "https://docs.speko.dev/errors/validation_error"
}{
"error": "Unauthorized",
"code": "UNAUTHORIZED"
}{
"error": "Speko cannot sell this number: it is premium-rate, outside the US and Canada, or the carrier sends no price for it. Pick another from GET /v1/phone-numbers/available, or import it from your own carrier.",
"code": "PHONE_NUMBER_PRICE_NOT_SUPPORTED"
}Authorization
bearerAuth In: header
Query Parameters
US or CA. When omitted, a Canadian areaCode searches Canada and anything else searches the US.
"US" | "CA"^\d{3}$local (the default) or toll_free. A toll-free area code such as 833 searches toll-free numbers without it. Toll-free numbers are listed under the US.
"local" | "toll_free"Two-letter US state code (e.g. TX), or Canadian province code (e.g. ON) with country=CA.
^[A-Za-z]{2}$101 <= value <= 50Response Body
application/json
application/json
[
{
"e164": "+12015551234",
"friendlyName": "string",
"monthlyCostUsd": 0,
"upfrontCostUsd": 0,
"aboveStandardPrice": true,
"features": [
"string"
],
"region": {}
}
]{
"error": "Unauthorized",
"code": "UNAUTHORIZED"
}Authorization
bearerAuth In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
{
"id": "string",
"organizationId": "string",
"e164": "+12015551234",
"source": "managed",
"providerResourceId": "string",
"telnyxPhoneNumberId": "string",
"sipTrunkId": "string",
"sipConnectionInstallationId": "string",
"sipProviderName": "string",
"direction": "inbound",
"dispatchMetadataTemplate": {},
"agentId": "string",
"routeToBrokerId": "string",
"label": "string",
"callerName": "string",
"callerNameUpdatedAt": "2019-08-24T14:15:22Z",
"callerNameSupported": true,
"voicemailGreeting": "string",
"sms10dlcProfileId": "string",
"smsCampaignId": "string",
"smsAssignmentStatus": "string",
"smsAssignmentUpdatedAt": "2019-08-24T14:15:22Z",
"telnyxMessagingProfileId": "string",
"smsMessagingProfileStatus": "pending",
"smsMessagingProfileUpdatedAt": "2019-08-24T14:15:22Z",
"smsMessagingProfileError": "string",
"smsAutomationEnabled": true,
"setupStatus": {
"status": "ready",
"inboundReady": true,
"outboundReady": true,
"agentReady": true,
"forwardingRequired": true,
"forwardingSipUri": "string",
"sipConnectionReady": true,
"issues": [
"string"
]
},
"nextChargeAt": "2019-08-24T14:15:22Z",
"lastChargedAt": "2019-08-24T14:15:22Z",
"suspendedAt": "2019-08-24T14:15:22Z",
"billingSuspendedAt": "2019-08-24T14:15:22Z",
"complianceSuspendedAt": "2019-08-24T14:15:22Z",
"suspensionReason": "billing",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}{
"error": "Invalid request",
"code": "VALIDATION_ERROR",
"issues": [
{
"path": "to",
"message": "Required"
}
],
"retryable": false,
"docs_url": "https://docs.speko.dev/errors/validation_error"
}{
"error": "Unauthorized",
"code": "UNAUTHORIZED"
}Authorization
bearerAuth In: header
Response Body
application/json
application/json
{
"status": "missing",
"submission": {
"id": "string",
"organizationId": "string",
"status": "draft",
"businessProfile": {
"legalName": "string",
"displayName": "string",
"entityType": "string",
"country": "string",
"registrationId": "string",
"website": "http://example.com",
"address": {},
"useCase": "string",
"expectedUsage": "string"
},
"authorizedRepresentative": {
"name": "string",
"title": "string",
"email": "user@example.com",
"phone": "+12015551234"
},
"declaration": {
"businessName": "string",
"useCase": "string"
},
"attestor": {
"kind": "user",
"userId": "string",
"name": "string",
"email": "user@example.com",
"organizationRole": "string"
},
"attestationAccepted": true,
"attestationVersion": "string",
"attestationText": "string",
"termsVersion": "string",
"attestedAt": "2019-08-24T14:15:22Z",
"accessHoldAt": "2019-08-24T14:15:22Z",
"accessHoldReason": "rejected",
"submittedByUserId": "string",
"submittedByEmail": "user@example.com",
"submittedByApiKeyId": "string",
"submittedAt": "2019-08-24T14:15:22Z",
"reviewerUserId": "string",
"reviewerEmail": "user@example.com",
"reviewedAt": "2019-08-24T14:15:22Z",
"rejectionReason": "string",
"slackNotificationStatus": "not_queued",
"slackNotificationJobId": "string",
"slackNotificationError": "string",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
},
"declarationPrefill": {
"businessName": "string",
"useCase": "string"
},
"requiredAttestation": {
"version": "string",
"text": "string",
"termsVersion": "string",
"termsUrl": "http://example.com"
},
"attestationRequired": true,
"complianceAccess": "enabled",
"prefill": {
"businessProfile": {
"legalName": "string",
"displayName": "string",
"entityType": "string",
"country": "string",
"registrationId": "string",
"website": "http://example.com",
"address": {},
"useCase": "string",
"expectedUsage": "string"
},
"authorizedRepresentative": {
"name": "string",
"title": "string",
"email": "user@example.com",
"phone": "+12015551234"
}
}
}{
"error": "Unauthorized",
"code": "UNAUTHORIZED"
}Authorization
bearerAuth In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
{
"id": "string",
"organizationId": "string",
"status": "draft",
"businessProfile": {
"legalName": "string",
"displayName": "string",
"entityType": "string",
"country": "string",
"registrationId": "string",
"website": "http://example.com",
"address": {},
"useCase": "string",
"expectedUsage": "string"
},
"authorizedRepresentative": {
"name": "string",
"title": "string",
"email": "user@example.com",
"phone": "+12015551234"
},
"declaration": {
"businessName": "string",
"useCase": "string"
},
"attestor": {
"kind": "user",
"userId": "string",
"name": "string",
"email": "user@example.com",
"organizationRole": "string"
},
"attestationAccepted": true,
"attestationVersion": "string",
"attestationText": "string",
"termsVersion": "string",
"attestedAt": "2019-08-24T14:15:22Z",
"accessHoldAt": "2019-08-24T14:15:22Z",
"accessHoldReason": "rejected",
"submittedByUserId": "string",
"submittedByEmail": "user@example.com",
"submittedByApiKeyId": "string",
"submittedAt": "2019-08-24T14:15:22Z",
"reviewerUserId": "string",
"reviewerEmail": "user@example.com",
"reviewedAt": "2019-08-24T14:15:22Z",
"rejectionReason": "string",
"slackNotificationStatus": "not_queued",
"slackNotificationJobId": "string",
"slackNotificationError": "string",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}{
"error": "Invalid request",
"code": "VALIDATION_ERROR",
"issues": [
{
"path": "to",
"message": "Required"
}
],
"retryable": false,
"docs_url": "https://docs.speko.dev/errors/validation_error"
}{
"error": "Unauthorized",
"code": "UNAUTHORIZED"
}Authorization
bearerAuth In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
{
"id": "string",
"organizationId": "string",
"status": "draft",
"businessProfile": {
"legalName": "string",
"displayName": "string",
"entityType": "string",
"country": "string",
"registrationId": "string",
"website": "http://example.com",
"address": {},
"useCase": "string",
"expectedUsage": "string"
},
"authorizedRepresentative": {
"name": "string",
"title": "string",
"email": "user@example.com",
"phone": "+12015551234"
},
"declaration": {
"businessName": "string",
"useCase": "string"
},
"attestor": {
"kind": "user",
"userId": "string",
"name": "string",
"email": "user@example.com",
"organizationRole": "string"
},
"attestationAccepted": true,
"attestationVersion": "string",
"attestationText": "string",
"termsVersion": "string",
"attestedAt": "2019-08-24T14:15:22Z",
"accessHoldAt": "2019-08-24T14:15:22Z",
"accessHoldReason": "rejected",
"submittedByUserId": "string",
"submittedByEmail": "user@example.com",
"submittedByApiKeyId": "string",
"submittedAt": "2019-08-24T14:15:22Z",
"reviewerUserId": "string",
"reviewerEmail": "user@example.com",
"reviewedAt": "2019-08-24T14:15:22Z",
"rejectionReason": "string",
"slackNotificationStatus": "not_queued",
"slackNotificationJobId": "string",
"slackNotificationError": "string",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}{
"error": "Invalid request",
"code": "VALIDATION_ERROR",
"issues": [
{
"path": "to",
"message": "Required"
}
],
"retryable": false,
"docs_url": "https://docs.speko.dev/errors/validation_error"
}{
"error": "Unauthorized",
"code": "UNAUTHORIZED"
}{
"error": "string",
"code": "string",
"requiredAttestation": {
"version": "string",
"text": "string",
"termsVersion": "string",
"termsUrl": "http://example.com"
}
}Authorization
bearerAuth In: header
Path Parameters
Resource id.
Response Body
application/json
application/json
{
"id": "string",
"organizationId": "string",
"e164": "+12015551234",
"source": "managed",
"providerResourceId": "string",
"telnyxPhoneNumberId": "string",
"sipTrunkId": "string",
"sipConnectionInstallationId": "string",
"sipProviderName": "string",
"direction": "inbound",
"dispatchMetadataTemplate": {},
"agentId": "string",
"routeToBrokerId": "string",
"label": "string",
"callerName": "string",
"callerNameUpdatedAt": "2019-08-24T14:15:22Z",
"callerNameSupported": true,
"voicemailGreeting": "string",
"sms10dlcProfileId": "string",
"smsCampaignId": "string",
"smsAssignmentStatus": "string",
"smsAssignmentUpdatedAt": "2019-08-24T14:15:22Z",
"telnyxMessagingProfileId": "string",
"smsMessagingProfileStatus": "pending",
"smsMessagingProfileUpdatedAt": "2019-08-24T14:15:22Z",
"smsMessagingProfileError": "string",
"smsAutomationEnabled": true,
"setupStatus": {
"status": "ready",
"inboundReady": true,
"outboundReady": true,
"agentReady": true,
"forwardingRequired": true,
"forwardingSipUri": "string",
"sipConnectionReady": true,
"issues": [
"string"
]
},
"nextChargeAt": "2019-08-24T14:15:22Z",
"lastChargedAt": "2019-08-24T14:15:22Z",
"suspendedAt": "2019-08-24T14:15:22Z",
"billingSuspendedAt": "2019-08-24T14:15:22Z",
"complianceSuspendedAt": "2019-08-24T14:15:22Z",
"suspensionReason": "billing",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}{
"error": "Unauthorized",
"code": "UNAUTHORIZED"
}Authorization
bearerAuth In: header
Path Parameters
Resource id.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
{
"id": "string",
"organizationId": "string",
"e164": "+12015551234",
"source": "managed",
"providerResourceId": "string",
"telnyxPhoneNumberId": "string",
"sipTrunkId": "string",
"sipConnectionInstallationId": "string",
"sipProviderName": "string",
"direction": "inbound",
"dispatchMetadataTemplate": {},
"agentId": "string",
"routeToBrokerId": "string",
"label": "string",
"callerName": "string",
"callerNameUpdatedAt": "2019-08-24T14:15:22Z",
"callerNameSupported": true,
"voicemailGreeting": "string",
"sms10dlcProfileId": "string",
"smsCampaignId": "string",
"smsAssignmentStatus": "string",
"smsAssignmentUpdatedAt": "2019-08-24T14:15:22Z",
"telnyxMessagingProfileId": "string",
"smsMessagingProfileStatus": "pending",
"smsMessagingProfileUpdatedAt": "2019-08-24T14:15:22Z",
"smsMessagingProfileError": "string",
"smsAutomationEnabled": true,
"setupStatus": {
"status": "ready",
"inboundReady": true,
"outboundReady": true,
"agentReady": true,
"forwardingRequired": true,
"forwardingSipUri": "string",
"sipConnectionReady": true,
"issues": [
"string"
]
},
"nextChargeAt": "2019-08-24T14:15:22Z",
"lastChargedAt": "2019-08-24T14:15:22Z",
"suspendedAt": "2019-08-24T14:15:22Z",
"billingSuspendedAt": "2019-08-24T14:15:22Z",
"complianceSuspendedAt": "2019-08-24T14:15:22Z",
"suspensionReason": "billing",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}{
"error": "Invalid request",
"code": "VALIDATION_ERROR",
"issues": [
{
"path": "to",
"message": "Required"
}
],
"retryable": false,
"docs_url": "https://docs.speko.dev/errors/validation_error"
}{
"error": "Unauthorized",
"code": "UNAUTHORIZED"
}Authorization
bearerAuth In: header
Path Parameters
Resource id.
Response Body
application/json
application/json
{
"released": true
}{
"error": "Unauthorized",
"code": "UNAUTHORIZED"
}Authorization
bearerAuth In: header
Response Body
application/json
application/json
{
"verifiedCallerIds": [
{
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"phoneNumber": "+12015551234",
"status": "pending",
"method": "sms",
"verifiedAt": "2019-08-24T14:15:22Z",
"expiresAt": "2019-08-24T14:15:22Z",
"codeExpiresAt": "2019-08-24T14:15:22Z",
"createdAt": "2019-08-24T14:15:22Z"
}
]
}{
"error": "Unauthorized",
"code": "UNAUTHORIZED"
}Authorization
bearerAuth In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
{
"verifiedCallerId": {
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"phoneNumber": "+12015551234",
"status": "pending",
"method": "sms",
"verifiedAt": "2019-08-24T14:15:22Z",
"expiresAt": "2019-08-24T14:15:22Z",
"codeExpiresAt": "2019-08-24T14:15:22Z",
"createdAt": "2019-08-24T14:15:22Z"
},
"codeSent": true
}{
"verifiedCallerId": {
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"phoneNumber": "+12015551234",
"status": "pending",
"method": "sms",
"verifiedAt": "2019-08-24T14:15:22Z",
"expiresAt": "2019-08-24T14:15:22Z",
"codeExpiresAt": "2019-08-24T14:15:22Z",
"createdAt": "2019-08-24T14:15:22Z"
},
"codeSent": true
}{
"error": "Only US and Canadian numbers can be verified as caller IDs. Toll-free, premium-rate and non-geographic numbers cannot.",
"code": "VERIFIED_CALLER_ID_NUMBER_UNSUPPORTED"
}{
"error": "Unauthorized",
"code": "UNAUTHORIZED"
}{
"error": "Calling from your own number needs one paid top-up of any amount first. Free credit does not count.",
"code": "VERIFIED_CALLER_ID_PAYMENT_REQUIRED",
"topUpUrl": "https://platform.speko.dev/v1/public/top-up/eyJ..."
}{
"error": "Organization owner or admin required",
"code": "FORBIDDEN"
}{
"error": "This number is already a Speko phone line. Speko numbers are used as caller IDs without verification.",
"code": "VERIFIED_CALLER_ID_NUMBER_IN_USE"
}{
"error": "This number cannot receive a verification code. Check the number, or try the other method.",
"code": "VERIFIED_CALLER_ID_REQUEST_REFUSED"
}{
"error": "This workspace requested 5 verification codes in the last 24 hours. Try again later.",
"code": "VERIFIED_CALLER_ID_ORG_BUDGET"
}{
"error": "Phone verification is unavailable right now. Try again in a few minutes.",
"code": "VERIFIED_CALLER_ID_CARRIER_UNAVAILABLE"
}{
"error": "Verified caller IDs are not available right now.",
"code": "VERIFIED_CALLER_ID_UNAVAILABLE"
}Authorization
bearerAuth In: header
Path Parameters
Resource id.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
{
"verifiedCallerId": {
"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"phoneNumber": "+12015551234",
"status": "pending",
"method": "sms",
"verifiedAt": "2019-08-24T14:15:22Z",
"expiresAt": "2019-08-24T14:15:22Z",
"codeExpiresAt": "2019-08-24T14:15:22Z",
"createdAt": "2019-08-24T14:15:22Z"
}
}{
"error": "Invalid request",
"code": "VALIDATION_ERROR",
"issues": [
{
"path": "to",
"message": "Required"
}
],
"retryable": false,
"docs_url": "https://docs.speko.dev/errors/validation_error"
}{
"error": "Unauthorized",
"code": "UNAUTHORIZED"
}{
"error": "Organization owner or admin required",
"code": "FORBIDDEN"
}{
"error": "Verified caller ID not found.",
"code": "VERIFIED_CALLER_ID_NOT_FOUND"
}{
"error": "This code is no longer accepted. Request a new code.",
"code": "VERIFIED_CALLER_ID_CODE_EXPIRED"
}{
"error": "That code is not right. 4 tries left before a new code is needed.",
"code": "VERIFIED_CALLER_ID_CODE_INVALID"
}{
"error": "Too many wrong codes. Request a new code.",
"code": "VERIFIED_CALLER_ID_TOO_MANY_ATTEMPTS"
}{
"error": "The number was verified but could not be set up for calls yet. Confirm again to finish; no new code is needed.",
"code": "VERIFIED_CALLER_ID_SETUP_FAILED"
}{
"error": "Verified caller IDs are not available right now.",
"code": "VERIFIED_CALLER_ID_UNAVAILABLE"
}Authorization
bearerAuth In: header
Path Parameters
Resource id.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
{
"released": true
}{
"error": "Unauthorized",
"code": "UNAUTHORIZED"
}{
"error": "Organization owner or admin required",
"code": "FORBIDDEN"
}{
"error": "Verified caller ID not found.",
"code": "VERIFIED_CALLER_ID_NOT_FOUND"
}{
"error": "Calls no longer use this caller ID, but removing it did not finish. Try again in a few minutes.",
"code": "VERIFIED_CALLER_ID_RELEASE_FAILED"
}{
"error": "Verified caller IDs are not available right now.",
"code": "VERIFIED_CALLER_ID_UNAVAILABLE"
}