Subaccounts API

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.

Télécharger la spécification OpenAPI

Subaccount Management

This section shows how you can create, retrieve and modify subaccounts of a primary account.

Opérations disponibles

Retrieve list of subaccounts

Get the information of all the subaccounts owned by the primary account.

gethttps://api.nexmo.com/accounts/:api_key/subaccounts

Authentification

Clé	Description	Où	Exemple
Authorization	Clé et secret de l'API encodés en Base64 et reliés par deux points. En savoir plus	Headers	`Basic <base64>`

Trajectoire Paramètres

api_key

string

Exigée

ID of the primary account

Réponses
Type de contenu
application/json

Subaccounts response

_embedded

object

primary_account

api_key

string

exemplebbe6222f

Unique subaccount ID.

name

string

exempleSubaccount department A

Name of the subaccount.

primary_account_api_key

string

exempleacc6111f

Unique primary account ID.

use_primary_account_balance

boolean

exempletrue

Flag showing if balance is shared with primary account.

created_at

string

exemple2018-03-02T16:34:49Z

Subaccount creation date and time.

suspended

boolean

Subaccount suspension status.

balance

number

exemple100.25

Balance of the subAccount. Value is null if balance is shared with primary account.

credit_limit

number

exemple-100.25

Credit limit of the subAccount. Value is null if balance is shared with primary account.

subaccounts

array

api_key

string

exemplebbe6222f

Unique subaccount ID.

name

string

exempleSubaccount department A

Name of the subaccount.

primary_account_api_key

string

exempleacc6111f

Unique primary account ID.

use_primary_account_balance

boolean

exempletrue

Flag showing if balance is shared with primary account.

created_at

string

exemple2018-03-02T16:34:49Z

Subaccount creation date and time.

suspended

boolean

Subaccount suspension status.

balance

number

exemple100.25

Balance of the subAccount. Value is null if balance is shared with primary account.

credit_limit

number

exemple-100.25

Credit limit of the subAccount. Value is null if balance is shared with primary account.

Exemple Réponse

{
   "_embedded": {
      "primary_account": {
         "api_key": "bbe6222f",
         "name": "Subaccount department A",
         "primary_account_api_key": "acc6111f",
         "use_primary_account_balance": true,
         "created_at": "2018-03-02T16:34:49Z",
         "suspended": false,
         "balance": 100.25,
         "credit_limit": -100.25
      },
      "subaccounts": [
         {
            "api_key": "bbe6222f",
            "name": "Subaccount department A",
            "primary_account_api_key": "acc6111f",
            "use_primary_account_balance": true,
            "created_at": "2018-03-02T16:34:49Z",
            "suspended": false,
            "balance": 100.25,
            "credit_limit": -100.25
         }
      ]
   }
}

Create subaccount

Create a subaccount for a given primary account.

posthttps://api.nexmo.com/accounts/:api_key/subaccounts

Authentification

Clé	Description	Où	Exemple
Authorization	Clé et secret de l'API encodés en Base64 et reliés par deux points. En savoir plus	Headers	`Basic <base64>`

Trajectoire Paramètres

api_key

string

Exigée

ID of the primary account

Corps de la demande
Type de contenu
application/json

name

string

Exigée

Max80

exempleSubaccount department A

secret

string

exemplePassword123

use_primary_account_balance

boolean

Défauttrue

Exemple Demande

{
   "name": "Subaccount department A",
   "secret": "Password123",
   "use_primary_account_balance": false
}

{
   "name": "Subaccount department A",
   "secret": "Password123",
   "use_primary_account_balance": false
}

Réponses
Type de contenu
application/json

Subaccount response

secret

string

exemplePassword123

API secret of the subaccount.

api_key

string

exemplebbe6222f

Unique subaccount ID.

name

string

exempleSubaccount department A

Name of the subaccount.

primary_account_api_key

string

exempleacc6111f

Unique primary account ID.

use_primary_account_balance

boolean

exempletrue

Flag showing if balance is shared with primary account.

created_at

string

exemple2018-03-02T16:34:49Z

Subaccount creation date and time.

suspended

boolean

Subaccount suspension status.

balance

number

exemple100.25

Balance of the subAccount. Value is null if balance is shared with primary account.

credit_limit

number

exemple-100.25

Credit limit of the subAccount. Value is null if balance is shared with primary account.

Exemple Réponse

{
   "secret": "Password123",
   "api_key": "bbe6222f",
   "name": "Subaccount department A",
   "primary_account_api_key": "acc6111f",
   "use_primary_account_balance": true,
   "created_at": "2018-03-02T16:34:49Z",
   "suspended": false,
   "balance": 100.25,
   "credit_limit": -100.25
}

Retrieve a subaccount

Get the information of a subaccount specified with its API key.

gethttps://api.nexmo.com/accounts/:api_key/subaccounts/:subaccount_key

Authentification

Clé	Description	Où	Exemple
Authorization	Clé et secret de l'API encodés en Base64 et reliés par deux points. En savoir plus	Headers	`Basic <base64>`

Trajectoire Paramètres

api_key

string

Exigée

ID of the primary account

subaccount_key

string

Exigée

ID of the subaccount

Réponses
Type de contenu
application/json

Subaccount response

api_key

string

exemplebbe6222f

Unique subaccount ID.

name

string

exempleSubaccount department A

Name of the subaccount.

primary_account_api_key

string

exempleacc6111f

Unique primary account ID.

use_primary_account_balance

boolean

exempletrue

Flag showing if balance is shared with primary account.

created_at

string

exemple2018-03-02T16:34:49Z

Subaccount creation date and time.

suspended

boolean

Subaccount suspension status.

balance

number

exemple100.25

Balance of the subAccount. Value is null if balance is shared with primary account.

credit_limit

number

exemple-100.25

Credit limit of the subAccount. Value is null if balance is shared with primary account.

Exemple Réponse

{
   "api_key": "bbe6222f",
   "name": "Subaccount department A",
   "primary_account_api_key": "acc6111f",
   "use_primary_account_balance": true,
   "created_at": "2018-03-02T16:34:49Z",
   "suspended": false,
   "balance": 100.25,
   "credit_limit": -100.25
}

Modify a subaccount

Change one or more properties of a subaccount.

patchhttps://api.nexmo.com/accounts/:api_key/subaccounts/:subaccount_key

Authentification

Clé	Description	Où	Exemple
Authorization	Clé et secret de l'API encodés en Base64 et reliés par deux points. En savoir plus	Headers	`Basic <base64>`

Trajectoire Paramètres

api_key

string

Exigée

ID of the primary account

subaccount_key

string

Exigée

ID of the subaccount

Corps de la demande
Type de contenu
application/json

suspended

boolean

exempletrue

use_primary_account_balance

boolean

name

string

exempleSubaccount department B

Exemple Demande

{
   "suspended": true,
   "use_primary_account_balance": false,
   "name": "Subaccount department B"
}

{
   "suspended": true,
   "use_primary_account_balance": false,
   "name": "Subaccount department B"
}

Réponses
Type de contenu
application/json

Subaccount response

api_key

string

exemplebbe6222f

Unique subaccount ID.

name

string

exempleSubaccount department A

Name of the subaccount.

primary_account_api_key

string

exempleacc6111f

Unique primary account ID.

use_primary_account_balance

boolean

exempletrue

Flag showing if balance is shared with primary account.

created_at

string

exemple2018-03-02T16:34:49Z

Subaccount creation date and time.

suspended

boolean

Subaccount suspension status.

balance

number

exemple100.25

Balance of the subAccount. Value is null if balance is shared with primary account.

credit_limit

number

exemple-100.25

Credit limit of the subAccount. Value is null if balance is shared with primary account.

Exemple Réponse

{
   "api_key": "bbe6222f",
   "name": "Subaccount department A",
   "primary_account_api_key": "acc6111f",
   "use_primary_account_balance": true,
   "created_at": "2018-03-02T16:34:49Z",
   "suspended": false,
   "balance": 100.25,
   "credit_limit": -100.25
}

Transfers

This section shows how you execute credit, balance and number transfers, as well as viewing past transactions.

Opérations disponibles

Retrieve list of credit transfers

Retrieve a list of credit transfers that have taken place for a primary account within a specified time period.

gethttps://api.nexmo.com/accounts/:api_key/credit-transfers

Authentification

Clé	Description	Où	Exemple
Authorization	Clé et secret de l'API encodés en Base64 et reliés par deux points. En savoir plus	Headers	`Basic <base64>`

Trajectoire Paramètres

api_key

string

Exigée

ID of the primary account.

Demande de renseignements Paramètres

start_date

string

Start of the retrieval period.

end_date

string

End of the retrieval period. If absent then all transfers until now is returned.

subaccount

string

Subaccount to filter by. You may send this multiple times to filter on multiple subaccounts

Réponses
Type de contenu
application/json

List credit transfers response

_embedded

object

credit-transfers

array

credit_transfer_id

string

exemple07b5-46e1-a527-85530e625800

Unique credit transfer ID

amount

number

exemple123.45

Credit transfer amount

from

string

exemple7c9738e6

Account the credit is transferred from

string

exemplead6dc56f

Account the credit is transferred to

reference

string

exempleThis gets added to the audit log

Reference for the credit transfer

created_at

string

exemple2019-03-02T16:34:49Z

The date and time when the credit transfer was executed

Exemple Réponse

{
   "_embedded": {
      "credit-transfers": [
         {
            "credit_transfer_id": "07b5-46e1-a527-85530e625800",
            "amount": 123.45,
            "from": "7c9738e6",
            "to": "ad6dc56f",
            "reference": "This gets added to the audit log",
            "created_at": "2019-03-02T16:34:49Z"
         }
      ]
   }
}

Transfer credit

Transfer credit limit between a primary account and one of its subaccounts.

posthttps://api.nexmo.com/accounts/:api_key/credit-transfers

Authentification

Clé	Description	Où	Exemple
Authorization	Clé et secret de l'API encodés en Base64 et reliés par deux points. En savoir plus	Headers	`Basic <base64>`

Trajectoire Paramètres

api_key

string

Exigée

ID of the primary account

Corps de la demande
Type de contenu
application/json

from

string

Exigée

exemple7c9738e6

string

Exigée

exemplead6dc56f

amount

number

Exigée

exemple123.45

reference

string

exempleThis gets added to the audit log

Exemple Demande

{
   "from": "7c9738e6",
   "to": "ad6dc56f",
   "amount": "123.45",
   "reference": "This gets added to the audit log"
}

{
   "from": "7c9738e6",
   "to": "ad6dc56f",
   "amount": "123.45",
   "reference": "This gets added to the audit log"
}

Réponses
Type de contenu
application/json

Credit transfer response

credit_transfer_id

string

exemple07b5-46e1-a527-85530e625800

Unique credit transfer ID

amount

number

exemple123.45

Credit transfer amount

from

string

exemple7c9738e6

Account the credit is transferred from

string

exemplead6dc56f

Account the credit is transferred to

reference

string

exempleThis gets added to the audit log

Reference for the credit transfer

created_at

string

exemple2019-03-02T16:34:49Z

The date and time when the credit transfer was executed

Exemple Réponse

{
   "credit_transfer_id": "07b5-46e1-a527-85530e625800",
   "amount": 123.45,
   "from": "7c9738e6",
   "to": "ad6dc56f",
   "reference": "This gets added to the audit log",
   "created_at": "2019-03-02T16:34:49Z"
}

Retrieve list of balance transfers

Retrieve a list of balance transfers that have taken place for a primary account within a specified time period.

gethttps://api.nexmo.com/accounts/:api_key/balance-transfers

Authentification

Clé	Description	Où	Exemple
Authorization	Clé et secret de l'API encodés en Base64 et reliés par deux points. En savoir plus	Headers	`Basic <base64>`

Trajectoire Paramètres

api_key

string

Exigée

ID of the primary account.

Demande de renseignements Paramètres

start_date

string

Start of the retrieval period.

end_date

string

End of the retrieval period. If absent then all transfers until now is returned.

subaccount

string

Subaccount to filter by. You may send this multiple times to filter on multiple subaccounts

Réponses
Type de contenu
application/json

List balance transfers response

_embedded

object

balance_transfers

array

balance_transfer_id

string

exemple07b5-46e1-a527-85530e625800

Unique balance transfer ID

amount

number

exemple123.45

Balance transfer amount

from

string

exemple7c9738e6

Account the balance is transferred from

string

exemplead6dc56f

Account the balance is transferred to

reference

string

exempleThis gets added to the audit log

Reference for the balance transfer

created_at

string

exemple2019-03-02T16:34:49Z

The date and time when the balance transfer was executed

Exemple Réponse

{
   "_embedded": {
      "balance_transfers": [
         {
            "balance_transfer_id": "07b5-46e1-a527-85530e625800",
            "amount": 123.45,
            "from": "7c9738e6",
            "to": "ad6dc56f",
            "reference": "This gets added to the audit log",
            "created_at": "2019-03-02T16:34:49Z"
         }
      ]
   }
}

Transfer balance

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.

posthttps://api.nexmo.com/accounts/:api_key/balance-transfers

Authentification

Clé	Description	Où	Exemple
Authorization	Clé et secret de l'API encodés en Base64 et reliés par deux points. En savoir plus	Headers	`Basic <base64>`

Trajectoire Paramètres

api_key

string

Exigée

ID of the primary account

Corps de la demande
Type de contenu
application/json

from

string

Exigée

exemple7c9738e6

string

Exigée

exemplead6dc56f

amount

number

Exigée

exemple123.45

reference

string

exempleThis gets added to the audit log

Exemple Demande

{
   "from": "7c9738e6",
   "to": "ad6dc56f",
   "amount": "123.45",
   "reference": "This gets added to the audit log"
}

{
   "from": "7c9738e6",
   "to": "ad6dc56f",
   "amount": "123.45",
   "reference": "This gets added to the audit log"
}

Réponses
Type de contenu
application/json

Balance transfer response

balance_transfer_id

string

exemple07b5-46e1-a527-85530e625800

Unique balance transfer ID

amount

number

exemple123.45

Balance transfer amount

from

string

exemple7c9738e6

Account the balance is transferred from

string

exemplead6dc56f

Account the balance is transferred to

reference

string

exempleThis gets added to the audit log

Reference for the balance transfer

created_at

string

exemple2019-03-02T16:34:49Z

The date and time when the balance transfer was executed

Exemple Réponse

{
   "balance_transfer_id": "07b5-46e1-a527-85530e625800",
   "amount": 123.45,
   "from": "7c9738e6",
   "to": "ad6dc56f",
   "reference": "This gets added to the audit log",
   "created_at": "2019-03-02T16:34:49Z"
}

Transfer number

Transfer number from one account to another.

posthttps://api.nexmo.com/accounts/:api_key/transfer-number

Authentification

Clé	Description	Où	Exemple
Authorization	Clé et secret de l'API encodés en Base64 et reliés par deux points. En savoir plus	Headers	`Basic <base64>`

Trajectoire Paramètres

api_key

string

Exigée

ID of the primary account.

Corps de la demande
Type de contenu
application/json

from

string

exemple7c9738e6

string

exemplead6dc56f

number

exemple23507703696

country

string

exempleGB

Exemple Demande

{
   "from": "7c9738e6",
   "to": "ad6dc56f",
   "number": "23507703696",
   "country": "GB"
}

{
   "from": "7c9738e6",
   "to": "ad6dc56f",
   "number": "23507703696",
   "country": "GB"
}

Réponses
Type de contenu
application/json

Number transfer response

number

string

exemple235077036

Number transfered

country

string

exempleGB

The two character country code in ISO 3166-1 alpha-2 format

from

string

exemple7c9738e6

Account the number is transferred from

string

exemplead6dc56f

Account the number is transferred to

Exemple Réponse

{
   "number": "235077036",
   "country": "GB",
   "from": "7c9738e6",
   "to": "ad6dc56f"
}

Erreurs

Voici une liste non exhaustive des codes d'erreur susceptibles de se produire lors de l'utilisation de cette API.

Ces codes s'ajoutent à ceux de notre site codes d'erreur génériques.

Code	Informations
validation	Description The request failed due to validation errors Résolution See the `detail` (and, if present, the `invalid_parameters`) fields for the exact reason this request was rejected and review the documentation.
invalid-transfers	Description Invalid transfer Résolution See the `detail` field for the reason this transfer is invalid.
provisioning	Description Maximum number of sub-accounts reached Résolution If you need more subaccounts, contact Vonage Support.
internal-error	Description An error has occurred in the platform while processing this request Résolution If the error persists, contact Vonage Support.
invalid-number-transfer	Description Failed to perform transfer number from source account to destination account Résolution See the `detail` field for the reason this transfer is invalid.
missing-number-transfer	Description Could not transfer number from source account to destination account - ShortCode not found Résolution See the `detail` field for the reason this transfer is invalid.
transfer-conflict	Description Could not transfer number from source account to destination account - ShortCode is already owned by requesting account Résolution See the `detail` field for the reason this transfer is invalid.

Subaccounts API

Subaccount Management

Opérations disponibles

Retrieve list of subaccounts

Authentification

Trajectoire Paramètres

Réponses Type de contenuapplication/json

Exemple Réponse

Create subaccount

Authentification

Trajectoire Paramètres

Corps de la demande Type de contenuapplication/json

Exemple Demande

Réponses Type de contenuapplication/json

Exemple Réponse

Retrieve a subaccount

Authentification

Trajectoire Paramètres

Réponses Type de contenuapplication/json

Exemple Réponse

Modify a subaccount

Authentification

Trajectoire Paramètres

Corps de la demande Type de contenuapplication/json

Exemple Demande

Réponses Type de contenuapplication/json

Exemple Réponse

Transfers

Opérations disponibles

Retrieve list of credit transfers

Authentification

Trajectoire Paramètres

Demande de renseignements Paramètres

Réponses Type de contenuapplication/json

Exemple Réponse

Transfer credit

Authentification

Trajectoire Paramètres

Corps de la demande Type de contenuapplication/json

Exemple Demande

Réponses Type de contenuapplication/json

Exemple Réponse

Retrieve list of balance transfers

Authentification

Trajectoire Paramètres

Demande de renseignements Paramètres

Réponses Type de contenuapplication/json

Exemple Réponse

Transfer balance

Authentification

Trajectoire Paramètres

Corps de la demande Type de contenuapplication/json

Exemple Demande

Réponses Type de contenuapplication/json

Exemple Réponse

Transfer number

Authentification

Trajectoire Paramètres

Corps de la demande Type de contenuapplication/json

Exemple Demande

Réponses Type de contenuapplication/json

Exemple Réponse

Erreurs

Réponses
Type de contenu
application/json

Corps de la demande
Type de contenu
application/json

Réponses
Type de contenu
application/json

Réponses
Type de contenu
application/json

Corps de la demande
Type de contenu
application/json

Réponses
Type de contenu
application/json

Réponses
Type de contenu
application/json

Corps de la demande
Type de contenu
application/json

Réponses
Type de contenu
application/json

Réponses
Type de contenu
application/json

Corps de la demande
Type de contenu
application/json

Réponses
Type de contenu
application/json

Corps de la demande
Type de contenu
application/json

Réponses
Type de contenu
application/json