Skip to content
Permalink
main
Switch branches/tags
Go to file
 
 
Cannot retrieve contributors at this time
openapi: 3.0.0
servers:
- url: "https://api.nexmo.com/accounts"
info:
version: 1.0.8
title: Subaccounts API
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.
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.
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.
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.
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.
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.
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.
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.
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.
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
valid-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).