{ "openapi": "3.1.0", "info": { "title": "Phone numbers", "version": "2026-10-09", "description": "Find, buy, and release US local and toll-free phone numbers for texting. Every number costs $1.60 a month. Authenticate with a secret API key in `Authorization: Bearer ...`. Send `Motor-Mode: test` to use fictional numbers for free." }, "servers": [ { "url": "https://api.motor.dev/phone_numbers" } ], "security": [ { "bearer": [] } ], "tags": [ { "name": "Search" }, { "name": "Numbers" } ], "paths": { "/available_numbers": { "get": { "operationId": "searchAvailableNumbers", "tags": [ "Search" ], "summary": "Search available numbers", "description": "Returns matching numbers. Results aren't paginated or reserved. Refine the filters to change the results. No matches returns an empty list with `200`. The default limit is 10 searches per second, per team and mode.", "parameters": [ { "name": "type", "in": "query", "required": false, "description": "`local` (the default) or `toll_free`.", "schema": { "type": "string", "enum": [ "local", "toll_free" ] } }, { "name": "area_code", "in": "query", "required": false, "description": "Three digits. For toll-free numbers, the prefix: 833, 844, 855, 866, 877, or 888. Motor doesn't sell 800 numbers.", "schema": { "type": "string" } }, { "name": "region", "in": "query", "required": false, "description": "The two-letter code of a US state or DC. Local numbers only.", "schema": { "type": "string" } }, { "name": "contains", "in": "query", "required": false, "description": "1 to 10 digits that the number must contain.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "From 1 to 50; 10 by default.", "schema": { "type": "integer", "minimum": 1, "maximum": 50 } }, { "name": "Motor-Mode", "in": "header", "required": false, "description": "`live` (default) or `test`. Test numbers are free and never connect to the phone network.", "schema": { "type": "string", "enum": [ "live", "test" ] } } ], "responses": { "200": { "description": "The matching numbers.", "content": { "application/json": { "example": { "data": [ { "phone_number": "+14155550123", "type": "local", "locality": "San Francisco", "region": "CA", "capabilities": { "sms": true, "mms": true, "voice": false }, "monthly_price_usd": "1.60" } ] } } } }, "401": { "description": "The key is missing or incorrect.", "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "This API key is invalid or has been revoked." } } } } }, "403": { "description": "The key can't use phone numbers, or it's a publishable key.", "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "This key cannot access this API. Update its permissions on the API keys page." } } } } }, "422": { "description": "Invalid filter or unsupported 800 prefix (`unsupported_number`).", "content": { "application/json": { "example": { "error": { "code": "unsupported_number", "message": "Motor doesn't sell 800 numbers. Use another toll-free prefix: 833, 844, 855, 866, 877, 888." } } } } }, "429": { "description": "Search limit reached. Wait the number of seconds in `Retry-After` before retrying.", "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "Too many requests. Retry after 2 seconds." } } } } }, "503": { "description": "Motor's number provider couldn't complete the search. Retry.", "content": { "application/json": { "example": { "error": { "code": "temporarily_unavailable", "message": "Motor's number provider couldn't complete the search. Retry in a few seconds." } } } } } } } }, "/numbers": { "post": { "operationId": "buyNumber", "tags": [ "Numbers" ], "summary": "Buy a number", "description": "Buys a specific number or the first match for your criteria, trying up to three candidates. Most numbers are `active` in the response. If `pending`, poll until `active` or `failed`. Billing starts on activation. Motor never substitutes another number for a specific number you request. An `Idempotency-Key` is required; retry with the same key to avoid buying a second number.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "1 to 128 printable ASCII characters. Use a new value for each purchase and reuse it for retries.", "schema": { "type": "string" } }, { "name": "Motor-Mode", "in": "header", "required": false, "description": "`live` (default) or `test`. Test numbers are free and never connect to the phone network.", "schema": { "type": "string", "enum": [ "live", "test" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone_number": { "type": "string", "description": "A specific number in E.164, such as `+14155550123`, usually from a search. Can't be combined with criteria." }, "type": { "type": "string", "enum": [ "local", "toll_free" ], "description": "Required when buying by criteria." }, "area_code": { "type": "string", "description": "Same as the search parameter." }, "region": { "type": "string", "description": "Same as the search parameter. Local numbers only." }, "contains": { "type": "string", "description": "Same as the search parameter. In test mode, `0000` creates a pending number that fails after 10 seconds." }, "label": { "type": [ "string", "null" ], "description": "Your name for the number, 0 to 128 UTF-8 bytes." } } }, "examples": { "criteria": { "value": { "type": "local", "area_code": "415" } }, "number": { "value": { "phone_number": "+14155550123", "label": "Order updates" } }, "toll_free": { "value": { "type": "toll_free" } } } } } }, "responses": { "201": { "description": "The number, `active` or `pending`.", "content": { "application/json": { "example": { "id": "pn_8Kq2vLxN4cT7", "phone_number": "+14155550123", "type": "local", "status": "active", "label": "Order updates", "locality": "San Francisco", "region": "CA", "capabilities": { "sms": true, "mms": true, "voice": false }, "used_by": null, "monthly_price_usd": "1.60", "billing_key_id": "key_BWBeN28Vb7cMEx7Ym8AUzs", "paid_through": "2026-11-09T18:22:04Z", "failure_reason": null, "created_at": "2026-10-09T18:22:01Z", "activated_at": "2026-10-09T18:22:04Z", "released_at": null } } }, "headers": { "ETag": { "description": "The number's version, for `If-Match`.", "schema": { "type": "string" } }, "Location": { "description": "The URL of the number.", "schema": { "type": "string" } } } }, "401": { "description": "The key is missing or incorrect.", "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "This API key is invalid or has been revoked." } } } } }, "403": { "description": "The key can't use phone numbers, or it's a publishable key.", "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "This key cannot access this API. Update its permissions on the API keys page." } } } } }, "402": { "description": "The first month would exceed the key's monthly spending limit.", "content": { "application/json": { "example": { "error": { "code": "spending_limit", "message": "The $1.60 charge for the first month would exceed this key's monthly spending limit. Raise the limit on the API keys page." } } } } }, "409": { "description": "The number is unavailable (`number_unavailable`), the team's number limit was reached (`quota_exceeded`), or the idempotency key was used for a different request.", "content": { "application/json": { "example": { "error": { "code": "number_unavailable", "message": "+14155550123 is no longer available. You weren't charged. Search for another number." } } } } }, "422": { "description": "A field isn't valid, no number matches the criteria (`no_numbers_available`), or the number is an 800 number (`unsupported_number`).", "content": { "application/json": { "example": { "error": { "code": "no_numbers_available", "message": "No numbers match these criteria. Try removing contains or region." } } } } }, "429": { "description": "The team's hourly purchase limit was reached.", "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "Your team has reached its limit of 20 number purchases per hour. Retry later." } } } } }, "503": { "description": "Motor's number provider couldn't accept the order. You weren't charged.", "content": { "application/json": { "example": { "error": { "code": "temporarily_unavailable", "message": "Motor's number provider couldn't accept the order. You weren't charged. Retry in a few minutes." } } } } } } }, "get": { "operationId": "listNumbers", "tags": [ "Numbers" ], "summary": "List your numbers", "description": "Lists the team's numbers in the selected mode, oldest first. Includes all statuses except `released` by default. Released and failed number records remain available for 90 days.", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Only numbers with this status.", "schema": { "type": "string", "enum": [ "pending", "active", "releasing", "released", "failed" ] } }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "local", "toll_free" ] } }, { "name": "area_code", "in": "query", "required": false, "description": "Three digits.", "schema": { "type": "string" } }, { "name": "in_use", "in": "query", "required": false, "description": "`true` for numbers used by a Motor resource; `false` for unused numbers.", "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "limit", "in": "query", "required": false, "description": "From 1 to 200; 50 by default.", "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "cursor", "in": "query", "required": false, "description": "The previous page's `next_cursor`.", "schema": { "type": "string" } }, { "name": "Motor-Mode", "in": "header", "required": false, "description": "`live` (default) or `test`. Test numbers are free and never connect to the phone network.", "schema": { "type": "string", "enum": [ "live", "test" ] } } ], "responses": { "200": { "description": "A page of numbers.", "content": { "application/json": { "example": { "data": [ { "id": "pn_8Kq2vLxN4cT7", "phone_number": "+14155550123", "type": "local", "status": "active", "label": "Order updates", "locality": "San Francisco", "region": "CA", "capabilities": { "sms": true, "mms": true, "voice": false }, "used_by": null, "monthly_price_usd": "1.60", "billing_key_id": "key_BWBeN28Vb7cMEx7Ym8AUzs", "paid_through": "2026-11-09T18:22:04Z", "failure_reason": null, "created_at": "2026-10-09T18:22:01Z", "activated_at": "2026-10-09T18:22:04Z", "released_at": null } ], "next_cursor": null } } } }, "401": { "description": "The key is missing or incorrect.", "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "This API key is invalid or has been revoked." } } } } }, "403": { "description": "The key can't use phone numbers, or it's a publishable key.", "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "This key cannot access this API. Update its permissions on the API keys page." } } } } }, "422": { "description": "A field or parameter isn't valid.", "content": { "application/json": { "example": { "error": { "code": "invalid_field", "message": "`area_code` must be three digits, such as 415." } } } } } } } }, "/numbers/{id}": { "get": { "operationId": "getNumber", "tags": [ "Numbers" ], "summary": "Read a number", "description": "Returns a number. Poll a `pending` number here until it's `active` or `failed`.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The number ID, such as `pn_8Kq2vLxN4cT7`.", "schema": { "type": "string" } }, { "name": "Motor-Mode", "in": "header", "required": false, "description": "`live` (default) or `test`. Test numbers are free and never connect to the phone network.", "schema": { "type": "string", "enum": [ "live", "test" ] } } ], "responses": { "200": { "description": "The number.", "content": { "application/json": { "example": { "id": "pn_8Kq2vLxN4cT7", "phone_number": "+14155550123", "type": "local", "status": "active", "label": "Order updates", "locality": "San Francisco", "region": "CA", "capabilities": { "sms": true, "mms": true, "voice": false }, "used_by": null, "monthly_price_usd": "1.60", "billing_key_id": "key_BWBeN28Vb7cMEx7Ym8AUzs", "paid_through": "2026-11-09T18:22:04Z", "failure_reason": null, "created_at": "2026-10-09T18:22:01Z", "activated_at": "2026-10-09T18:22:04Z", "released_at": null } } }, "headers": { "ETag": { "description": "The number's version, for `If-Match`.", "schema": { "type": "string" } } } }, "401": { "description": "The key is missing or incorrect.", "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "This API key is invalid or has been revoked." } } } } }, "403": { "description": "The key can't use phone numbers, or it's a publishable key.", "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "This key cannot access this API. Update its permissions on the API keys page." } } } } }, "404": { "description": "The number wasn't found for your team in this mode, or it was released or failed more than 90 days ago.", "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "The number doesn't exist." } } } } } } }, "patch": { "operationId": "updateNumber", "tags": [ "Numbers" ], "summary": "Change a number's label or billing key", "description": "Updates `label` and `billing_key_id`. Billing key changes take effect next month.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The number ID, such as `pn_8Kq2vLxN4cT7`.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": false, "description": "The number's ETag, such as `\"pn:pn_8Kq2vLxN4cT7:3\"`. Optional; when sent, the change applies only if the number hasn't changed.", "schema": { "type": "string" } }, { "name": "Motor-Mode", "in": "header", "required": false, "description": "`live` (default) or `test`. Test numbers are free and never connect to the phone network.", "schema": { "type": "string", "enum": [ "live", "test" ] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": [ "string", "null" ], "description": "0 to 128 UTF-8 bytes, or `null` to remove it." }, "billing_key_id": { "type": "string", "description": "The ID of an active API key for your team, such as `key_...`." } } }, "example": { "label": "Support line" } } } }, "responses": { "200": { "description": "The changed number.", "content": { "application/json": { "example": { "id": "pn_8Kq2vLxN4cT7", "phone_number": "+14155550123", "type": "local", "status": "active", "label": "Support line", "locality": "San Francisco", "region": "CA", "capabilities": { "sms": true, "mms": true, "voice": false }, "used_by": null, "monthly_price_usd": "1.60", "billing_key_id": "key_BWBeN28Vb7cMEx7Ym8AUzs", "paid_through": "2026-11-09T18:22:04Z", "failure_reason": null, "created_at": "2026-10-09T18:22:01Z", "activated_at": "2026-10-09T18:22:04Z", "released_at": null } } }, "headers": { "ETag": { "description": "The number's version, for `If-Match`.", "schema": { "type": "string" } } } }, "401": { "description": "The key is missing or incorrect.", "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "This API key is invalid or has been revoked." } } } } }, "403": { "description": "The key can't use phone numbers, or it's a publishable key.", "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "This key cannot access this API. Update its permissions on the API keys page." } } } } }, "404": { "description": "The number wasn't found for your team in this mode, or it was released or failed more than 90 days ago.", "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "The number doesn't exist." } } } } }, "409": { "description": "The number changed during the update. Read it again and retry.", "content": { "application/json": { "example": { "error": { "code": "revision_conflict", "message": "The number changed during the update. Read it again and retry." } } } } }, "412": { "description": "`If-Match` isn't the number's current ETag.", "content": { "application/json": { "example": { "error": { "code": "revision_conflict", "message": "The number changed since you read it. Read it again and retry with the new ETag." } } } } }, "422": { "description": "A field or parameter isn't valid.", "content": { "application/json": { "example": { "error": { "code": "invalid_field", "message": "`area_code` must be three digits, such as 415." } } } } } } }, "delete": { "operationId": "releaseNumber", "tags": [ "Numbers" ], "summary": "Release a number", "description": "Releases an unused active number. Its status becomes `releasing`, then `released` once the carrier confirms. Release is permanent, and the carrier can reassign the number. Unused time isn't refunded.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The number ID, such as `pn_8Kq2vLxN4cT7`.", "schema": { "type": "string" } }, { "name": "If-Match", "in": "header", "required": false, "description": "The number's ETag, such as `\"pn:pn_8Kq2vLxN4cT7:3\"`. Optional; when sent, the change applies only if the number hasn't changed.", "schema": { "type": "string" } }, { "name": "Motor-Mode", "in": "header", "required": false, "description": "`live` (default) or `test`. Test numbers are free and never connect to the phone network.", "schema": { "type": "string", "enum": [ "live", "test" ] } } ], "responses": { "200": { "description": "The number with status `releasing`.", "content": { "application/json": { "example": { "id": "pn_8Kq2vLxN4cT7", "phone_number": "+14155550123", "type": "local", "status": "releasing", "label": "Order updates", "locality": "San Francisco", "region": "CA", "capabilities": { "sms": true, "mms": true, "voice": false }, "used_by": null, "monthly_price_usd": "1.60", "billing_key_id": "key_BWBeN28Vb7cMEx7Ym8AUzs", "paid_through": "2026-11-09T18:22:04Z", "failure_reason": null, "created_at": "2026-10-09T18:22:01Z", "activated_at": "2026-10-09T18:22:04Z", "released_at": null } } }, "headers": { "ETag": { "description": "The number's version, for `If-Match`.", "schema": { "type": "string" } } } }, "401": { "description": "The key is missing or incorrect.", "content": { "application/json": { "example": { "error": { "code": "unauthorized", "message": "This API key is invalid or has been revoked." } } } } }, "403": { "description": "The key can't use phone numbers, or it's a publishable key.", "content": { "application/json": { "example": { "error": { "code": "forbidden", "message": "This key cannot access this API. Update its permissions on the API keys page." } } } } }, "404": { "description": "The number wasn't found for your team in this mode, or it was released or failed more than 90 days ago.", "content": { "application/json": { "example": { "error": { "code": "not_found", "message": "The number doesn't exist." } } } } }, "409": { "description": "A Motor resource uses the number (`number_in_use`, with `resource_id`), or the number isn't active (`invalid_state`).", "content": { "application/json": { "example": { "error": { "code": "number_in_use", "message": "Delete SMS sender sms_snd_1 before releasing this number.", "resource_id": "sms_snd_1" } } } } }, "412": { "description": "`If-Match` isn't the number's current ETag.", "content": { "application/json": { "example": { "error": { "code": "revision_conflict", "message": "The number changed since you read it. Read it again and retry with the new ETag." } } } } } } } } }, "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "A secret API key from the API keys page, such as `motor_sk_...`." } }, "schemas": { "Number": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID, starting with `pn_`. Buying the same phone number again gives a new ID." }, "phone_number": { "type": "string", "description": "The number in E.164, such as `+14155550123`." }, "type": { "type": "string", "enum": [ "local", "toll_free" ] }, "status": { "type": "string", "enum": [ "pending", "active", "releasing", "released", "failed" ], "description": "`pending`: awaiting carrier confirmation. `active`: ready to use. `releasing`: being returned to the carrier. `released`: returned to the carrier. `failed`: order failed; no charge." }, "label": { "type": [ "string", "null" ], "description": "Your name for the number, 0 to 128 UTF-8 bytes." }, "locality": { "type": [ "string", "null" ], "description": "The city of a local number, when known." }, "region": { "type": [ "string", "null" ], "description": "The two-letter state code for a local number, when known." }, "capabilities": { "type": "object", "description": "Supported services: SMS and MMS. Voice is not supported.", "properties": { "sms": { "type": "boolean" }, "mms": { "type": "boolean" }, "voice": { "type": "boolean" } } }, "used_by": { "type": [ "object", "null" ], "description": "The Motor resource that uses the number, such as an SMS sender, or `null`.", "properties": { "service": { "type": "string" }, "type": { "type": "string" }, "id": { "type": "string" } } }, "monthly_price_usd": { "type": "string", "description": "The monthly price, in US dollars: `1.60` for every number." }, "billing_key_id": { "type": "string", "description": "The API key associated with the account charged for rent. Defaults to the key that bought the number." }, "paid_through": { "type": [ "string", "null" ], "format": "date-time", "description": "When the paid month ends. The next month is charged then." }, "failure_reason": { "type": [ "string", "null" ], "enum": [ "number_unavailable", "provider_error", null ], "description": "The reason the order failed." }, "created_at": { "type": "string", "format": "date-time" }, "activated_at": { "type": [ "string", "null" ], "format": "date-time" }, "released_at": { "type": [ "string", "null" ], "format": "date-time" } } } } } }