{ "openapi": "3.0.3", "info": { "title": "JoltSMS API", "description": "Enterprise SMS management platform API", "version": "1.0.0" }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer" }, "apiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key" }, "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "joltsms_session" } }, "schemas": {} }, "paths": { "/v1/numbers/available-area-codes": { "get": { "tags": [ "Numbers" ], "description": "Get cached list of available area codes with state information", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "areaCode": { "type": "string" }, "state": { "type": "string" } }, "required": [ "areaCode", "state" ], "additionalProperties": false } } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } } } } }, "/v1/numbers/rent": { "post": { "tags": [ "Numbers" ], "description": "Rent a new phone number using modern Stripe billing flow", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "areaCode": { "type": "string" }, "preferredAreaCode": { "type": "boolean" }, "emailDelivery": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "to": { "type": "string" }, "cc": { "type": "string" } }, "required": [ "enabled" ], "additionalProperties": false }, "autoRenew": { "type": "boolean", "default": true } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "x-idempotency-key", "required": false } ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "subscriptionId": { "type": "string" }, "status": { "type": "string" }, "clientSecret": { "type": "string" }, "requiresAction": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "success", "status", "requiresAction" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } } } } }, "/v1/numbers/available": { "get": { "tags": [ "Numbers" ], "description": "Search for available phone numbers to rent", "parameters": [ { "schema": { "type": "string", "minLength": 3, "maxLength": 3 }, "in": "query", "name": "areaCode", "required": false }, { "schema": { "type": "number", "minimum": 1, "maximum": 50, "default": 10 }, "in": "query", "name": "limit", "required": false } ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "phoneNumber": { "type": "string" }, "areaCode": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" }, "monthlyPrice": { "type": "number" }, "formattedPrice": { "type": "string" }, "capabilities": { "type": "array", "items": { "type": "string", "enum": [ "sms", "voice", "mms" ] } } }, "required": [ "phoneNumber", "areaCode", "city", "state", "country", "monthlyPrice", "formattedPrice", "capabilities" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "count": { "type": "number" }, "limit": { "type": "number" } }, "required": [ "count", "limit" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } } } } }, "/v1/numbers": { "get": { "tags": [ "Numbers" ], "description": "List user's phone numbers with cursor pagination", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 20 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string", "enum": [ "active", "provisioning", "releasing", "released", "failed", "suspended", "cancelled" ] }, "in": "query", "name": "status", "required": false }, { "schema": { "type": "string", "enum": [ "owned", "shared", "all" ], "default": "all" }, "in": "query", "name": "scope", "required": false } ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "phoneNumber": { "type": "string" }, "status": { "type": "string" }, "displayStatus": { "type": "string" }, "verificationId": { "type": "string" }, "serviceName": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "notes": { "type": "string" }, "billingCycleId": { "type": "string" }, "stripeSubscriptionId": { "type": "string" }, "subscriptionId": { "type": "string", "format": "uuid" }, "subscriptionStatus": { "type": "string" }, "autoRenewEnabled": { "type": "boolean" }, "enterpriseContractId": { "type": "string" }, "enterpriseContractName": { "type": "string" }, "enterpriseLineState": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "rentedAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time", "description": "Legacy upstream/provider rental lease end. Do not use as customer paid-through, renewal, cancellation, or next-charge date." }, "nextBillingDate": { "type": "string", "format": "date-time", "description": "Legacy number-level billing mirror. Prefer customerEntitlementEndsAt for paid-through dates and nextChargeDate for card charge dates." }, "nextChargeDate": { "type": "string", "format": "date-time", "nullable": true, "description": "Next scheduled customer card charge or retry date from the subscription." }, "customerEntitlementEndsAt": { "type": "string", "format": "date-time", "description": "Customer paid-through/service entitlement end from the Jolt/Stripe subscription period." }, "cancelAtPeriodEnd": { "type": "boolean" }, "messageCount": { "type": "number" }, "unreadCount": { "type": "number" }, "lastMessageAt": { "type": "string", "format": "date-time" }, "isShared": { "type": "boolean" }, "accessRole": { "type": "string", "enum": [ "OWNER", "VIEWER", "MANAGER" ] }, "owner": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "name": { "type": "string", "nullable": true } }, "required": [ "id", "email", "name" ], "additionalProperties": false } }, "required": [ "id", "phoneNumber", "status", "verificationId", "createdAt", "updatedAt", "rentedAt", "messageCount", "unreadCount" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "nextCursor": { "type": "string" }, "total": { "type": "number" }, "limit": { "type": "number" } }, "required": [ "hasMore", "total", "limit" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } } } }, "post": { "tags": [ "Numbers" ], "description": "Provision a new phone number (async operation)", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "subscriptionId": { "type": "string" }, "idempotencyKey": { "type": "string" } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string" }, "in": "header", "name": "x-idempotency-key", "required": false } ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "number": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "statusUrl": { "type": "string" } }, "required": [ "id", "status", "statusUrl" ], "additionalProperties": false }, "jobId": { "type": "string" }, "error": { "type": "string" } }, "required": [ "success" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "existing": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string" }, "jobId": { "type": "string" } }, "required": [ "id", "status" ], "additionalProperties": false } }, "required": [ "error", "message" ], "additionalProperties": false } } } } } } }, "/v1/numbers/{id}": { "get": { "tags": [ "Numbers" ], "description": "Get detailed information about a specific phone number", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "phoneNumber": { "type": "string" }, "status": { "type": "string" }, "displayStatus": { "type": "string" }, "verificationId": { "type": "string" }, "serviceName": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "notes": { "type": "string" }, "billingCycleId": { "type": "string" }, "stripeSubscriptionId": { "type": "string" }, "subscriptionId": { "type": "string", "format": "uuid" }, "subscriptionStatus": { "type": "string" }, "autoRenewEnabled": { "type": "boolean" }, "enterpriseContractId": { "type": "string" }, "enterpriseContractName": { "type": "string" }, "enterpriseLineState": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "rentedAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time", "description": "Legacy upstream/provider rental lease end. Do not use as customer paid-through, renewal, cancellation, or next-charge date." }, "nextBillingDate": { "type": "string", "format": "date-time", "description": "Legacy number-level billing mirror. Prefer customerEntitlementEndsAt for paid-through dates and nextChargeDate for card charge dates." }, "nextChargeDate": { "type": "string", "format": "date-time", "nullable": true, "description": "Next scheduled customer card charge or retry date from the subscription." }, "customerEntitlementEndsAt": { "type": "string", "format": "date-time", "description": "Customer paid-through/service entitlement end from the Jolt/Stripe subscription period." }, "cancelAtPeriodEnd": { "type": "boolean" }, "messageCount": { "type": "number" }, "unreadCount": { "type": "number" }, "lastMessageAt": { "type": "string", "format": "date-time" }, "isShared": { "type": "boolean" }, "accessRole": { "type": "string", "enum": [ "OWNER", "VIEWER", "MANAGER" ] }, "owner": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "name": { "type": "string", "nullable": true } }, "required": [ "id", "email", "name" ], "additionalProperties": false } }, "required": [ "id", "phoneNumber", "status", "verificationId", "createdAt", "updatedAt", "rentedAt", "messageCount", "unreadCount" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } } } }, "put": { "tags": [ "Numbers" ], "description": "Update phone number details (e.g., label)", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "serviceName": { "type": "string", "minLength": 1, "maxLength": 100 }, "tags": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 50 }, "maxItems": 20 }, "notes": { "type": "string", "maxLength": 1000 } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "phoneNumber": { "type": "string" }, "status": { "type": "string" }, "displayStatus": { "type": "string" }, "verificationId": { "type": "string" }, "serviceName": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "notes": { "type": "string" }, "billingCycleId": { "type": "string" }, "stripeSubscriptionId": { "type": "string" }, "subscriptionId": { "type": "string", "format": "uuid" }, "subscriptionStatus": { "type": "string" }, "autoRenewEnabled": { "type": "boolean" }, "enterpriseContractId": { "type": "string" }, "enterpriseContractName": { "type": "string" }, "enterpriseLineState": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "rentedAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time", "description": "Legacy upstream/provider rental lease end. Do not use as customer paid-through, renewal, cancellation, or next-charge date." }, "nextBillingDate": { "type": "string", "format": "date-time", "description": "Legacy number-level billing mirror. Prefer customerEntitlementEndsAt for paid-through dates and nextChargeDate for card charge dates." }, "nextChargeDate": { "type": "string", "format": "date-time", "nullable": true, "description": "Next scheduled customer card charge or retry date from the subscription." }, "customerEntitlementEndsAt": { "type": "string", "format": "date-time", "description": "Customer paid-through/service entitlement end from the Jolt/Stripe subscription period." }, "cancelAtPeriodEnd": { "type": "boolean" }, "messageCount": { "type": "number" }, "unreadCount": { "type": "number" }, "lastMessageAt": { "type": "string", "format": "date-time" }, "isShared": { "type": "boolean" }, "accessRole": { "type": "string", "enum": [ "OWNER", "VIEWER", "MANAGER" ] }, "owner": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "name": { "type": "string", "nullable": true } }, "required": [ "id", "email", "name" ], "additionalProperties": false } }, "required": [ "id", "phoneNumber", "status", "verificationId", "createdAt", "updatedAt", "rentedAt", "messageCount", "unreadCount" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } } } }, "delete": { "tags": [ "Numbers" ], "description": "Cancel/release a phone number (async operation, idempotent)", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true }, { "schema": { "type": "string" }, "in": "header", "name": "x-idempotency-key", "required": false } ], "security": [ { "sessionCookie": [] } ], "responses": { "202": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "jobId": { "type": "string" }, "statusUrl": { "type": "string" } }, "required": [ "success", "message", "jobId", "statusUrl" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "currentStatus": { "type": "string" } }, "required": [ "error", "message", "currentStatus" ], "additionalProperties": false } } } } } } }, "/v1/numbers/{id}/messages": { "get": { "tags": [ "Numbers" ], "description": "Get SMS messages for a specific phone number", "parameters": [ { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 20 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "from", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "to", "required": false }, { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" }, "body": { "type": "string" }, "parsedCode": { "type": "string" }, "parsedCodeConfidence": { "type": "number" }, "encrypted": { "type": "boolean" }, "receivedAt": { "type": "string", "format": "date-time" }, "ingestedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "from", "to", "body", "encrypted", "receivedAt", "ingestedAt" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "nextCursor": { "type": "string" }, "total": { "type": "number" }, "limit": { "type": "number" } }, "required": [ "hasMore", "total", "limit" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } } } } }, "/v1/messages": { "get": { "tags": [ "Messages" ], "description": "List SMS messages for authenticated user with filtering and cursor pagination", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "numberId", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 20 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "from", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "to", "required": false }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "since", "required": false } ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "numberId": { "type": "string", "format": "uuid" }, "number": { "type": "object", "properties": { "id": { "type": "string" }, "phoneNumber": { "type": "string" } }, "required": [ "id", "phoneNumber" ], "additionalProperties": false }, "from": { "type": "string" }, "to": { "type": "string" }, "body": { "type": "string" }, "parsedCode": { "type": "string" }, "parsedCodeConfidence": { "type": "number" }, "encrypted": { "type": "boolean" }, "isRead": { "type": "boolean" }, "receivedAt": { "type": "string", "format": "date-time" }, "ingestedAt": { "type": "string", "format": "date-time" }, "providerEventId": { "type": "string" }, "reply": { "type": "object", "properties": { "canReply": { "type": "boolean" }, "unavailableReason": { "type": "string", "enum": [ "api_key_capability_required", "oauth_scope_required", "permission_required", "number_not_active", "provider_sms_id_missing", "already_replied", "reply_in_progress" ] }, "unavailableMessage": { "type": "string" }, "lastReplyId": { "type": "string", "format": "uuid" }, "lastReplyStatus": { "type": "string", "enum": [ "PENDING", "SENT", "FAILED", "UNKNOWN", "REJECTED" ] }, "lastReplyAt": { "type": "string", "format": "date-time" } }, "required": [ "canReply" ], "additionalProperties": false } }, "required": [ "id", "numberId", "number", "from", "to", "body", "encrypted", "isRead", "receivedAt", "ingestedAt", "providerEventId", "reply" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "nextCursor": { "type": "string" }, "total": { "type": "number" }, "limit": { "type": "number" }, "filters": { "type": "object", "properties": { "numberId": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" }, "since": { "type": "string" } }, "additionalProperties": false } }, "required": [ "hasMore", "total", "limit", "filters" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } } } } }, "/v1/messages/{id}": { "get": { "tags": [ "Messages" ], "description": "Get details of a specific SMS message", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "numberId": { "type": "string", "format": "uuid" }, "number": { "type": "object", "properties": { "id": { "type": "string" }, "phoneNumber": { "type": "string" } }, "required": [ "id", "phoneNumber" ], "additionalProperties": false }, "from": { "type": "string" }, "to": { "type": "string" }, "body": { "type": "string" }, "parsedCode": { "type": "string" }, "parsedCodeConfidence": { "type": "number" }, "encrypted": { "type": "boolean" }, "isRead": { "type": "boolean" }, "receivedAt": { "type": "string", "format": "date-time" }, "ingestedAt": { "type": "string", "format": "date-time" }, "providerEventId": { "type": "string" }, "reply": { "type": "object", "properties": { "canReply": { "type": "boolean" }, "unavailableReason": { "type": "string", "enum": [ "api_key_capability_required", "oauth_scope_required", "permission_required", "number_not_active", "provider_sms_id_missing", "already_replied", "reply_in_progress" ] }, "unavailableMessage": { "type": "string" }, "lastReplyId": { "type": "string", "format": "uuid" }, "lastReplyStatus": { "type": "string", "enum": [ "PENDING", "SENT", "FAILED", "UNKNOWN", "REJECTED" ] }, "lastReplyAt": { "type": "string", "format": "date-time" } }, "required": [ "canReply" ], "additionalProperties": false } }, "required": [ "id", "numberId", "number", "from", "to", "body", "encrypted", "isRead", "receivedAt", "ingestedAt", "providerEventId", "reply" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } } } } }, "/v1/messages/{id}/reply": { "post": { "tags": [ "Messages" ], "description": "Reply to a specific inbound SMS. The destination is resolved server-side from the original message.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "string", "minLength": 1, "maxLength": 15, "description": "SMS reply content. The destination is always resolved from the original message." } }, "required": [ "content" ], "additionalProperties": {} } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "replyId": { "type": "string", "format": "uuid" }, "messageId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "PENDING", "SENT", "FAILED", "UNKNOWN", "REJECTED" ] }, "sentAt": { "type": "string", "format": "date-time", "nullable": true }, "correlationId": { "type": "string" }, "message": { "type": "string" } }, "required": [ "success", "replyId", "messageId", "status", "correlationId", "message" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "replyId": { "type": "string", "format": "uuid" }, "correlationId": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "replyId": { "type": "string", "format": "uuid" }, "correlationId": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "replyId": { "type": "string", "format": "uuid" }, "correlationId": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "replyId": { "type": "string", "format": "uuid" }, "correlationId": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "replyId": { "type": "string", "format": "uuid" }, "correlationId": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "replyId": { "type": "string", "format": "uuid" }, "correlationId": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } } } } }, "/v1/messages/{id}/read": { "put": { "tags": [ "Messages" ], "description": "Mark SMS message as read", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "messageId": { "type": "string" }, "readAt": { "type": "string", "format": "date-time" } }, "required": [ "success", "messageId", "readAt" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } } } } }, "/v1/messages/search": { "get": { "tags": [ "Messages" ], "description": "Search SMS messages by content, sender, or other criteria", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100 }, "in": "query", "name": "q", "required": true }, { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "numberId", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "from", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "to", "required": false }, { "schema": { "type": "string", "format": "date-time" }, "in": "query", "name": "since", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "cursor", "required": false }, { "schema": { "type": "number", "minimum": 1, "maximum": 50, "default": 20 }, "in": "query", "name": "limit", "required": false } ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "numberId": { "type": "string", "format": "uuid" }, "number": { "type": "object", "properties": { "id": { "type": "string" }, "phoneNumber": { "type": "string" } }, "required": [ "id", "phoneNumber" ], "additionalProperties": false }, "from": { "type": "string" }, "to": { "type": "string" }, "body": { "type": "string" }, "parsedCode": { "type": "string" }, "parsedCodeConfidence": { "type": "number" }, "encrypted": { "type": "boolean" }, "isRead": { "type": "boolean" }, "receivedAt": { "type": "string", "format": "date-time" }, "ingestedAt": { "type": "string", "format": "date-time" }, "providerEventId": { "type": "string" }, "reply": { "type": "object", "properties": { "canReply": { "type": "boolean" }, "unavailableReason": { "type": "string", "enum": [ "api_key_capability_required", "oauth_scope_required", "permission_required", "number_not_active", "provider_sms_id_missing", "already_replied", "reply_in_progress" ] }, "unavailableMessage": { "type": "string" }, "lastReplyId": { "type": "string", "format": "uuid" }, "lastReplyStatus": { "type": "string", "enum": [ "PENDING", "SENT", "FAILED", "UNKNOWN", "REJECTED" ] }, "lastReplyAt": { "type": "string", "format": "date-time" } }, "required": [ "canReply" ], "additionalProperties": false } }, "required": [ "id", "numberId", "number", "from", "to", "body", "encrypted", "isRead", "receivedAt", "ingestedAt", "providerEventId", "reply" ], "additionalProperties": false } }, "meta": { "type": "object", "properties": { "hasMore": { "type": "boolean" }, "nextCursor": { "type": "string" }, "total": { "type": "number" }, "limit": { "type": "number" }, "filters": { "type": "object", "properties": { "numberId": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" }, "since": { "type": "string" } }, "additionalProperties": false } }, "required": [ "hasMore", "total", "limit", "filters" ], "additionalProperties": false } }, "required": [ "data", "meta" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } } } } }, "/v1/messages/mark-all-read": { "put": { "tags": [ "Messages" ], "description": "Mark all user messages as read (optionally filtered by number)", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "query", "name": "numberId", "required": false } ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "count": { "type": "number" }, "message": { "type": "string" } }, "required": [ "success", "count", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } } } } }, "/v1/billing/payment-method": { "post": { "tags": [ "Billing", "Payment Methods" ], "description": "Create SetupIntent for saving payment method with 3DS", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "clientSecret": { "type": "string" }, "setupIntentId": { "type": "string" } }, "required": [ "clientSecret", "setupIntentId" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } } } } }, "/v1/billing/payment-methods": { "get": { "tags": [ "Billing", "Payment Methods" ], "description": "List payment methods for customer", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "brand": { "type": "string" }, "last4": { "type": "string" }, "expMonth": { "type": "number" }, "expYear": { "type": "number" }, "isDefault": { "type": "boolean" } }, "required": [ "id", "isDefault" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/v1/billing/payment-methods/{pmId}/default": { "post": { "tags": [ "Billing", "Payment Methods" ], "description": "Set customer default payment method", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "pmId", "required": true } ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } } } } }, "/v1/billing/payment-methods/{pmId}": { "delete": { "tags": [ "Billing", "Payment Methods" ], "description": "Detach payment method from customer", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "pmId", "required": true } ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "guidance": { "type": "string" } }, "required": [ "error", "message", "guidance" ], "additionalProperties": false } } } } } }, "put": { "tags": [ "Billing", "Payment Methods" ], "description": "Update payment method expiration date (CVC cannot be updated - Stripe PCI compliance)", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "expMonth": { "type": "number", "minimum": 1, "maximum": 12 }, "expYear": { "type": "number", "minimum": 2026, "maximum": 2046 } }, "required": [ "expMonth", "expYear" ], "additionalProperties": false } } }, "required": true }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "pmId", "required": true } ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "brand": { "type": "string" }, "last4": { "type": "string" }, "expMonth": { "type": "number" }, "expYear": { "type": "number" }, "isDefault": { "type": "boolean" } }, "required": [ "id", "isDefault" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } } } } }, "/v1/billing/checkout-reservation": { "post": { "tags": [ "Billing", "Subscriptions" ], "description": "Reserve a ready pooled number before starting a payment flow", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "type": "string", "enum": [ "monthly_any_number" ], "default": "monthly_any_number" }, "client": { "type": "string", "enum": [ "web", "ios", "android" ] }, "checkoutAttemptId": { "type": "string", "minLength": 8, "maxLength": 128, "pattern": "^[A-Za-z0-9._:-]+$" } }, "required": [ "client", "checkoutAttemptId" ], "additionalProperties": false } } }, "required": true }, "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "reservationId": { "type": "string", "format": "uuid" }, "product": { "type": "string", "enum": [ "monthly_any_number" ] }, "client": { "type": "string", "enum": [ "web", "ios", "android" ] }, "status": { "type": "string", "enum": [ "RESERVED" ] }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "reservationId", "product", "client", "status", "expiresAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } } } } }, "/v1/billing/backorder-intents/current": { "get": { "tags": [ "Billing", "Subscriptions" ], "description": "Get the current web backorder intent for the authenticated user", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "intent": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "WAITING_FOR_INVENTORY", "FULFILLING", "PAYMENT_FAILED", "PAYMENT_ACTION_REQUIRED", "FULFILLED", "CANCELLED" ] }, "priceBaseId": { "type": "string" }, "basePriceDisplay": { "type": "string", "nullable": true }, "billingInterval": { "type": "string", "enum": [ "MONTHLY", "ANNUAL" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "status", "priceBaseId", "billingInterval", "createdAt", "updatedAt" ], "additionalProperties": false, "nullable": true } }, "required": [ "intent" ], "additionalProperties": false } } } } } } }, "/v1/billing/backorder-intents": { "post": { "tags": [ "Billing", "Subscriptions" ], "description": "Create a web backorder intent for any-number checkout", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "product": { "type": "string", "enum": [ "monthly_any_number" ], "default": "monthly_any_number" }, "client": { "type": "string", "enum": [ "web" ], "default": "web" }, "paymentMethodId": { "type": "string", "minLength": 3 }, "setupIntentId": { "type": "string", "minLength": 3 }, "billingInterval": { "type": "string", "enum": [ "MONTHLY", "ANNUAL" ], "default": "MONTHLY" }, "termsAccepted": { "type": "boolean", "enum": [ true ] } }, "required": [ "paymentMethodId", "termsAccepted" ], "additionalProperties": false } } }, "required": true }, "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "WAITING_FOR_INVENTORY", "FULFILLING", "PAYMENT_FAILED", "PAYMENT_ACTION_REQUIRED", "FULFILLED", "CANCELLED" ] }, "priceBaseId": { "type": "string" }, "basePriceDisplay": { "type": "string", "nullable": true }, "billingInterval": { "type": "string", "enum": [ "MONTHLY", "ANNUAL" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "status", "priceBaseId", "billingInterval", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } } } } }, "/v1/billing/backorder-intents/{id}": { "delete": { "tags": [ "Billing", "Subscriptions" ], "description": "Cancel a waiting web backorder intent", "parameters": [ { "schema": { "type": "string", "minLength": 1 }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "WAITING_FOR_INVENTORY", "FULFILLING", "PAYMENT_FAILED", "PAYMENT_ACTION_REQUIRED", "FULFILLED", "CANCELLED" ] }, "priceBaseId": { "type": "string" }, "basePriceDisplay": { "type": "string", "nullable": true }, "billingInterval": { "type": "string", "enum": [ "MONTHLY", "ANNUAL" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "status", "priceBaseId", "billingInterval", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } } } } }, "/v1/billing/subscription": { "post": { "tags": [ "Billing", "Subscriptions" ], "description": "Create subscription using modern Stripe flow", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "priceBaseId": { "type": "string" }, "wantsAreaCode": { "type": "boolean", "default": false }, "areaCode": { "type": "string" }, "autoRenew": { "type": "boolean", "default": true }, "paymentMethodId": { "type": "string" }, "billingInterval": { "type": "string", "enum": [ "MONTHLY", "ANNUAL" ], "default": "MONTHLY" }, "checkoutReservationId": { "type": "string", "format": "uuid" } }, "required": [ "priceBaseId" ], "additionalProperties": false } } }, "required": true }, "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscriptionId": { "type": "string" }, "status": { "type": "string" }, "clientSecret": { "type": "string" }, "requiresAction": { "type": "boolean" }, "requiresPaymentMethod": { "type": "boolean" }, "paymentStatus": { "type": "string" } }, "required": [ "subscriptionId", "status", "requiresAction" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } } } }, "get": { "tags": [ "Billing", "Subscriptions" ], "description": "Get most recent subscription (backward compatibility)", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscription": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "stripeSubscriptionId": { "type": "string", "nullable": true }, "billingProvider": { "type": "string", "enum": [ "STRIPE", "APP_STORE", "GOOGLE_PLAY" ] }, "externalSubscriptionId": { "type": "string", "nullable": true }, "externalOriginalTransactionId": { "type": "string", "nullable": true }, "storeProductId": { "type": "string", "nullable": true }, "status": { "type": "string" }, "billingHealth": { "type": "string", "enum": [ "healthy", "payment_failing", "suspended", "ending", "canceled", "setup_required" ] }, "priceBaseId": { "type": "string" }, "priceAddonId": { "type": "string" }, "areaCodePref": { "type": "string" }, "numberId": { "type": "string" }, "currentPeriodStart": { "type": "string", "format": "date-time" }, "currentPeriodEnd": { "type": "string", "format": "date-time" }, "nextChargeDate": { "type": "string", "format": "date-time", "nullable": true }, "serviceGraceUntil": { "type": "string", "format": "date-time" }, "cancelAtPeriodEnd": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "isServiceAllowed": { "type": "boolean" }, "defaultPaymentMethodId": { "type": "string" }, "basePriceDisplay": { "type": "string" }, "addonPriceDisplay": { "type": "string" }, "billingInterval": { "type": "string", "enum": [ "MONTHLY", "ANNUAL" ], "default": "MONTHLY" }, "tvUpgradeRequestedAt": { "type": "string", "format": "date-time", "nullable": true }, "tvUpgradeFulfilledAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "id", "stripeSubscriptionId", "billingProvider", "status", "billingHealth", "priceBaseId", "currentPeriodStart", "currentPeriodEnd", "serviceGraceUntil", "cancelAtPeriodEnd", "createdAt", "isServiceAllowed" ], "additionalProperties": false, "nullable": true } }, "required": [ "subscription" ], "additionalProperties": false } } } } } } }, "/v1/billing/subscriptions": { "get": { "tags": [ "Billing", "Subscriptions" ], "description": "Get all active subscription details", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "subscriptions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "stripeSubscriptionId": { "type": "string", "nullable": true }, "billingProvider": { "type": "string", "enum": [ "STRIPE", "APP_STORE", "GOOGLE_PLAY" ] }, "externalSubscriptionId": { "type": "string", "nullable": true }, "externalOriginalTransactionId": { "type": "string", "nullable": true }, "storeProductId": { "type": "string", "nullable": true }, "status": { "type": "string" }, "billingHealth": { "type": "string", "enum": [ "healthy", "payment_failing", "suspended", "ending", "canceled", "setup_required" ] }, "priceBaseId": { "type": "string" }, "priceAddonId": { "type": "string" }, "areaCodePref": { "type": "string" }, "numberId": { "type": "string" }, "currentPeriodStart": { "type": "string", "format": "date-time" }, "currentPeriodEnd": { "type": "string", "format": "date-time" }, "nextChargeDate": { "type": "string", "format": "date-time", "nullable": true }, "serviceGraceUntil": { "type": "string", "format": "date-time" }, "cancelAtPeriodEnd": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "isServiceAllowed": { "type": "boolean" }, "defaultPaymentMethodId": { "type": "string" }, "basePriceDisplay": { "type": "string" }, "addonPriceDisplay": { "type": "string" }, "billingInterval": { "type": "string", "enum": [ "MONTHLY", "ANNUAL" ], "default": "MONTHLY" }, "tvUpgradeRequestedAt": { "type": "string", "format": "date-time", "nullable": true }, "tvUpgradeFulfilledAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "id", "stripeSubscriptionId", "billingProvider", "status", "billingHealth", "priceBaseId", "currentPeriodStart", "currentPeriodEnd", "serviceGraceUntil", "cancelAtPeriodEnd", "createdAt", "isServiceAllowed" ], "additionalProperties": false } } }, "required": [ "subscriptions" ], "additionalProperties": false } } } } } } }, "/v1/billing/subscriptions/{id}/open-invoice": { "get": { "tags": [ "Billing", "Subscriptions" ], "description": "Get open invoice for subscription with failed payment method details", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "invoice": { "type": "object", "properties": { "id": { "type": "string" }, "amount": { "type": "number" }, "status": { "type": "string" }, "failedPaymentMethodId": { "type": "string" }, "created": { "type": "number" } }, "required": [ "id", "amount", "status", "created" ], "additionalProperties": false } }, "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } } } } }, "/v1/billing/subscriptions/{id}/auto-renew": { "post": { "tags": [ "Billing", "Subscriptions" ], "description": "Toggle auto-renew for subscription", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "required": [ "enabled" ], "additionalProperties": false } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } } } } }, "/v1/billing/subscriptions/{id}/upgrade-to-annual/preview": { "get": { "tags": [ "Billing", "Subscriptions" ], "description": "Preview the proration breakdown for upgrading a MONTHLY subscription to ANNUAL", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "fullAnnualAmount": { "type": "number" }, "prorationCredit": { "type": "number" }, "dueToday": { "type": "number" }, "currency": { "type": "string" }, "currentCycleEnd": { "type": "string", "format": "date-time" }, "newCycleEnd": { "type": "string", "format": "date-time" }, "basePriceId": { "type": "string" }, "addonPriceId": { "type": "string", "nullable": true }, "hasAddon": { "type": "boolean" }, "savings": { "type": "object", "properties": { "annualVsMonthly": { "type": "number" }, "monthsFree": { "type": "number" } }, "required": [ "annualVsMonthly", "monthsFree" ], "additionalProperties": false } }, "required": [ "fullAnnualAmount", "prorationCredit", "dueToday", "currency", "currentCycleEnd", "newCycleEnd", "basePriceId", "addonPriceId", "hasAddon", "savings" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } } } } }, "/v1/billing/subscriptions/{id}/upgrade-to-annual": { "post": { "tags": [ "Billing", "Subscriptions" ], "description": "Commit upgrade of a MONTHLY subscription to ANNUAL with prorated charge", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "paymentMethodId": { "type": "string" } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "invoiceId": { "type": "string" }, "amountCharged": { "type": "number" }, "newCycleEnd": { "type": "string", "format": "date-time" }, "requiresAction": { "type": "boolean" }, "clientSecret": { "type": "string" } }, "required": [ "success", "invoiceId", "amountCharged", "newCycleEnd", "requiresAction" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "402": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "clientSecret": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } } } } }, "/v1/billing/subscriptions/{id}/payment-method": { "post": { "tags": [ "Billing", "Subscriptions" ], "description": "Set payment method for specific subscription", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "paymentMethodId": { "type": "string" } }, "required": [ "paymentMethodId" ], "additionalProperties": false } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "id", "required": true } ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" } }, "required": [ "success" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } } } } }, "/v1/billing/preview": { "post": { "tags": [ "Billing", "Preview" ], "description": "Preview billing for subscription items with tax calculation", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "priceBaseId": { "type": "string" }, "priceAddonId": { "type": "string" } }, "required": [ "priceBaseId" ], "additionalProperties": false } } }, "required": true }, "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "subtotal": { "type": "number" }, "taxAmount": { "type": "number" }, "total": { "type": "number" }, "currency": { "type": "string" }, "taxDisplayName": { "type": "string" } }, "required": [ "subtotal", "taxAmount", "total", "currency" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } } } } }, "/v1/billing/invoices/{invoiceId}/pay": { "post": { "tags": [ "Billing", "Invoices" ], "description": "Pay an open invoice with a specific payment method", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "paymentMethodId": { "type": "string" } }, "required": [ "paymentMethodId" ], "additionalProperties": false } } }, "required": true }, "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "invoiceId", "required": true } ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "status": { "type": "string" }, "amountPaid": { "type": "number" } }, "required": [ "success", "status", "amountPaid" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } } } } }, "/v1/billing/invoices": { "get": { "tags": [ "Billing", "Invoices" ], "description": "List customer invoices with phone number details", "parameters": [ { "schema": { "type": "number", "minimum": 1, "maximum": 100, "default": 20 }, "in": "query", "name": "limit", "required": false }, { "schema": { "type": "string" }, "in": "query", "name": "startingAfter", "required": false }, { "schema": { "type": "string", "enum": [ "draft", "open", "paid", "void", "uncollectible" ] }, "in": "query", "name": "status", "required": false } ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string", "nullable": true }, "created": { "type": "number" }, "periodStart": { "type": "number" }, "periodEnd": { "type": "number" }, "total": { "type": "number" }, "amountDue": { "type": "number" }, "amountPaid": { "type": "number" }, "status": { "type": "string" }, "invoicePdf": { "type": "string", "nullable": true }, "hostedInvoiceUrl": { "type": "string", "nullable": true }, "receiptUrl": { "type": "string", "nullable": true }, "phoneNumber": { "type": "string", "nullable": true }, "phoneNumberE164": { "type": "string", "nullable": true } }, "required": [ "id", "number", "created", "periodStart", "periodEnd", "total", "amountDue", "amountPaid", "status", "invoicePdf", "hostedInvoiceUrl", "receiptUrl", "phoneNumber", "phoneNumberE164" ], "additionalProperties": false } }, "hasMore": { "type": "boolean" } }, "required": [ "data", "hasMore" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } } } } }, "/v1/billing/invoices/authentication-required": { "get": { "tags": [ "Billing", "Invoices" ], "description": "Get invoices requiring 3DS authentication", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "subscriptionId": { "type": "string" }, "invoiceId": { "type": "string" }, "amount": { "type": "string" }, "phoneNumber": { "type": "string" }, "hostedInvoiceUrl": { "type": "string" }, "daysUntilExpiry": { "type": "number" } }, "required": [ "subscriptionId", "invoiceId", "amount", "hostedInvoiceUrl", "daysUntilExpiry" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/v1/billing/portal": { "post": { "tags": [ "Billing" ], "description": "Create Stripe customer portal session", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "returnUrl": { "type": "string", "format": "uri" } }, "required": [ "returnUrl" ], "additionalProperties": false } } }, "required": true }, "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "portalUrl": { "type": "string", "format": "uri" }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "portalUrl", "expiresAt" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } } } } }, "/v1/billing/numbers/{numberId}/recovery-status": { "get": { "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "numberId", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "recoverable": { "type": "boolean" }, "textVerifiedState": { "type": "string", "enum": [ "renewableActive", "renewableOverdue", "renewableExpired", "renewableRefunded", "expired", "cancelled" ], "nullable": true }, "amountDue": { "type": "number" }, "invoiceId": { "type": "string", "nullable": true }, "hostedInvoiceUrl": { "type": "string", "nullable": true }, "stripeSubscriptionId": { "type": "string", "nullable": true }, "message": { "type": "string" } }, "required": [ "recoverable", "textVerifiedState", "amountDue", "invoiceId", "hostedInvoiceUrl", "stripeSubscriptionId", "message" ], "additionalProperties": false } } } } } } }, "/v1/billing/numbers/{numberId}/recover": { "post": { "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "paymentMethodId": { "type": "string" } }, "additionalProperties": false } } } }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "numberId", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/notifications/endpoints/": { "get": { "responses": { "200": { "description": "Default Response" } } }, "post": { "responses": { "200": { "description": "Default Response" } } } }, "/v1/notifications/endpoints/{id}": { "get": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "patch": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "delete": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/notifications/endpoints/{id}/test": { "post": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/notifications/endpoints/{id}/set-default": { "post": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/notifications/endpoints/{id}/send-verification": { "post": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/notifications/endpoints/{id}/rotate-secret": { "post": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/notifications/rules/": { "get": { "responses": { "200": { "description": "Default Response" } } }, "post": { "responses": { "200": { "description": "Default Response" } } } }, "/v1/notifications/rules/{id}": { "get": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "patch": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } }, "delete": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/notifications/rules/batch": { "post": { "responses": { "200": { "description": "Default Response" } } } }, "/v1/notifications/rules/numbers-with-custom-rules": { "get": { "responses": { "200": { "description": "Default Response" } } } }, "/v1/notifications/attempts/": { "get": { "responses": { "200": { "description": "Default Response" } } } }, "/v1/notifications/attempts/{id}": { "get": { "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "responses": { "200": { "description": "Default Response" } } } }, "/v1/notifications/attempts/stats": { "get": { "responses": { "200": { "description": "Default Response" } } } }, "/v1/notifications/telegram/link-code": { "post": { "tags": [ "Notifications" ], "description": "Generate a one-time Telegram link code for the authenticated user", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "linkCode": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "botUsername": { "type": "string" } }, "required": [ "linkCode", "expiresAt", "botUsername" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "503": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } } } } }, "/v1/team/{numberId}/members": { "get": { "tags": [ "Team" ], "description": "List all team members for a number (owner only)", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "numberId", "required": true } ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "userId": { "type": "string" }, "email": { "type": "string" }, "name": { "type": "string", "nullable": true }, "role": { "type": "string", "enum": [ "OWNER", "VIEWER", "MANAGER" ] }, "grantedAt": { "type": "string", "format": "date-time" }, "isOwner": { "type": "boolean" } }, "required": [ "id", "userId", "email", "name", "role", "grantedAt", "isOwner" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } } } } }, "/v1/team/my-invitations": { "get": { "tags": [ "Team" ], "description": "Get all pending invitations for the current user", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "token": { "type": "string" }, "numberId": { "type": "string" }, "phoneNumber": { "type": "string" }, "role": { "type": "string", "enum": [ "VIEWER", "MANAGER" ] }, "inviterName": { "type": "string", "nullable": true }, "inviterEmail": { "type": "string" }, "invitedAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "isExpired": { "type": "boolean" } }, "required": [ "id", "token", "numberId", "phoneNumber", "role", "inviterName", "inviterEmail", "invitedAt", "expiresAt", "isExpired" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } } } } }, "/v1/team/invite-preview/{token}": { "get": { "tags": [ "Team" ], "description": "Get invitation preview without authentication", "parameters": [ { "schema": { "type": "string", "minLength": 32 }, "in": "path", "name": "token", "required": true } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "inviterName": { "type": "string", "nullable": true }, "inviterEmail": { "type": "string" }, "phoneNumber": { "type": "string" }, "role": { "type": "string", "enum": [ "VIEWER", "MANAGER" ] }, "invitedEmail": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "isExpired": { "type": "boolean" }, "acceptedAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "inviterName", "inviterEmail", "phoneNumber", "role", "invitedEmail", "expiresAt", "isExpired", "acceptedAt" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } } } } }, "/v1/team/invite": { "post": { "tags": [ "Team" ], "description": "Invite a team member to a number (owner only)", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "numberId": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "role": { "type": "string", "enum": [ "VIEWER", "MANAGER" ], "default": "VIEWER" } }, "required": [ "numberId", "email" ], "additionalProperties": false } } }, "required": true }, "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "invitationId": { "type": "string" }, "message": { "type": "string" } }, "required": [ "success", "invitationId", "message" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "429": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } } } } }, "/v1/team/accept-invite": { "post": { "tags": [ "Team" ], "description": "Accept a team invitation", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "minLength": 32 } }, "required": [ "token" ], "additionalProperties": false } } }, "required": true }, "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "numberId": { "type": "string" }, "message": { "type": "string" } }, "required": [ "success", "numberId", "message" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } } } } }, "/v1/team/decline-invite/{token}": { "delete": { "tags": [ "Team" ], "description": "Decline a team invitation by token", "parameters": [ { "schema": { "type": "string", "minLength": 32 }, "in": "path", "name": "token", "required": true } ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "success", "message" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } } } } }, "/v1/team/{numberId}/invitations": { "get": { "tags": [ "Team" ], "description": "List pending invitations for a number (owner only)", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "numberId", "required": true } ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "enum": [ "VIEWER", "MANAGER" ] }, "invitedAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "isExpired": { "type": "boolean" } }, "required": [ "id", "email", "role", "invitedAt", "expiresAt", "isExpired" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } } } } }, "/v1/team/{numberId}/members/{userId}": { "delete": { "tags": [ "Team" ], "description": "Remove a team member (owner only)", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "numberId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "userId", "required": true } ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "success", "message" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } } } } }, "/v1/team/{numberId}/members/{userId}/role": { "patch": { "tags": [ "Team" ], "description": "Update team member role (owner only)", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "VIEWER", "MANAGER" ] } }, "required": [ "role" ], "additionalProperties": false } } }, "required": true }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "numberId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "userId", "required": true } ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "success", "message" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } } } } }, "/v1/team/{numberId}/invitations/{invitationId}": { "delete": { "tags": [ "Team" ], "description": "Cancel a pending invitation (owner only)", "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "in": "path", "name": "numberId", "required": true }, { "schema": { "type": "string" }, "in": "path", "name": "invitationId", "required": true } ], "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "success", "message" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } } } } }, "/v1/enterprise/contracts": { "get": { "tags": [ "Enterprise" ], "description": "List enterprise contracts available to the authenticated user", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "companyName": { "type": "string" }, "status": { "type": "string" }, "complianceStatus": { "type": "string" }, "role": { "type": "string", "enum": [ "OWNER", "ADMIN", "MEMBER" ] }, "committedLineCount": { "type": "number" }, "filledLineCount": { "type": "number" }, "activeLineCount": { "type": "number" }, "trialEndsAt": { "type": "string", "format": "date-time", "nullable": true }, "paidThrough": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "cycles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "textVerifiedBillingCycleId": { "type": "string" }, "expectedLineCount": { "type": "number" }, "filledLineCount": { "type": "number" }, "activeLineCount": { "type": "number" }, "state": { "type": "string" }, "billingCycleEndsAt": { "type": "string", "format": "date-time", "nullable": true }, "lastSyncedAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "id", "textVerifiedBillingCycleId", "expectedLineCount", "filledLineCount", "activeLineCount", "state", "billingCycleEndsAt", "lastSyncedAt" ], "additionalProperties": false } } }, "required": [ "id", "companyName", "status", "complianceStatus", "role", "committedLineCount", "filledLineCount", "activeLineCount", "trialEndsAt", "paidThrough", "createdAt", "cycles" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } } } } }, "/v1/backorders": { "get": { "tags": [ "Backorders" ], "description": "Get user's backordered number orders", "security": [ { "bearerAuth": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "subscriptionId": { "type": "string", "format": "uuid" }, "stripeSubscriptionId": { "type": "string" }, "areaCodePref": { "type": "string", "nullable": true }, "backorderState": { "type": "string", "enum": [ "BACKORDERED", "CUSTOM_BACKORDER" ] }, "backorderAreaCodeKey": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "priceBaseId": { "type": "string" }, "customBackorder": { "type": "object", "properties": { "status": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "status", "createdAt" ], "additionalProperties": false } }, "required": [ "subscriptionId", "stripeSubscriptionId", "areaCodePref", "backorderState", "backorderAreaCodeKey", "createdAt", "priceBaseId" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } }, "401": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "500": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } } } } }, "/v1/api-keys": { "get": { "tags": [ "API Keys" ], "description": "List all API keys for the authenticated user", "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "lastUsedAt": { "type": "string", "format": "date-time", "nullable": true }, "lastUsedIp": { "type": "string", "nullable": true }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true }, "revokedAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "scopeType": { "type": "string", "enum": [ "PERSONAL", "ENTERPRISE_CONTRACT", "NUMBER_SET" ] }, "enterpriseContractId": { "type": "string", "nullable": true }, "enterpriseContractName": { "type": "string", "nullable": true }, "numberScopeCount": { "type": "number" }, "numberScopes": { "type": "array", "items": { "type": "object", "properties": { "numberId": { "type": "string" }, "phoneNumber": { "type": "string" }, "serviceName": { "type": "string", "nullable": true } }, "required": [ "numberId", "phoneNumber", "serviceName" ], "additionalProperties": false } }, "capabilities": { "type": "array", "items": { "type": "string", "enum": [ "sms:reply" ] } } }, "required": [ "id", "name", "prefix", "lastUsedAt", "lastUsedIp", "expiresAt", "revokedAt", "createdAt", "scopeType", "enterpriseContractId", "enterpriseContractName", "numberScopeCount", "numberScopes", "capabilities" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } } } }, "post": { "tags": [ "API Keys" ], "description": "Create a new API key. The full key is returned ONCE — store it securely.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64 }, "expiresAt": { "type": "string", "format": "date-time" }, "scopeType": { "type": "string", "enum": [ "PERSONAL", "ENTERPRISE_CONTRACT", "NUMBER_SET" ] }, "enterpriseContractId": { "type": "string" }, "numberIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 1000 }, "capabilities": { "type": "array", "items": { "type": "string", "enum": [ "sms:reply" ] }, "maxItems": 10, "default": [] } }, "required": [ "name" ], "additionalProperties": false } } }, "required": true }, "security": [ { "sessionCookie": [] } ], "responses": { "201": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "scopeType": { "type": "string", "enum": [ "PERSONAL", "ENTERPRISE_CONTRACT", "NUMBER_SET" ] }, "enterpriseContractId": { "type": "string", "nullable": true }, "enterpriseContractName": { "type": "string", "nullable": true }, "numberScopeCount": { "type": "number" }, "numberScopes": { "type": "array", "items": { "type": "object", "properties": { "numberId": { "type": "string" }, "phoneNumber": { "type": "string" }, "serviceName": { "type": "string", "nullable": true } }, "required": [ "numberId", "phoneNumber", "serviceName" ], "additionalProperties": false } }, "capabilities": { "type": "array", "items": { "type": "string", "enum": [ "sms:reply" ] } } }, "required": [ "key", "id", "name", "prefix", "expiresAt", "createdAt", "scopeType", "enterpriseContractId", "enterpriseContractName", "numberScopeCount", "numberScopes", "capabilities" ], "additionalProperties": false } } } }, "400": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "403": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } }, "409": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } } } } }, "/v1/api-keys/{id}": { "delete": { "tags": [ "API Keys" ], "description": "Revoke an API key. This cannot be undone.", "parameters": [ { "schema": { "type": "string" }, "in": "path", "name": "id", "required": true } ], "security": [ { "sessionCookie": [] } ], "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "success", "message" ], "additionalProperties": false } } } }, "404": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "additionalProperties": false } } } } } } }, "/v1/system/stock-status": { "get": { "tags": [ "System" ], "description": "Whether new number subscriptions are currently being accepted", "responses": { "200": { "description": "Default Response", "content": { "application/json": { "schema": { "type": "object", "properties": { "closed": { "type": "boolean" }, "message": { "type": "string" }, "reason": { "type": "string", "enum": [ "MANUAL_CLOSED", "POOL_EMPTY" ] }, "backorderAvailable": { "type": "boolean" } }, "required": [ "closed" ], "additionalProperties": false } } } } } } } }, "servers": [ { "url": "https://api.joltsms.com", "description": "Current environment" } ], "security": [ { "bearerAuth": [] }, { "apiKey": [] }, { "sessionCookie": [] } ], "tags": [ { "name": "Numbers", "description": "Phone number management" }, { "name": "Messages", "description": "SMS message operations" }, { "name": "API Keys", "description": "API key management" }, { "name": "Billing", "description": "Billing and subscription operations" }, { "name": "Notifications", "description": "Notification endpoint management" }, { "name": "Team", "description": "Team access and collaboration" }, { "name": "Enterprise", "description": "Enterprise contract operations" }, { "name": "Backorders", "description": "Backordered number operations" }, { "name": "System", "description": "Authenticated system status endpoints" } ] }