{ "openapi": "3.1.0", "info": { "title": "MirageTEL partner API", "version": "current", "description": "The API of a MirageTEL partner account: rate cards, the balance, signed webhooks and the event log, in a live and a sandbox environment. Authenticate with your key in X-Api-Key (mtp_live_… or mtp_test_…). Amounts are integer cents. Reference and guides: https://miragetel.com/partners/developers/", "contact": { "name": "MirageTEL partners", "email": "partners@miragetel.com", "url": "https://miragetel.com/partners/" } }, "servers": [ { "url": "https://miragetel.com" } ], "security": [ { "partnerKey": [] } ], "tags": [ { "name": "partner", "description": "The partner API — /api/v1/partner/*, for a partner's own software (X-Api-Key mtp_live_… or mtp_test_…) and its panel. Errors carry error.code, error.message and requestId." } ], "paths": { "/api/v1/partner/account": { "get": { "operationId": "partnerAccount", "tags": [ "partner" ], "summary": "The partner account, its services and what this key or person may do", "description": "Partner API. Authenticated by a partner key in `X-Api-Key` (`mtp_live_…`, `mtp_test_…`) or by the\nsession of one of the partner's people (the panel) with `X-Partner-Environment`. Errors are\n`{ \"error\": { \"code\", \"message\" }, \"requestId\" }`; every response carries `X-Request-Id`. 600 requests a minute\nper key or person. Scope `account:read`.\n", "security": [ { "partnerKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/PartnerEnvironment" } ], "responses": { "200": { "description": "The account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerAccount" } } } }, "401": { "$ref": "#/components/responses/PartnerUnauthorized" }, "403": { "$ref": "#/components/responses/PartnerForbidden" }, "429": { "$ref": "#/components/responses/PartnerRateLimited" } } }, "patch": { "operationId": "partnerUpdateAccount", "tags": [ "partner" ], "summary": "Set the low-balance alert line", "description": "Scope `wallet:write`. A debit that takes the live balance below `lowBalanceAlertMinor` sends `balance.low` (and a mail\nto your admins and finance people) once per crossing. 0 switches it off. USD 50 by default.\n", "security": [ { "partnerKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/PartnerEnvironment" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "lowBalanceAlertMinor" ], "properties": { "lowBalanceAlertMinor": { "$ref": "#/components/schemas/MinorUnits" } } } } } }, "responses": { "200": { "description": "The account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerAccount" } } } }, "400": { "description": "INVALID_AMOUNT or NOTHING_TO_CHANGE" }, "401": { "$ref": "#/components/responses/PartnerUnauthorized" }, "403": { "$ref": "#/components/responses/PartnerForbidden" } } } }, "/api/v1/partner/balance": { "get": { "operationId": "partnerBalance", "tags": [ "partner" ], "summary": "The prepaid balance — live, or the sandbox's virtual one", "description": "Scope `wallet:read`. A balance holds at most USD 2,000. In the sandbox the balance is virtual.", "security": [ { "partnerKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/PartnerEnvironment" } ], "responses": { "200": { "description": "The balance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerBalance" } } } }, "401": { "$ref": "#/components/responses/PartnerUnauthorized" }, "403": { "$ref": "#/components/responses/PartnerForbidden" } } } }, "/api/v1/partner/transactions": { "get": { "operationId": "partnerTransactions", "tags": [ "partner" ], "summary": "Money in and out of the balance, newest first", "description": "Scope `wallet:read`. Page with `before` (the last id you have).", "security": [ { "partnerKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/PartnerEnvironment" }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "A page of transactions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerTransactionPage" } } } }, "400": { "description": "INVALID_CURSOR" }, "401": { "$ref": "#/components/responses/PartnerUnauthorized" }, "403": { "$ref": "#/components/responses/PartnerForbidden" } } } }, "/api/v1/partner/topups": { "post": { "operationId": "partnerCreateTopup", "tags": [ "partner" ], "summary": "Add funds to the balance — card, USDT or bank transfer", "description": "Scope `wallet:write`. Live: a payment request on your account and what you need to pay it — `checkoutUrl` (card),\n`usdt` (the exact amount to send and our TRON address; the amount identifies your payment), or `bank` (the details\nand the reference to quote). Credited when the money arrives, with a receipt in your company's name and a\n`topup.completed` event. The balance holds at most USD 2,000 (counting top-ups not yet paid): above it, 409.\nSandbox: the play-money balance goes up at once.\n", "security": [ { "partnerKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/PartnerEnvironment" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "method", "amountMinor" ], "properties": { "method": { "type": "string", "enum": [ "card", "usdt_trc20", "bank" ] }, "amountMinor": { "$ref": "#/components/schemas/MinorUnits" } } } } } }, "responses": { "201": { "description": "The top-up and how to pay it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerTopup" } } } }, "400": { "description": "INVALID_METHOD, INVALID_AMOUNT or IDEMPOTENCY_KEY_REQUIRED" }, "401": { "$ref": "#/components/responses/PartnerUnauthorized" }, "403": { "$ref": "#/components/responses/PartnerForbidden" }, "409": { "description": "BALANCE_CAP_EXCEEDED (error.details.headroomMinor says what fits) or an Idempotency-Key conflict" }, "502": { "description": "PAYMENT_PROVIDER_ERROR — the card page could not be opened" }, "503": { "description": "METHOD_UNAVAILABLE or AMOUNT_UNAVAILABLE" } } }, "get": { "operationId": "partnerListTopups", "tags": [ "partner" ], "summary": "Your top-ups, newest first, with the room left under the cap", "description": "Scope `wallet:read`.", "security": [ { "partnerKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/PartnerEnvironment" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "The top-ups.", "content": { "application/json": { "schema": { "type": "object", "properties": { "environment": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PartnerTopup" } }, "capMinor": { "$ref": "#/components/schemas/MinorUnits" }, "balanceMinor": { "$ref": "#/components/schemas/MinorUnits" }, "pendingMinor": { "$ref": "#/components/schemas/MinorUnits" }, "headroomMinor": { "$ref": "#/components/schemas/MinorUnits" } } } } } }, "401": { "$ref": "#/components/responses/PartnerUnauthorized" }, "403": { "$ref": "#/components/responses/PartnerForbidden" } } } }, "/api/v1/partner/topups/{id}": { "get": { "operationId": "partnerGetTopup", "tags": [ "partner" ], "summary": "One top-up and where it stands", "description": "Scope `wallet:read`.", "security": [ { "partnerKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/PartnerEnvironment" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The top-up.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerTopup" } } } }, "401": { "$ref": "#/components/responses/PartnerUnauthorized" }, "403": { "$ref": "#/components/responses/PartnerForbidden" }, "404": { "description": "NOT_FOUND" } } } }, "/api/v1/partner/topups/{id}/claim": { "post": { "operationId": "partnerClaimTopup", "tags": [ "partner" ], "summary": "I have paid — name the USDT transaction", "description": "Scope `wallet:write`. For a USDT top-up whose amount could not be matched (for example a wallet that converted the\nfigure): the transaction is read from the chain and every check of the automatic path applies before anything is\ncredited. What arrived is credited, rounded up to the cent; less than asked is settled by a person.\n", "security": [ { "partnerKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/PartnerEnvironment" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "txid" ], "properties": { "txid": { "type": "string", "description": "64 hex characters" } } } } } }, "responses": { "200": { "description": "Credited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerTopup" } } } }, "400": { "description": "INVALID_TXID" }, "401": { "$ref": "#/components/responses/PartnerUnauthorized" }, "403": { "$ref": "#/components/responses/PartnerForbidden" }, "404": { "description": "NOT_FOUND or NOT_FOUND_ON_CHAIN" }, "409": { "description": "REQUEST_NOT_PENDING, ALREADY_CREDITED, TOO_RECENT, AMOUNT_TOO_LOW, NOT_USDT, NOT_SENT_TO_US, USDT_ONLY or LIVE_ONLY" }, "503": { "description": "CHAIN_UNREACHABLE or NO_BUSINESS_ADDRESS" } } } }, "/api/v1/partner/receipts": { "get": { "operationId": "partnerReceipts", "tags": [ "partner" ], "summary": "Receipts for every top-up, issued to your company", "description": "Scope `wallet:read`. `url` opens the document without signing in.", "security": [ { "partnerKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/PartnerEnvironment" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "The receipts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "environment": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "kind": { "type": "string" }, "status": { "type": "string" }, "totalMinor": { "$ref": "#/components/schemas/MinorUnits" }, "currency": { "type": "string" }, "issuedAt": { "type": "string", "format": "date-time" }, "url": { "type": "string" } } } } } } } } }, "401": { "$ref": "#/components/responses/PartnerUnauthorized" }, "403": { "$ref": "#/components/responses/PartnerForbidden" } } } }, "/api/v1/partner/statements": { "get": { "operationId": "partnerStatements", "tags": [ "partner" ], "summary": "Monthly statements — what was charged, by category", "description": "Scope `wallet:read`. A statement lists charges only; money paid in is on the receipts.", "security": [ { "partnerKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/PartnerEnvironment" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 120, "default": 24 } } ], "responses": { "200": { "description": "The statements.", "content": { "application/json": { "schema": { "type": "object", "properties": { "environment": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "401": { "$ref": "#/components/responses/PartnerUnauthorized" }, "403": { "$ref": "#/components/responses/PartnerForbidden" } } } }, "/api/v1/partner/esims/packages": { "get": { "operationId": "partnerEsimPackages", "tags": [ "partner" ], "summary": "Every eSIM package you can buy, at your price", "description": "Scope `esims:read`. The same list as GET /partner/rates/esim: `available` says whether it can be bought this minute.\n", "security": [ { "partnerKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/PartnerEnvironment" }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "minLength": 2, "maxLength": 2 } } ], "responses": { "200": { "description": "The packages.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PartnerEsimRate" } }, "currency": { "type": "string" } } } } } }, "401": { "$ref": "#/components/responses/PartnerUnauthorized" }, "403": { "$ref": "#/components/responses/PartnerForbidden" } } } }, "/api/v1/partner/esims": { "post": { "operationId": "partnerBuyEsim", "tags": [ "partner" ], "summary": "Buy an eSIM for your customer, from your balance", "description": "Scope `esims:write`. Answers at once with the eSIM in `processing`; it becomes `issued` (or `failed`, nothing charged)\nwhen the operator answers — usually within seconds — and `esim.issued` carries the activation code, the iPhone\ninstall link and the QR path. `reference` is your own id for the sale, unique on your account. Needs the eSIM\nservice switched on for your account. Sandbox: issued at once with a test activation code; play money only.\n", "security": [ { "partnerKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/PartnerEnvironment" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "packageId" ], "properties": { "packageId": { "type": "integer" }, "reference": { "type": "string", "maxLength": 100 }, "activationDate": { "type": "string", "format": "date", "description": "Only for a plan that needs one." } } } } } }, "responses": { "201": { "description": "The eSIM.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerEsim" } } } }, "400": { "description": "INVALID_PACKAGE, INVALID_REFERENCE, INVALID_ACTIVATION_DATE, ACTIVATION_DATE_REQUIRED or IDEMPOTENCY_KEY_REQUIRED" }, "401": { "$ref": "#/components/responses/PartnerUnauthorized" }, "402": { "description": "INSUFFICIENT_BALANCE" }, "403": { "description": "SERVICE_NOT_ACTIVE, PRODUCT_NOT_IN_CATALOGUE, MONTHLY_CAP_REACHED, or a scope or account refusal" }, "404": { "description": "PACKAGE_NOT_FOUND (sandbox)" }, "409": { "description": "REFERENCE_IN_USE, PACKAGE_NOT_AVAILABLE, PRICE_ON_HOLD or an Idempotency-Key conflict" } } }, "get": { "operationId": "partnerListEsims", "tags": [ "partner" ], "summary": "Your eSIMs, newest first", "description": "Scope `esims:read`. Filter by `status` or by your `reference`.\n", "security": [ { "partnerKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/PartnerEnvironment" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "processing", "issued", "installed", "used_up", "expired", "closed", "cancelled", "failed" ] } }, { "name": "reference", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "The eSIMs.", "content": { "application/json": { "schema": { "type": "object", "properties": { "environment": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PartnerEsim" } } } } } } }, "401": { "$ref": "#/components/responses/PartnerUnauthorized" }, "403": { "$ref": "#/components/responses/PartnerForbidden" } } } }, "/api/v1/partner/esims/{id}": { "get": { "operationId": "partnerGetEsim", "tags": [ "partner" ], "summary": "One eSIM — its state, install data and, where the operator reports it, usage", "description": "Scope `esims:read`. `usage.reported` is false where the operator does not report consumption: only the allowance is\ngiven then, never an estimate.\n", "security": [ { "partnerKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/PartnerEnvironment" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The eSIM.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerEsim" } } } }, "401": { "$ref": "#/components/responses/PartnerUnauthorized" }, "403": { "$ref": "#/components/responses/PartnerForbidden" }, "404": { "description": "NOT_FOUND" } } } }, "/api/v1/partner/esims/{id}/qr.png": { "get": { "operationId": "partnerEsimQr", "tags": [ "partner" ], "summary": "The activation QR code, as a PNG", "description": "Scope `esims:read`. Generated here from the activation code; never by a third party.\n", "security": [ { "partnerKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/PartnerEnvironment" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The QR code.", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/PartnerUnauthorized" }, "403": { "$ref": "#/components/responses/PartnerForbidden" }, "404": { "description": "NOT_FOUND" }, "409": { "description": "NOT_ISSUED" } } } }, "/api/v1/partner/esims/{id}/topup-options": { "get": { "operationId": "partnerEsimTopupOptions", "tags": [ "partner" ], "summary": "What can be added to this eSIM, at your price", "description": "Scope `esims:read`.\n", "security": [ { "partnerKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/PartnerEnvironment" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The options.", "content": { "application/json": { "schema": { "type": "object", "properties": { "environment": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "packageCode": { "type": "string" }, "name": { "type": "string" }, "dataMb": { "type": [ "integer", "null" ] }, "validityDays": { "type": [ "integer", "null" ] }, "priceMinor": { "$ref": "#/components/schemas/MinorUnits" } } } } } } } } }, "401": { "$ref": "#/components/responses/PartnerUnauthorized" }, "403": { "$ref": "#/components/responses/PartnerForbidden" }, "404": { "description": "NOT_FOUND" }, "409": { "description": "NOT_ISSUED, TOPUP_NOT_SUPPORTED or TOPUP_WINDOW_CLOSED" } } } }, "/api/v1/partner/esims/{id}/topups": { "post": { "operationId": "partnerEsimTopup", "tags": [ "partner" ], "summary": "Add data to an eSIM, from your balance", "description": "Scope `esims:write`. Same eSIM, no reinstall. `esim.topup.completed` (or `esim.topup.failed`, nothing charged) follows.\n", "security": [ { "partnerKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/PartnerEnvironment" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "packageCode" ], "properties": { "packageCode": { "type": "string" } } } } } }, "responses": { "201": { "description": "The top-up.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "esimId": { "type": "string" }, "environment": { "type": "string" }, "packageCode": { "type": "string" }, "priceMinor": { "$ref": "#/components/schemas/MinorUnits" }, "status": { "type": "string", "enum": [ "processing", "completed", "under_review" ] } } } } } }, "400": { "description": "INVALID_TOPUP_OPTION or IDEMPOTENCY_KEY_REQUIRED" }, "401": { "$ref": "#/components/responses/PartnerUnauthorized" }, "402": { "description": "INSUFFICIENT_FUNDS" }, "403": { "$ref": "#/components/responses/PartnerForbidden" }, "404": { "description": "NOT_FOUND" }, "409": { "description": "NOT_ISSUED, TOPUP_NOT_SUPPORTED, TOPUP_WINDOW_CLOSED, PRICE_ON_HOLD or ESIM_TEMPORARILY_UNAVAILABLE" }, "503": { "description": "SUPPLY_TEMPORARILY_UNAVAILABLE" } } } }, "/api/v1/partner/esims/{id}/cancel": { "post": { "operationId": "partnerCancelEsim", "tags": [ "partner" ], "summary": "Cancel an eSIM — refunded to your balance where the operator refunds it", "description": "Scope `esims:write`. `refundedMinor` is what came back to your balance; `esim.cancelled` follows.\n", "security": [ { "partnerKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/PartnerEnvironment" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The eSIM", "cancelled.": null, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerEsim" } } } }, "401": { "$ref": "#/components/responses/PartnerUnauthorized" }, "403": { "$ref": "#/components/responses/PartnerForbidden" }, "404": { "description": "NOT_FOUND" }, "409": { "description": "CANCEL_REJECTED or NOT_ISSUED" } } } }, "/api/v1/partner/numbers/areas": { "get": { "operationId": "partnerNumberAreas", "tags": [ "partner" ], "summary": "The areas of a country, at your price", "description": "Scope `numbers:read`. Monthly and setup price of one number in each area, and whether the country registers the user of\na number before it works.\n", "security": [ { "partnerKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/PartnerEnvironment" }, { "name": "country", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2, "maxLength": 2 } }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } } ], "responses": { "200": { "description": "The areas.", "content": { "application/json": { "schema": { "type": "object", "properties": { "country": { "type": "string" }, "currency": { "type": "string" }, "total": { "type": "integer" }, "data": { "type": "array", "items": { "type": "object", "properties": { "areaId": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "prefix": { "type": [ "string", "null" ] }, "region": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "monthlyMinor": { "$ref": "#/components/schemas/MinorUnits" }, "setupMinor": { "$ref": "#/components/schemas/MinorUnits" }, "registrationRequired": { "type": "boolean" }, "textsIn": { "type": "boolean" } } } } } } } } }, "400": { "description": "INVALID_COUNTRY" }, "401": { "$ref": "#/components/responses/PartnerUnauthorized" }, "403": { "$ref": "#/components/responses/PartnerForbidden" }, "404": { "description": "COUNTRY_NOT_SOLD" } } } }, "/api/v1/partner/numbers": { "post": { "operationId": "partnerBuyNumber", "tags": [ "partner" ], "summary": "Buy a phone number for your customer, from your balance", "description": "Scope `numbers:write`. Needs the numbers service switched on for your account and your company’s acceptable use policy.\nThe first month (and a setup fee where the area has one) is paid at once. In a country that registers the user, the\nnumber waits for its registration (`number.registration.required`, then POST …/registration). `endUserId` names whose line\nit is; `reference` is your own id. Sandbox: a +999 number at once, play money.\n", "security": [ { "partnerKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/PartnerEnvironment" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "country", "areaId" ], "properties": { "country": { "type": "string" }, "areaId": { "type": "string" }, "reference": { "type": "string", "maxLength": 100 }, "endUserId": { "type": "string", "format": "uuid" } } } } } }, "responses": { "201": { "description": "The number.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerNumber" } } } }, "400": { "description": "INVALID_COUNTRY, INVALID_AREA, INVALID_REFERENCE or IDEMPOTENCY_KEY_REQUIRED" }, "401": { "$ref": "#/components/responses/PartnerUnauthorized" }, "402": { "description": "INSUFFICIENT_FUNDS" }, "403": { "description": "SERVICE_NOT_ACTIVE, AUP_REQUIRED, NUMBER_COUNTRY_SANCTIONED, or a scope or account refusal" }, "404": { "description": "COUNTRY_NOT_SOLD or END_USER_NOT_FOUND" }, "409": { "description": "REFERENCE_IN_USE, AREA_NOT_AVAILABLE or an Idempotency-Key conflict" }, "502": { "description": "NUMBER_ORDER_FAILED — nothing was charged" } } }, "get": { "operationId": "partnerListNumbers", "tags": [ "partner" ], "summary": "Your numbers, newest first", "description": "Scope `numbers:read`.\n", "security": [ { "partnerKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/PartnerEnvironment" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "reference", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500 } } ], "responses": { "200": { "description": "The numbers.", "content": { "application/json": { "schema": { "type": "object", "properties": { "environment": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PartnerNumber" } } } } } } }, "401": { "$ref": "#/components/responses/PartnerUnauthorized" }, "403": { "$ref": "#/components/responses/PartnerForbidden" } } } }, "/api/v1/partner/numbers/{id}": { "get": { "operationId": "partnerGetNumber", "tags": [ "partner" ], "summary": "One number", "description": "Scope `numbers:read`.\n", "security": [ { "partnerKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/PartnerEnvironment" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The number.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerNumber" } } } }, "401": { "$ref": "#/components/responses/PartnerUnauthorized" }, "403": { "$ref": "#/components/responses/PartnerForbidden" }, "404": { "description": "NOT_FOUND" } } }, "patch": { "operationId": "partnerRouteNumber", "tags": [ "partner" ], "summary": "Where calls to the number ring", "description": "Scope `numbers:write`. `routing.to`: `trunk` (with `trunkId`) or `none`.\n", "security": [ { "partnerKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/PartnerEnvironment" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "routing" ], "properties": { "routing": { "type": "object", "properties": { "to": { "type": "string", "enum": [ "trunk", "none" ] }, "trunkId": { "type": "string" } } } } } } } }, "responses": { "200": { "description": "The number.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerNumber" } } } }, "400": { "description": "INVALID_ROUTING" }, "401": { "$ref": "#/components/responses/PartnerUnauthorized" }, "403": { "$ref": "#/components/responses/PartnerForbidden" }, "404": { "description": "NOT_FOUND" } } }, "delete": { "operationId": "partnerCancelNumber", "tags": [ "partner" ], "summary": "Cancel a number at the end of its paid month", "description": "Scope `numbers:write`. `number.cancelled` follows.\n", "security": [ { "partnerKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/PartnerEnvironment" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The number.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerNumber" } } } }, "401": { "$ref": "#/components/responses/PartnerUnauthorized" }, "403": { "$ref": "#/components/responses/PartnerForbidden" }, "404": { "description": "NOT_FOUND" }, "409": { "description": "NOT_CANCELLABLE" } } } }, "/api/v1/partner/numbers/{id}/registration": { "get": { "operationId": "partnerNumberRegistrationForm", "tags": [ "partner" ], "summary": "What the country asks to register the number’s user", "description": "Scope `numbers:read`. The fields and documents the operator asks for.\n", "security": [ { "partnerKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/PartnerEnvironment" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The form.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/PartnerUnauthorized" }, "403": { "$ref": "#/components/responses/PartnerForbidden" }, "404": { "description": "NOT_FOUND" } } }, "post": { "operationId": "partnerSubmitNumberRegistration", "tags": [ "partner" ], "summary": "File the registration", "description": "Scope `numbers:write`. `identityType`, `identity` and `address` fields as the form asks — filled from the end user you gave\nthe number when you leave them out — and `documents` (base64). The verdict arrives as `number.registration.approved` or\n`…rejected` (with what to correct).\n", "security": [ { "partnerKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/PartnerEnvironment" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "identityType": { "type": "string", "enum": [ "personal", "business" ] }, "identity": { "type": "object", "additionalProperties": true }, "address": { "type": "object", "additionalProperties": true }, "serviceDescription": { "type": "string" }, "documents": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "responses": { "200": { "description": "Filed.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "A field or a document is missing or invalid" }, "401": { "$ref": "#/components/responses/PartnerUnauthorized" }, "403": { "$ref": "#/components/responses/PartnerForbidden" }, "404": { "description": "NOT_FOUND" }, "409": { "description": "NO_REGISTRATION or LIVE_ONLY" } } } }, "/api/v1/partner/end-users": { "get": { "operationId": "partnerListEndUsers", "tags": [ "partner" ], "summary": "Your end users", "description": "Scope `end_users:read`. What a registration needs is held encrypted and never read back in full.\n", "security": [ { "partnerKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/PartnerEnvironment" }, { "name": "reference", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500 } } ], "responses": { "200": { "description": "The end users.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PartnerEndUser" } } } } } } }, "401": { "$ref": "#/components/responses/PartnerUnauthorized" }, "403": { "$ref": "#/components/responses/PartnerForbidden" } } }, "post": { "operationId": "partnerCreateEndUser", "tags": [ "partner" ], "summary": "Record an end user — the identity a country registers a number to", "description": "Scope `end_users:write`. Only what a registration asks for; stored encrypted, filed with the operator, read by nobody else.\n", "security": [ { "partnerKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/PartnerEnvironment" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "identityType", "name" ], "properties": { "identityType": { "type": "string", "enum": [ "personal", "business" ] }, "name": { "type": "string", "maxLength": 200 }, "country": { "type": "string" }, "reference": { "type": "string", "maxLength": 100 }, "identity": { "type": "object", "additionalProperties": true }, "address": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "201": { "description": "The end user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerEndUser" } } } }, "400": { "description": "INVALID_IDENTITY_TYPE, INVALID_NAME, INVALID_COUNTRY or INVALID_REFERENCE" }, "401": { "$ref": "#/components/responses/PartnerUnauthorized" }, "403": { "$ref": "#/components/responses/PartnerForbidden" }, "409": { "description": "REFERENCE_IN_USE" } } } }, "/api/v1/partner/end-users/{id}": { "get": { "operationId": "partnerGetEndUser", "tags": [ "partner" ], "summary": "One end user", "description": "Scope `end_users:read`.\n", "security": [ { "partnerKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/PartnerEnvironment" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The end user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerEndUser" } } } }, "401": { "$ref": "#/components/responses/PartnerUnauthorized" }, "403": { "$ref": "#/components/responses/PartnerForbidden" }, "404": { "description": "END_USER_NOT_FOUND" } } }, "patch": { "operationId": "partnerUpdateEndUser", "tags": [ "partner" ], "summary": "Correct an end user", "description": "Scope `end_users:write`. `end_user.updated` follows.\n", "security": [ { "partnerKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/PartnerEnvironment" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "identity": { "type": "object", "additionalProperties": true }, "address": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "The end user.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerEndUser" } } } }, "401": { "$ref": "#/components/responses/PartnerUnauthorized" }, "403": { "$ref": "#/components/responses/PartnerForbidden" }, "404": { "description": "END_USER_NOT_FOUND" } } }, "delete": { "operationId": "partnerDeleteEndUser", "tags": [ "partner" ], "summary": "Delete an end user (its fields are erased)", "description": "Scope `end_users:write`. Refused while the end user holds a number.\n", "security": [ { "partnerKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/PartnerEnvironment" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/PartnerUnauthorized" }, "403": { "$ref": "#/components/responses/PartnerForbidden" }, "404": { "description": "END_USER_NOT_FOUND" }, "409": { "description": "END_USER_HAS_NUMBERS" } } } }, "/api/v1/partner/trunks": { "get": { "operationId": "partnerListTrunks", "tags": [ "partner" ], "summary": "Your SIP trunks, with today’s use", "description": "Scope `trunks:read`.\n", "security": [ { "partnerKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/PartnerEnvironment" } ], "responses": { "200": { "description": "The trunks.", "content": { "application/json": { "schema": { "type": "object", "properties": { "environment": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "connection": { "type": "object", "additionalProperties": true } } } } } }, "401": { "$ref": "#/components/responses/PartnerUnauthorized" }, "403": { "$ref": "#/components/responses/PartnerForbidden" } } }, "post": { "operationId": "partnerCreateTrunk", "tags": [ "partner" ], "summary": "Connect a phone system — the password is shown once", "description": "Scope `trunks:write`. Needs outbound calling switched on for your account and `acceptAup: true` with the current `aupVersion`.\nMinutes are paid from your balance at your rate card (GET /partner/rates/voice); `maxChannels` and `dailyLimitMinor` cap it.\n", "security": [ { "partnerKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/PartnerEnvironment" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "acceptAup", "aupVersion" ], "properties": { "name": { "type": "string", "maxLength": 60 }, "maxChannels": { "type": "integer", "minimum": 1, "maximum": 500 }, "dailyLimitMinor": { "oneOf": [ { "$ref": "#/components/schemas/MinorUnits" }, { "type": "null" } ] }, "cliMode": { "type": "string", "enum": [ "fixed", "random" ] }, "cliNumberId": { "type": "string" }, "acceptAup": { "type": "boolean" }, "aupVersion": { "type": "string" } } } } } }, "responses": { "201": { "description": "The trunk and its password.", "content": { "application/json": { "schema": { "type": "object", "properties": { "trunk": { "type": "object", "additionalProperties": true }, "sipPassword": { "type": "string" }, "shownOnce": { "type": "boolean" }, "environment": { "type": "string" } } } } } }, "400": { "description": "AUP_NOT_ACCEPTED, INVALID_NAME, INVALID_CHANNELS, INVALID_DAILY_LIMIT or CLI_REQUIRED" }, "401": { "$ref": "#/components/responses/PartnerUnauthorized" }, "403": { "description": "SERVICE_NOT_ACTIVE, or a scope, account or compliance refusal" }, "409": { "description": "NO_NUMBER, NO_CREDIT, AUP_VERSION_CHANGED or an Idempotency-Key conflict" } } } }, "/api/v1/partner/trunks/{id}": { "patch": { "operationId": "partnerUpdateTrunk", "tags": [ "partner" ], "summary": "Change a trunk’s name, lines, daily cap, caller ID or state", "description": "Scope `trunks:write`.\n", "security": [ { "partnerKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/PartnerEnvironment" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "maxChannels": { "type": "integer" }, "dailyLimitMinor": { "oneOf": [ { "$ref": "#/components/schemas/MinorUnits" }, { "type": "null" } ] }, "cliMode": { "type": "string" }, "cliNumberId": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "disabled" ] } } } } } }, "responses": { "200": { "description": "The trunk.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "An invalid field" }, "401": { "$ref": "#/components/responses/PartnerUnauthorized" }, "403": { "$ref": "#/components/responses/PartnerForbidden" }, "404": { "description": "NOT_FOUND" } } }, "delete": { "operationId": "partnerDeleteTrunk", "tags": [ "partner" ], "summary": "Delete a trunk", "description": "Scope `trunks:write`. Its numbers stop ringing it.\n", "security": [ { "partnerKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/PartnerEnvironment" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/PartnerUnauthorized" }, "403": { "$ref": "#/components/responses/PartnerForbidden" }, "404": { "description": "NOT_FOUND" } } } }, "/api/v1/partner/trunks/{id}/status": { "get": { "operationId": "partnerTrunkStatus", "tags": [ "partner" ], "summary": "Whether the phone system is registered, and today’s calls", "description": "Scope `trunks:read`.\n", "security": [ { "partnerKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/PartnerEnvironment" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The status.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/PartnerUnauthorized" }, "403": { "$ref": "#/components/responses/PartnerForbidden" }, "404": { "description": "NOT_FOUND" } } } }, "/api/v1/partner/trunks/{id}/rotate-password": { "post": { "operationId": "partnerRotateTrunkPassword", "tags": [ "partner" ], "summary": "A new SIP password — shown once", "description": "Scope `trunks:write`. The old one stops working at once.\n", "security": [ { "partnerKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/PartnerEnvironment" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The new password.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "$ref": "#/components/responses/PartnerUnauthorized" }, "403": { "$ref": "#/components/responses/PartnerForbidden" }, "404": { "description": "NOT_FOUND" } } } }, "/api/v1/partner/calls": { "get": { "operationId": "partnerCalls", "tags": [ "partner" ], "summary": "Calls on your numbers and trunks, with what each was charged", "description": "Scope `calls:read`. Newest first; `before` pages back.\n", "security": [ { "partnerKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/PartnerEnvironment" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200 } }, { "name": "before", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "filter", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "all", "attempts", "charged" ] } } ], "responses": { "200": { "description": "The calls.", "content": { "application/json": { "schema": { "type": "object", "properties": { "environment": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "month": { "type": "object", "additionalProperties": true } } } } } }, "400": { "description": "INVALID_FILTER or INVALID_BEFORE" }, "401": { "$ref": "#/components/responses/PartnerUnauthorized" }, "403": { "$ref": "#/components/responses/PartnerForbidden" } } } }, "/api/v1/partner/texts": { "get": { "operationId": "partnerTexts", "tags": [ "partner" ], "summary": "Texts sent and received on your numbers", "description": "Scope `sms:read`.\n", "security": [ { "partnerKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/PartnerEnvironment" }, { "name": "numberId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500 } } ], "responses": { "200": { "description": "The texts.", "content": { "application/json": { "schema": { "type": "object", "properties": { "environment": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "401": { "$ref": "#/components/responses/PartnerUnauthorized" }, "403": { "$ref": "#/components/responses/PartnerForbidden" } } }, "post": { "operationId": "partnerSendText", "tags": [ "partner" ], "summary": "Send a text from one of your numbers", "description": "Scope `sms:write`. Needs outbound texts switched on for your account. Charged per part at your SMS rate card;\n`text.status.changed` follows the operator’s verdict.\n", "security": [ { "partnerKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/PartnerEnvironment" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "numberId", "to", "text" ], "properties": { "numberId": { "type": "string" }, "to": { "type": "string" }, "text": { "type": "string", "maxLength": 1000 } } } } } }, "responses": { "201": { "description": "Sent.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "INVALID_MESSAGE or INVALID_NUMBER" }, "401": { "$ref": "#/components/responses/PartnerUnauthorized" }, "402": { "description": "INSUFFICIENT_FUNDS" }, "403": { "description": "SERVICE_NOT_ACTIVE, DESTINATION_NOT_ALLOWED or DESTINATION_SANCTIONED" }, "409": { "description": "NO_ACTIVE_NUMBER, SMS_SENDING_NOT_OPEN or SMS_DESTINATION_NOT_PRICED" } } } }, "/api/v1/partner/sandbox/balance": { "post": { "operationId": "partnerSandboxBalance", "tags": [ "partner" ], "summary": "Set the sandbox's virtual balance", "description": "Only in the sandbox (`mtp_test_` key or `X-Partner-Environment test`). Up to USD 2,000. Nothing is money.", "security": [ { "partnerKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/PartnerEnvironment" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "balanceMinor": { "$ref": "#/components/schemas/MinorUnits" } } } } } }, "responses": { "200": { "description": "The new sandbox balance.", "content": { "application/json": { "schema": { "type": "object", "properties": { "balanceMinor": { "$ref": "#/components/schemas/MinorUnits" }, "currency": { "type": "string" }, "environment": { "type": "string" } } } } } }, "400": { "description": "INVALID_AMOUNT" }, "401": { "$ref": "#/components/responses/PartnerUnauthorized" }, "403": { "$ref": "#/components/responses/PartnerForbidden" }, "409": { "description": "SANDBOX_ONLY — this is a live key or the live environment" } } } }, "/api/v1/partner/rates/esim": { "get": { "operationId": "partnerRatesEsim", "tags": [ "partner" ], "summary": "Your price for every eSIM package", "description": "Scope `rates:read`. Your price from your partner agreement, in whole cents — the price a purchase charges. `available` is\nfalse while a package cannot be bought this minute (for example out of stock), with the reason in `hold`.\n`format=csv` downloads the same list.\n", "security": [ { "partnerKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/PartnerEnvironment" }, { "name": "country", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "csv" ] } } ], "responses": { "200": { "description": "The packages.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PartnerEsimRate" } }, "currency": { "type": "string" } } } }, "text/csv": { "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/PartnerUnauthorized" }, "403": { "$ref": "#/components/responses/PartnerForbidden" } } } }, "/api/v1/partner/rates/numbers": { "get": { "operationId": "partnerRatesNumbers", "tags": [ "partner" ], "summary": "Your from-price for a phone number in every country", "description": "Scope `rates:read`. The cheapest area's monthly and setup price; whether the country registers the user of a number.", "security": [ { "partnerKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/PartnerEnvironment" }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "csv" ] } } ], "responses": { "200": { "description": "One row per country.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PartnerNumberRate" } }, "currency": { "type": "string" } } } }, "text/csv": { "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/PartnerUnauthorized" }, "403": { "$ref": "#/components/responses/PartnerForbidden" } } } }, "/api/v1/partner/rates/voice": { "get": { "operationId": "partnerRatesVoice", "tags": [ "partner" ], "summary": "Your per-minute price to every destination (SIP trunk calls)", "description": "Scope `rates:read`. Billed 60/60. `q` filters by destination name or prefix; paged with `limit`/`offset`.", "security": [ { "partnerKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/PartnerEnvironment" }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 60 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "csv" ] } } ], "responses": { "200": { "description": "A page of destinations.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PartnerVoiceRate" } }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "currency": { "type": "string" }, "reason": { "type": [ "string", "null" ] } } } }, "text/csv": { "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/PartnerUnauthorized" }, "403": { "$ref": "#/components/responses/PartnerForbidden" } } } }, "/api/v1/partner/rates/sms": { "get": { "operationId": "partnerRatesSms", "tags": [ "partner" ], "summary": "Your price for one part of an outbound text, per destination", "description": "Scope `rates:read`. A destination we cannot price yet is listed as not open — never at a guess.", "security": [ { "partnerKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/PartnerEnvironment" }, { "name": "format", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "json", "csv" ] } } ], "responses": { "200": { "description": "One row per destination prefix.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PartnerSmsRate" } }, "currency": { "type": "string" } } } }, "text/csv": { "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/PartnerUnauthorized" }, "403": { "$ref": "#/components/responses/PartnerForbidden" } } } }, "/api/v1/partner/webhooks": { "get": { "operationId": "partnerListWebhooks", "tags": [ "partner" ], "summary": "Your webhooks in this environment", "description": "Scope `webhooks:manage`. Up to 5 per environment.", "security": [ { "partnerKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/PartnerEnvironment" } ], "responses": { "200": { "description": "The webhooks and the event types they can ask for.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PartnerWebhook" } }, "limit": { "type": "integer" }, "signatureHeader": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } } } } } } }, "401": { "$ref": "#/components/responses/PartnerUnauthorized" }, "403": { "$ref": "#/components/responses/PartnerForbidden" } } }, "post": { "operationId": "partnerCreateWebhook", "tags": [ "partner" ], "summary": "Add a webhook — the signing secret is shown once", "description": "Scope `webhooks:manage`. A public https address (resolved now and before every delivery; private addresses are\nrefused). `events`: exact types or families (`esim.*`), or `*`. Each delivery is signed with HMAC-SHA256 over\n`\".\"` in `X-MirageTel-Signature` and retried for 24 hours.\n", "security": [ { "partnerKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/PartnerEnvironment" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string", "maxLength": 120 } } } } } }, "responses": { "201": { "description": "Created", "with its secret.": null, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerWebhook" } } } }, "400": { "description": "INVALID_WEBHOOK_URL, WEBHOOK_NOT_PUBLIC, WEBHOOK_UNRESOLVED, UNKNOWN_EVENT or IDEMPOTENCY_KEY_REQUIRED" }, "401": { "$ref": "#/components/responses/PartnerUnauthorized" }, "403": { "$ref": "#/components/responses/PartnerForbidden" }, "409": { "description": "TOO_MANY_WEBHOOKS or an Idempotency-Key conflict" } } } }, "/api/v1/partner/webhooks/{id}": { "patch": { "operationId": "partnerUpdateWebhook", "tags": [ "partner" ], "summary": "Change a webhook's address, events or state", "security": [ { "partnerKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/PartnerEnvironment" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string" }, "active": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "The webhook.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerWebhook" } } } }, "400": { "description": "Invalid address or event" }, "401": { "$ref": "#/components/responses/PartnerUnauthorized" }, "403": { "$ref": "#/components/responses/PartnerForbidden" }, "404": { "description": "NOT_FOUND" } } }, "delete": { "operationId": "partnerDeleteWebhook", "tags": [ "partner" ], "summary": "Delete a webhook; its pending deliveries are cancelled", "security": [ { "partnerKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/PartnerEnvironment" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/PartnerUnauthorized" }, "403": { "$ref": "#/components/responses/PartnerForbidden" }, "404": { "description": "NOT_FOUND" } } } }, "/api/v1/partner/webhooks/{id}/rotate-secret": { "post": { "operationId": "partnerRotateWebhookSecret", "tags": [ "partner" ], "summary": "A new signing secret, shown once; the old one stops at once", "security": [ { "partnerKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/PartnerEnvironment" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The webhook with its new secret.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerWebhook" } } } }, "401": { "$ref": "#/components/responses/PartnerUnauthorized" }, "403": { "$ref": "#/components/responses/PartnerForbidden" }, "404": { "description": "NOT_FOUND" } } } }, "/api/v1/partner/webhooks/{id}/test": { "post": { "operationId": "partnerTestWebhook", "tags": [ "partner" ], "summary": "Send a signed webhook.test event now, and say what the address answered", "security": [ { "partnerKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/PartnerEnvironment" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The outcome.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "status": { "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ] }, "eventId": { "type": "string" }, "deliveryId": { "type": "string" } } } } } }, "401": { "$ref": "#/components/responses/PartnerUnauthorized" }, "403": { "$ref": "#/components/responses/PartnerForbidden" }, "404": { "description": "NOT_FOUND" } } } }, "/api/v1/partner/webhooks/{id}/deliveries": { "get": { "operationId": "partnerWebhookDeliveries", "tags": [ "partner" ], "summary": "The latest deliveries to one webhook", "security": [ { "partnerKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/PartnerEnvironment" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "Deliveries", "newest first.": null, "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "401": { "$ref": "#/components/responses/PartnerUnauthorized" }, "403": { "$ref": "#/components/responses/PartnerForbidden" }, "404": { "description": "NOT_FOUND" } } } }, "/api/v1/partner/events": { "get": { "operationId": "partnerListEvents", "tags": [ "partner" ], "summary": "Every event of this environment, oldest first from a cursor", "description": "Scope `events:read`. Kept 90 days. `after` is the id of the last event you have; `type` an exact type or `family.*`.", "security": [ { "partnerKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/PartnerEnvironment" }, { "name": "after", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "order", "in": "query", "required": false, "description": "oldest (default) reads after a cursor; newest returns the latest events, newest first, and takes no cursor", "schema": { "type": "string", "enum": [ "oldest", "newest" ] } } ], "responses": { "200": { "description": "A page of events.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PartnerEvent" } }, "hasMore": { "type": "boolean" }, "nextAfter": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "INVALID_CURSOR" }, "401": { "$ref": "#/components/responses/PartnerUnauthorized" }, "403": { "$ref": "#/components/responses/PartnerForbidden" }, "404": { "description": "CURSOR_NOT_FOUND" } } } }, "/api/v1/partner/events/{id}": { "get": { "operationId": "partnerGetEvent", "tags": [ "partner" ], "summary": "One event", "security": [ { "partnerKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/PartnerEnvironment" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The event.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerEvent" } } } }, "401": { "$ref": "#/components/responses/PartnerUnauthorized" }, "403": { "$ref": "#/components/responses/PartnerForbidden" }, "404": { "description": "NOT_FOUND" } } } } }, "components": { "securitySchemes": { "partnerKey": { "type": "apiKey", "in": "header", "name": "X-Api-Key", "description": "Partner API. `mtp_live_…` or `mtp_test_…` — the environment is in the key, and a test key\nnever reaches an operator or money. Scopes per key (account:read, rates:read, wallet:read, wallet:write, esims:*,\nnumbers:*, end_users:*, trunks:*, calls:read, sms:*, webhooks:manage, events:read). Shown once, stored as a SHA-256.\nThe partner panel calls the same routes with the session of one of the partner's people and X-Partner-Environment.\n" } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Caller-supplied key making this mutation safe to retry. Scoped to the\ncaller server-side and enforced by a UNIQUE constraint. Routes that\nmove money may require it; optional routes remain unprotected when it\nis omitted.\n\nThis is a **product-local** convention. No ecosystem-wide idempotency\nheader standard exists — see escalation E-IDEMPOTENCY in the README.\n", "schema": { "type": "string", "maxLength": 120 } }, "PartnerEnvironment": { "name": "X-Partner-Environment", "in": "header", "required": false, "description": "For the panel's session only — `live` (default) or `test`. A key carries its own environment.", "schema": { "type": "string", "enum": [ "live", "test" ] } } }, "schemas": { "MinorUnits": { "type": "integer", "format": "int64", "description": "An amount in **minor units** (cents), stored as PostgreSQL `BIGINT`.\nNever a float, never a decimal string, never scaled at the boundary.\n`1999` means $19.99.\n\nSigned where the field represents a movement (ledger entries,\nadjustments); non-negative where it represents a balance.\n", "examples": [ 1999 ] }, "PartnerAccount": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "legalName": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "suspended" ] }, "country": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] }, "environment": { "type": "string", "enum": [ "live", "test" ] }, "services": { "type": "array", "items": { "type": "object", "properties": { "service": { "type": "string" }, "state": { "type": "string", "enum": [ "draft", "active", "suspended" ] }, "limits": { "type": "object", "additionalProperties": true } } } }, "you": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "key", "user" ] }, "role": { "type": [ "string", "null" ] }, "scopes": { "type": "array", "items": { "type": "string" } } } }, "limits": { "type": "object", "properties": { "requestsPerMinute": { "type": "integer" }, "balanceCapMinor": { "$ref": "#/components/schemas/MinorUnits" } } }, "support": { "type": "object", "properties": { "email": { "type": "string" } } } } }, "PartnerBalance": { "type": "object", "properties": { "environment": { "type": "string", "enum": [ "live", "test" ] }, "balanceMinor": { "$ref": "#/components/schemas/MinorUnits" }, "heldMinor": { "$ref": "#/components/schemas/MinorUnits" }, "availableMinor": { "$ref": "#/components/schemas/MinorUnits" }, "capMinor": { "$ref": "#/components/schemas/MinorUnits" }, "headroomMinor": { "$ref": "#/components/schemas/MinorUnits" }, "currency": { "type": "string" } } }, "PartnerEndUser": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "reference": { "type": [ "string", "null" ] }, "identityType": { "type": "string", "enum": [ "personal", "business" ] }, "name": { "type": "string" }, "country": { "type": [ "string", "null" ] }, "fieldsHeld": { "type": "object", "description": "The names of the fields we hold — never their values.", "properties": { "identity": { "type": "array", "items": { "type": "string" } }, "address": { "type": "array", "items": { "type": "string" } } } }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "PartnerError": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true }, "requestId": { "type": [ "string", "null" ] } } }, "PartnerEsim": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Exists from the first answer; follow it to issued or failed." }, "reference": { "type": [ "string", "null" ] }, "environment": { "type": "string", "enum": [ "live", "test" ] }, "status": { "type": "string", "enum": [ "processing", "issued", "installed", "used_up", "expired", "closed", "cancelled", "failed" ] }, "package": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "dataMb": { "type": [ "integer", "null" ] }, "unlimited": { "type": "boolean" }, "validityDays": { "type": [ "integer", "null" ] } } }, "priceMinor": { "$ref": "#/components/schemas/MinorUnits" }, "currency": { "type": "string" }, "iccid": { "type": [ "string", "null" ] }, "install": { "type": [ "object", "null" ], "properties": { "activationCode": { "type": "string", "description": "LPA:1$…" }, "iosLink": { "type": [ "string", "null" ] }, "qrPath": { "type": "string" } } }, "allowanceMb": { "type": [ "number", "null" ] }, "usage": { "type": "object", "properties": { "reported": { "type": "boolean" }, "usedMb": { "type": [ "number", "null" ] }, "remainingMb": { "type": [ "number", "null" ] }, "checkedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "topupSupported": { "type": [ "boolean", "null" ] }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "failure": { "type": [ "string", "null" ] }, "refundedMinor": { "$ref": "#/components/schemas/MinorUnits" }, "createdAt": { "type": "string", "format": "date-time" } } }, "PartnerEsimRate": { "type": "object", "properties": { "id": { "type": "integer" }, "sku": { "type": "string" }, "name": { "type": "string" }, "country": { "type": [ "string", "null" ] }, "countryName": { "type": [ "string", "null" ] }, "region": { "type": [ "string", "null" ] }, "dataMb": { "type": [ "integer", "null" ] }, "unlimited": { "type": "boolean" }, "validityDays": { "type": [ "integer", "null" ] }, "priceMinor": { "oneOf": [ { "$ref": "#/components/schemas/MinorUnits" }, { "type": "null" } ] }, "currency": { "type": "string" }, "available": { "type": "boolean" }, "hold": { "type": [ "string", "null" ] } } }, "PartnerEvent": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string" }, "environment": { "type": "string", "enum": [ "live", "test" ] }, "object": { "type": [ "object", "null" ], "properties": { "type": { "type": "string" }, "id": { "type": "string" } } }, "data": { "type": "object", "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" } } }, "PartnerNumber": { "type": "object", "properties": { "id": { "type": "string" }, "reference": { "type": [ "string", "null" ] }, "environment": { "type": "string", "enum": [ "live", "test" ] }, "e164": { "type": [ "string", "null" ] }, "country": { "type": "string" }, "status": { "type": "string" }, "endUser": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "reference": { "type": [ "string", "null" ] }, "name": { "type": "string" } } }, "monthlyMinor": { "oneOf": [ { "$ref": "#/components/schemas/MinorUnits" }, { "type": "null" } ] }, "setupMinor": { "$ref": "#/components/schemas/MinorUnits" }, "currency": { "type": "string" }, "registration": { "type": "object", "properties": { "id": { "type": "string" }, "required": { "type": "boolean" }, "status": { "type": "string" } } }, "routing": { "type": "object", "properties": { "to": { "type": "string", "enum": [ "trunk", "none" ] }, "trunkId": { "type": [ "string", "null" ] } } }, "currentPeriodEnd": { "type": [ "string", "null" ], "format": "date-time" }, "autoRenew": { "type": "boolean" }, "cancelAtPeriodEnd": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } } }, "PartnerNumberRate": { "type": "object", "properties": { "country": { "type": "string" }, "name": { "type": "string" }, "fromMonthlyMinor": { "oneOf": [ { "$ref": "#/components/schemas/MinorUnits" }, { "type": "null" } ] }, "fromSetupMinor": { "oneOf": [ { "$ref": "#/components/schemas/MinorUnits" }, { "type": "null" } ] }, "currency": { "type": "string" }, "registrationRequired": { "type": "boolean" }, "priced": { "type": "boolean" }, "note": { "type": [ "string", "null" ] } } }, "PartnerSmsRate": { "type": "object", "properties": { "prefix": { "type": "string" }, "country": { "type": [ "string", "null" ] }, "perPartMinor": { "oneOf": [ { "$ref": "#/components/schemas/MinorUnits" }, { "type": "null" } ] }, "currency": { "type": "string" }, "open": { "type": "boolean" } } }, "PartnerTopup": { "type": "object", "properties": { "id": { "type": "string" }, "reference": { "type": "string" }, "method": { "type": "string", "enum": [ "card", "usdt_trc20", "bank" ] }, "environment": { "type": "string", "enum": [ "live", "test" ] }, "amountMinor": { "$ref": "#/components/schemas/MinorUnits" }, "currency": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "completed", "rejected", "expired" ] }, "createdAt": { "type": "string", "format": "date-time" }, "resolvedAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "checkoutUrl": { "type": "string", "description": "Card only", "while it is pending — the payment page.": null }, "usdt": { "type": "object", "properties": { "exactAmount": { "type": "string" }, "address": { "type": [ "string", "null" ] }, "network": { "type": "string" }, "token": { "type": "string" }, "note": { "type": "string" } } }, "bank": { "type": "object", "properties": { "details": { "type": [ "string", "null" ] }, "note": { "type": [ "string", "null" ] }, "referenceToQuote": { "type": "string" } } }, "creditedMinor": { "$ref": "#/components/schemas/MinorUnits" }, "returnedMinor": { "$ref": "#/components/schemas/MinorUnits" } } }, "PartnerTransactionPage": { "type": "object", "properties": { "environment": { "type": "string", "enum": [ "live", "test" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "amountMinor": { "allOf": [ { "$ref": "#/components/schemas/MinorUnits" } ], "description": "Signed — a top-up is positive", "a charge negative.": null }, "balanceAfterMinor": { "oneOf": [ { "$ref": "#/components/schemas/MinorUnits" }, { "type": "null" } ] }, "description": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" } } } }, "hasMore": { "type": "boolean" }, "nextBefore": { "type": [ "string", "null" ] } } }, "PartnerVoiceRate": { "type": "object", "properties": { "destination": { "type": "string" }, "country": { "type": [ "string", "null" ] }, "prefix": { "type": "string" }, "prefixes": { "type": "integer" }, "fromPerMinuteUsd": { "type": [ "number", "null" ] }, "toPerMinuteUsd": { "type": [ "number", "null" ] }, "billing": { "type": "string" }, "carried": { "type": "boolean" }, "notCarriedReason": { "type": [ "string", "null" ], "enum": [ "sanctions", "not_open", null ] } } }, "PartnerWebhook": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "environment": { "type": "string", "enum": [ "live", "test" ] }, "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } }, "description": { "type": [ "string", "null" ] }, "active": { "type": "boolean" }, "failuresInRow": { "type": "integer" }, "lastSuccessAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastFailureAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastError": { "type": [ "string", "null" ] }, "disabledReason": { "type": [ "string", "null" ] }, "secret": { "type": "string", "description": "Only when the webhook is created or its secret rotated." }, "createdAt": { "type": "string", "format": "date-time" } } } }, "responses": { "PartnerForbidden": { "description": "INSUFFICIENT_SCOPE, PANEL_ONLY, PARTNER_ONLY, PARTNER_SUSPENDED (reads only) or PARTNER_INACTIVE.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerError" } } } }, "PartnerRateLimited": { "description": "RATE_LIMITED — more than 600 requests a minute for this key or person. Retry-After says when.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerError" } } } }, "PartnerUnauthorized": { "description": "API_KEY_INVALID, or no key and no session (UNAUTHORIZED).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartnerError" } } } } } } }