{ "openapi": "3.0.0", "servers": [ { "url": "https://api.nexmo.com/accounts" } ], "info": { "version": "1.0.8", "title": "Subaccounts API", "x-metaTitle": "Vonage Subaccounts API Reference | Vonage API Documentation", "x-metaDescription": "Find quick answers to questions about the Vonage Subaccounts API in this reference guide. Learn more in Vonage's API documentation.", "description": "The Subaccounts API enables you to create subaccounts under your primary account. Subaccounts facilitate differential product configuration, reporting, and billing. The Subaccounts API is released initially with restricted availability. You can read more about the API in the [Subaccounts documentation](/account/subaccounts/overview).", "contact": { "name": "Vonage DevRel", "email": "devrel@vonage.com", "url": "https://developer.nexmo.com/" } }, "paths": { "/{api_key}/subaccounts": { "get": { "summary": "Retrieve list of subaccounts", "operationId": "retrieveSubaccountsList", "description": "Get the information of all the subaccounts owned by the primary account.\n", "tags": [ "Subaccount Management" ], "security": [ { "basicAuth": [] } ], "parameters": [ { "name": "api_key", "in": "path", "description": "ID of the primary account", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Subaccounts response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubaccountsAllResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/AccountIdNotFoundError" } } }, "post": { "summary": "Create subaccount", "operationId": "createSubAccount", "description": "Create a subaccount for a given primary account.\n", "tags": [ "Subaccount Management" ], "security": [ { "basicAuth": [] } ], "parameters": [ { "name": "api_key", "in": "path", "description": "ID of the primary account", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewSubaccountRequest" } } } }, "responses": { "200": { "description": "Subaccount response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubaccountCreateResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/AccountIdNotFoundError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" } } } }, "/{api_key}/subaccounts/{subaccount_key}": { "get": { "summary": "Retrieve a subaccount", "operationId": "retrieveSubaccount", "description": "Get the information of a subaccount specified with its API key.\n", "tags": [ "Subaccount Management" ], "security": [ { "basicAuth": [] } ], "parameters": [ { "name": "api_key", "in": "path", "description": "ID of the primary account", "required": true, "schema": { "type": "string" } }, { "name": "subaccount_key", "in": "path", "description": "ID of the subaccount", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Subaccount response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubaccountResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/AccountIdNotFoundError" } } }, "patch": { "summary": "Modify a subaccount", "operationId": "modifySubaccount", "description": "Change one or more properties of a subaccount.\n", "tags": [ "Subaccount Management" ], "security": [ { "basicAuth": [] } ], "parameters": [ { "name": "api_key", "in": "path", "description": "ID of the primary account", "required": true, "schema": { "type": "string" } }, { "name": "subaccount_key", "in": "path", "description": "ID of the subaccount", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModifySubaccountRequest" } } } }, "responses": { "200": { "description": "Subaccount response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubaccountResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/AccountIdNotFoundError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" } } } }, "/{api_key}/credit-transfers": { "get": { "summary": "Retrieve list of credit transfers", "operationId": "retrieveCreditTransfers", "description": "Retrieve a list of credit transfers that have taken place for a primary account within a specified time period.\n", "tags": [ "Transfers" ], "security": [ { "basicAuth": [] } ], "parameters": [ { "name": "api_key", "in": "path", "description": "ID of the primary account.", "required": true, "schema": { "type": "string" } }, { "name": "start_date", "in": "query", "description": "Start of the retrieval period.", "required": true, "schema": { "type": "string" }, "example": "2019-07-15T13:11:44Z" }, { "name": "end_date", "in": "query", "description": "End of the retrieval period. If absent then all transfers until now is returned.", "required": false, "schema": { "type": "string" }, "example": "2019-07-15T14:11:44Z" }, { "name": "subaccount", "in": "query", "description": "Subaccount to filter by. You may send this multiple times to filter on multiple subaccounts", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List credit transfers response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListCreditTransfersResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/AccountIdNotFoundError" } } }, "post": { "summary": "Transfer credit", "operationId": "transferCredit", "description": "Transfer credit limit between a primary account and one of its subaccounts.\n", "tags": [ "Transfers" ], "security": [ { "basicAuth": [] } ], "parameters": [ { "name": "api_key", "in": "path", "description": "ID of the primary account", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferBalanceOrCreditRequest" } } } }, "responses": { "200": { "description": "Credit transfer response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferCreditResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/AccountIdNotFoundError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" } } } }, "/{api_key}/balance-transfers": { "get": { "summary": "Retrieve list of balance transfers", "operationId": "retrieveBalanceTransfers", "description": "Retrieve a list of balance transfers that have taken place for a primary account within a specified time period.\n", "tags": [ "Transfers" ], "security": [ { "basicAuth": [] } ], "parameters": [ { "name": "api_key", "in": "path", "description": "ID of the primary account.", "required": true, "schema": { "type": "string" } }, { "name": "start_date", "in": "query", "description": "Start of the retrieval period.", "required": true, "schema": { "type": "string" }, "example": "2019-07-15T13:11:44Z" }, { "name": "end_date", "in": "query", "description": "End of the retrieval period. If absent then all transfers until now is returned.", "required": false, "schema": { "type": "string" }, "example": "2019-07-15T14:11:44Z" }, { "name": "subaccount", "in": "query", "description": "Subaccount to filter by. You may send this multiple times to filter on multiple subaccounts", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List balance transfers response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListBalanceTransfersResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/AccountIdNotFoundError" } } }, "post": { "summary": "Transfer balance", "description": "Transfer balance between a primary account and one of its subaccounts. Note that balance_available_for_transfer = |account_balance - credit_limit| of the source account.\n", "tags": [ "Transfers" ], "security": [ { "basicAuth": [] } ], "operationId": "transferBalance", "parameters": [ { "name": "api_key", "in": "path", "description": "ID of the primary account", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferBalanceOrCreditRequest" } } } }, "responses": { "200": { "description": "Balance transfer response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferBalanceResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "$ref": "#/components/responses/ForbiddenError" }, "404": { "$ref": "#/components/responses/AccountIdNotFoundError" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" } } } }, "/{api_key}/transfer-number": { "post": { "summary": "Transfer number", "operationId": "transferNumber", "description": "Transfer number from one account to another.\n", "tags": [ "Transfers" ], "security": [ { "basicAuth": [] } ], "parameters": [ { "name": "api_key", "in": "path", "description": "ID of the primary account.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferNumberRequest" } } } }, "responses": { "200": { "description": "Number transfer response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferNumberResponse" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "403": { "description": "Action is forbidden", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/UnprovisionedErrorResponse" }, { "$ref": "#/components/schemas/InvalidNumberTransferErrorResponse" } ] } } } }, "404": { "description": "Action is forbidden", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/responses/AccountIdNotFoundError/content/application~1json/schema" }, { "$ref": "#/components/schemas/ShortcodeNotFound" } ] } } } }, "409": { "$ref": "#/components/responses/NumberTransferConflictResponse" }, "422": { "$ref": "#/components/responses/UnprocessableEntityError" } } } } }, "tags": [ { "name": "Subaccount Management", "description": "This section shows how you can create, retrieve and modify subaccounts of a primary account." }, { "name": "Transfers", "description": "This section shows how you execute credit, balance and number transfers, as well as viewing past transactions." } ], "components": { "securitySchemes": { "basicAuth": { "type": "http", "scheme": "basic" } }, "responses": { "UnauthorizedError": { "description": "Credential is missing or invalid", "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "title", "detail", "instance" ], "properties": { "type": { "type": "string", "example": "https://developer.nexmo.com/api-errors#unauthorized" }, "title": { "type": "string", "example": "Invalid credentials supplied" }, "detail": { "type": "string", "example": "You did not provide correct credentials" }, "instance": { "type": "string", "example": "798b8f199c45014ab7b08bfe9cc1c12c" } } } } } }, "ForbiddenError": { "description": "Action is forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnprovisionedErrorResponse" } } } }, "AccountIdNotFoundError": { "description": "The account ID provided does not exist in our system or you do not have access", "content": { "application/json": { "schema": { "description": "Invalid API Key", "type": "object", "required": [ "type", "title", "detail", "instance" ], "properties": { "type": { "type": "string", "example": "https://developer.nexmo.com/api-errors#invalid-api-key" }, "title": { "type": "string", "example": "Invalid API Key" }, "detail": { "type": "string", "example": "API key 'acc6111f' does not exist, or you do not have access" }, "instance": { "type": "string", "example": "158b8f199c45014ab7b08bfe9cc1c12c" } } } } } }, "NumberTransferConflictResponse": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "title", "detail", "instance" ], "properties": { "type": { "type": "string", "example": "https://developer.nexmo.com/api-errors/subaccounts#transfer-conflict" }, "title": { "type": "string", "example": "Transfer Conflict" }, "detail": { "type": "string", "example": "Could not transfer number {number} from account {from} to {to} - ShortCode is already owned by requesting account" }, "instance": { "type": "string", "example": "158b8f199c45014ab7b08bfe9cc1c12c" } } } } } }, "UnprocessableEntityError": { "description": "Validation Error", "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "title", "detail", "invalid_parameters", "instance" ], "properties": { "type": { "type": "string", "example": "https://developer.nexmo.com/api-errors/subaccounts#validation" }, "title": { "type": "string", "example": "Bad Request" }, "detail": { "type": "string", "example": "The request failed due to validation errors" }, "invalid_parameters": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "use_primary_account_balance" }, "reason": { "type": "string", "example": "Should be either 'true' or 'false'" } } } }, "instance": { "type": "string", "example": "158b8f199c45014ab7b08bfe9cc1c12c" } } } } } }, "InternalError": { "description": "An internal error has occurred", "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "title", "detail", "instance" ], "properties": { "type": { "type": "string", "example": "https://developer.nexmo.com/api-errors#internal-error" }, "title": { "type": "string", "example": "Internal Error" }, "detail": { "type": "string", "example": "An internal error occurred. Please try again shortly" }, "instance": { "type": "string", "example": "158b8f199c45014ab7b08bfe9cc1c12c" } } } } } } }, "schemas": { "UnprovisionedErrorResponse": { "description": "Unprovisioned", "type": "object", "required": [ "type", "title", "detail", "instance" ], "properties": { "type": { "type": "string", "example": "https://developer.nexmo.com/api-errors#unprovisioned" }, "title": { "type": "string", "example": "Authorisation error" }, "detail": { "type": "string", "example": "Account acc6111f is not provisioned to access Subaccount Provisioning API" }, "instance": { "type": "string", "example": "158b8f199c45014ab7b08bfe9cc1c12c" } } }, "ShortcodeNotFound": { "description": "Shortcode Not Found", "type": "object", "required": [ "type", "title", "detail", "instance" ], "properties": { "type": { "type": "string", "example": "https://developer.nexmo.com/api-errors/subaccounts#missing-number-transfer" }, "title": { "type": "string", "example": "Invalid Number Transfer" }, "detail": { "type": "string", "example": "Could not transfer number {number} from account {from} to {to} - ShortCode not found" }, "instance": { "type": "string", "example": "158b8f199c45014ab7b08bfe9cc1c12c" } } }, "InvalidNumberTransferErrorResponse": { "description": "Invalid Transfer", "type": "object", "required": [ "type", "title", "detail", "instance" ], "properties": { "type": { "type": "string", "example": "https://developer.nexmo.com/api-errors/subaccounts#invalid-number-transfer" }, "title": { "type": "string", "example": "Invalid Number Transfer" }, "detail": { "type": "string", "example": "Failed to perform transfer number {number} from account {from} to {to} - The relationship between these two accounts does not allow for number transfer" }, "instance": { "type": "string", "example": "158b8f199c45014ab7b08bfe9cc1c12c" } } }, "SubaccountsAllResponse": { "properties": { "_embedded": { "type": "object", "properties": { "primary_account": { "$ref": "#/components/schemas/SubaccountResponse" }, "subaccounts": { "type": "array", "items": { "$ref": "#/components/schemas/SubaccountResponse" } } } } } }, "SubaccountResponse": { "properties": { "api_key": { "example": "bbe6222f", "type": "string", "description": "Unique subaccount ID." }, "name": { "type": "string", "example": "Subaccount department A", "description": "Name of the subaccount." }, "primary_account_api_key": { "example": "acc6111f", "type": "string", "description": "Unique primary account ID." }, "use_primary_account_balance": { "example": true, "type": "boolean", "description": "Flag showing if balance is shared with primary account." }, "created_at": { "example": "2018-03-02T16:34:49Z", "type": "string", "description": "Subaccount creation date and time." }, "suspended": { "example": false, "type": "boolean", "description": "Subaccount suspension status." }, "balance": { "example": 100.25, "type": "number", "description": "Balance of the subAccount. Value is null if balance is shared with primary account." }, "credit_limit": { "example": -100.25, "type": "number", "description": "Credit limit of the subAccount. Value is null if balance is shared with primary account." } } }, "SubaccountCreateResponse": { "allOf": [ { "properties": { "secret": { "type": "string", "example": "Password123", "description": "API secret of the subaccount." } } }, { "$ref": "#/components/schemas/SubaccountResponse" } ] }, "TransferCreditResponse": { "properties": { "credit_transfer_id": { "example": "07b5-46e1-a527-85530e625800", "type": "string", "description": "Unique credit transfer ID" }, "amount": { "example": 123.45, "type": "number", "description": "Credit transfer amount" }, "from": { "example": "7c9738e6", "type": "string", "description": "Account the credit is transferred from" }, "to": { "example": "ad6dc56f", "type": "string", "description": "Account the credit is transferred to" }, "reference": { "example": "This gets added to the audit log", "type": "string", "description": "Reference for the credit transfer" }, "created_at": { "example": "2019-03-02T16:34:49Z", "type": "string", "description": "The date and time when the credit transfer was executed" } } }, "TransferBalanceResponse": { "properties": { "balance_transfer_id": { "example": "07b5-46e1-a527-85530e625800", "type": "string", "description": "Unique balance transfer ID" }, "amount": { "example": 123.45, "type": "number", "description": "Balance transfer amount" }, "from": { "example": "7c9738e6", "type": "string", "description": "Account the balance is transferred from" }, "to": { "example": "ad6dc56f", "type": "string", "description": "Account the balance is transferred to" }, "reference": { "example": "This gets added to the audit log", "type": "string", "description": "Reference for the balance transfer" }, "created_at": { "example": "2019-03-02T16:34:49Z", "type": "string", "description": "The date and time when the balance transfer was executed" } } }, "TransferNumberResponse": { "properties": { "number": { "example": "235077036", "type": "string", "description": "Number transfered" }, "country": { "example": "GB", "type": "string", "description": "The two character country code in ISO 3166-1 alpha-2 format" }, "from": { "example": "7c9738e6", "type": "string", "description": "Account the number is transferred from" }, "to": { "example": "ad6dc56f", "type": "string", "description": "Account the number is transferred to" } } }, "ListCreditTransfersResponse": { "properties": { "_embedded": { "type": "object", "properties": { "credit-transfers": { "type": "array", "items": { "$ref": "#/components/schemas/TransferCreditResponse" } } } } } }, "ListBalanceTransfersResponse": { "properties": { "_embedded": { "type": "object", "properties": { "balance_transfers": { "type": "array", "items": { "$ref": "#/components/schemas/TransferBalanceResponse" } } } } } }, "NewSubaccountRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "maxLength": 80, "example": "Subaccount department A" }, "secret": { "type": "string", "example": "Password123" }, "use_primary_account_balance": { "type": "boolean", "example": false, "default": true } } }, "ModifySubaccountRequest": { "type": "object", "properties": { "suspended": { "type": "boolean", "example": true }, "use_primary_account_balance": { "type": "boolean", "example": false }, "name": { "type": "string", "example": "Subaccount department B" } } }, "TransferBalanceOrCreditRequest": { "type": "object", "properties": { "from": { "type": "string", "example": "7c9738e6" }, "to": { "type": "string", "example": "ad6dc56f" }, "amount": { "type": "number", "example": "123.45" }, "reference": { "type": "string", "example": "This gets added to the audit log" } }, "required": [ "from", "to", "amount" ] }, "TransferNumberRequest": { "type": "object", "properties": { "from": { "type": "string", "example": "7c9738e6" }, "to": { "type": "string", "example": "ad6dc56f" }, "number": { "type": "number", "example": "23507703696" }, "country": { "type": "string", "example": "GB" } } } } }, "x-errors": { "validation": { "description": "The request failed due to validation errors", "resolution": "See the `detail` (and, if present, the `invalid_parameters`) fields for the exact reason this request was rejected and review the documentation.", "link": { "text": "View API reference", "url": "/api/subaccounts" } }, "invalid-transfers": { "description": "Invalid transfer", "resolution": "See the `detail` field for the reason this transfer is invalid.", "link": { "text": "View API reference", "url": "/api/subaccounts#transferCredit" } }, "provisioning": { "description": "Maximum number of sub-accounts reached", "resolution": "If you need more subaccounts, contact [Vonage Support](https://support.vonage.co.uk/contactus)." }, "internal-error": { "description": "An error has occurred in the platform while processing this request", "resolution": "If the error persists, contact [Vonage Support](https://support.vonage.co.uk/contactus)." }, "invalid-number-transfer": { "description": "Failed to perform transfer number from source account to destination account", "resolution": "See the `detail` field for the reason this transfer is invalid.", "link": { "text": "View API reference", "url": "/api/subaccounts#transferNumber" } }, "missing-number-transfer": { "description": "Could not transfer number from source account to destination account - ShortCode not found", "resolution": "See the `detail` field for the reason this transfer is invalid.", "link": { "text": "View API reference", "url": "/api/subaccounts#transferNumber" } }, "transfer-conflict": { "description": "Could not transfer number from source account to destination account - ShortCode is already owned by requesting account", "resolution": "See the `detail` field for the reason this transfer is invalid.", "link": { "text": "View API reference", "url": "/api/subaccounts#transferNumber" } } } }