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.

OpenAPI-Spezifikation herunterladen

Subaccount Management

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

Verfügbare Operationen

Retrieve list of subaccounts

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

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

Authentifizierung

Schlüssel	Beschreibung	Wo	Beispiel
Authorization	Base64-kodierter API-Schlüssel und Geheimnis, verbunden durch einen Doppelpunkt. Mehr lesen	Headers	`Basic <base64>`

Pfad Parameter

api_key

string

Erforderlich

ID of the primary account

Antworten
Inhalt Typ
application/json

Subaccounts response

_embedded

object

primary_account

api_key

string

Beispielbbe6222f

Unique subaccount ID.

name

string

BeispielSubaccount department A

Name of the subaccount.

primary_account_api_key

string

Beispielacc6111f

Unique primary account ID.

use_primary_account_balance

boolean

Beispieltrue

Flag showing if balance is shared with primary account.

created_at

string

Beispiel2018-03-02T16:34:49Z

Subaccount creation date and time.

suspended

boolean

Subaccount suspension status.

balance

number

Beispiel100.25

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

credit_limit

number

Beispiel-100.25

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

subaccounts

array

api_key

string

Beispielbbe6222f

Unique subaccount ID.

name

string

BeispielSubaccount department A

Name of the subaccount.

primary_account_api_key

string

Beispielacc6111f

Unique primary account ID.

use_primary_account_balance

boolean

Beispieltrue

Flag showing if balance is shared with primary account.

created_at

string

Beispiel2018-03-02T16:34:49Z

Subaccount creation date and time.

suspended

boolean

Subaccount suspension status.

balance

number

Beispiel100.25

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

credit_limit

number

Beispiel-100.25

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

Beispiel Antwort

{
   "_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

Authentifizierung

Schlüssel	Beschreibung	Wo	Beispiel
Authorization	Base64-kodierter API-Schlüssel und Geheimnis, verbunden durch einen Doppelpunkt. Mehr lesen	Headers	`Basic <base64>`

Pfad Parameter

api_key

string

Erforderlich

ID of the primary account

Anfrage Körper
Inhalt Typ
application/json

name

string

Erforderlich

Max80

BeispielSubaccount department A

secret

string

BeispielPassword123

use_primary_account_balance

boolean

Standardtrue

Beispiel Anfrage

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

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

Antworten
Inhalt Typ
application/json

Subaccount response

secret

string

BeispielPassword123

API secret of the subaccount.

api_key

string

Beispielbbe6222f

Unique subaccount ID.

name

string

BeispielSubaccount department A

Name of the subaccount.

primary_account_api_key

string

Beispielacc6111f

Unique primary account ID.

use_primary_account_balance

boolean

Beispieltrue

Flag showing if balance is shared with primary account.

created_at

string

Beispiel2018-03-02T16:34:49Z

Subaccount creation date and time.

suspended

boolean

Subaccount suspension status.

balance

number

Beispiel100.25

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

credit_limit

number

Beispiel-100.25

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

Beispiel Antwort

{
   "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

Authentifizierung

Schlüssel	Beschreibung	Wo	Beispiel
Authorization	Base64-kodierter API-Schlüssel und Geheimnis, verbunden durch einen Doppelpunkt. Mehr lesen	Headers	`Basic <base64>`

Pfad Parameter

api_key

string

Erforderlich

ID of the primary account

subaccount_key

string

Erforderlich

ID of the subaccount

Antworten
Inhalt Typ
application/json

Subaccount response

api_key

string

Beispielbbe6222f

Unique subaccount ID.

name

string

BeispielSubaccount department A

Name of the subaccount.

primary_account_api_key

string

Beispielacc6111f

Unique primary account ID.

use_primary_account_balance

boolean

Beispieltrue

Flag showing if balance is shared with primary account.

created_at

string

Beispiel2018-03-02T16:34:49Z

Subaccount creation date and time.

suspended

boolean

Subaccount suspension status.

balance

number

Beispiel100.25

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

credit_limit

number

Beispiel-100.25

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

Beispiel Antwort

{
   "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

Authentifizierung

Schlüssel	Beschreibung	Wo	Beispiel
Authorization	Base64-kodierter API-Schlüssel und Geheimnis, verbunden durch einen Doppelpunkt. Mehr lesen	Headers	`Basic <base64>`

Pfad Parameter

api_key

string

Erforderlich

ID of the primary account

subaccount_key

string

Erforderlich

ID of the subaccount

Anfrage Körper
Inhalt Typ
application/json

suspended

boolean

Beispieltrue

use_primary_account_balance

boolean

name

string

BeispielSubaccount department B

Beispiel Anfrage

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

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

Antworten
Inhalt Typ
application/json

Subaccount response

api_key

string

Beispielbbe6222f

Unique subaccount ID.

name

string

BeispielSubaccount department A

Name of the subaccount.

primary_account_api_key

string

Beispielacc6111f

Unique primary account ID.

use_primary_account_balance

boolean

Beispieltrue

Flag showing if balance is shared with primary account.

created_at

string

Beispiel2018-03-02T16:34:49Z

Subaccount creation date and time.

suspended

boolean

Subaccount suspension status.

balance

number

Beispiel100.25

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

credit_limit

number

Beispiel-100.25

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

Beispiel Antwort

{
   "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.

Verfügbare Operationen

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

Authentifizierung

Schlüssel	Beschreibung	Wo	Beispiel
Authorization	Base64-kodierter API-Schlüssel und Geheimnis, verbunden durch einen Doppelpunkt. Mehr lesen	Headers	`Basic <base64>`

Pfad Parameter

api_key

string

Erforderlich

ID of the primary account.

Abfrage Parameter

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

Antworten
Inhalt Typ
application/json

List credit transfers response

_embedded

object

credit-transfers

array

credit_transfer_id

string

Beispiel07b5-46e1-a527-85530e625800

Unique credit transfer ID

amount

number

Beispiel123.45

Credit transfer amount

from

string

Beispiel7c9738e6

Account the credit is transferred from

string

Beispielad6dc56f

Account the credit is transferred to

reference

string

BeispielThis gets added to the audit log

Reference for the credit transfer

created_at

string

Beispiel2019-03-02T16:34:49Z

The date and time when the credit transfer was executed

Beispiel Antwort

{
   "_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

Authentifizierung

Schlüssel	Beschreibung	Wo	Beispiel
Authorization	Base64-kodierter API-Schlüssel und Geheimnis, verbunden durch einen Doppelpunkt. Mehr lesen	Headers	`Basic <base64>`

Pfad Parameter

api_key

string

Erforderlich

ID of the primary account

Anfrage Körper
Inhalt Typ
application/json

from

string

Erforderlich

Beispiel7c9738e6

string

Erforderlich

Beispielad6dc56f

amount

number

Erforderlich

Beispiel123.45

reference

string

BeispielThis gets added to the audit log

Beispiel Anfrage

{
   "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"
}

Antworten
Inhalt Typ
application/json

Credit transfer response

credit_transfer_id

string

Beispiel07b5-46e1-a527-85530e625800

Unique credit transfer ID

amount

number

Beispiel123.45

Credit transfer amount

from

string

Beispiel7c9738e6

Account the credit is transferred from

string

Beispielad6dc56f

Account the credit is transferred to

reference

string

BeispielThis gets added to the audit log

Reference for the credit transfer

created_at

string

Beispiel2019-03-02T16:34:49Z

The date and time when the credit transfer was executed

Beispiel Antwort

{
   "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

Authentifizierung

Schlüssel	Beschreibung	Wo	Beispiel
Authorization	Base64-kodierter API-Schlüssel und Geheimnis, verbunden durch einen Doppelpunkt. Mehr lesen	Headers	`Basic <base64>`

Pfad Parameter

api_key

string

Erforderlich

ID of the primary account.

Abfrage Parameter

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

Antworten
Inhalt Typ
application/json

List balance transfers response

_embedded

object

balance_transfers

array

balance_transfer_id

string

Beispiel07b5-46e1-a527-85530e625800

Unique balance transfer ID

amount

number

Beispiel123.45

Balance transfer amount

from

string

Beispiel7c9738e6

Account the balance is transferred from

string

Beispielad6dc56f

Account the balance is transferred to

reference

string

BeispielThis gets added to the audit log

Reference for the balance transfer

created_at

string

Beispiel2019-03-02T16:34:49Z

The date and time when the balance transfer was executed

Beispiel Antwort

{
   "_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

Authentifizierung

Schlüssel	Beschreibung	Wo	Beispiel
Authorization	Base64-kodierter API-Schlüssel und Geheimnis, verbunden durch einen Doppelpunkt. Mehr lesen	Headers	`Basic <base64>`

Pfad Parameter

api_key

string

Erforderlich

ID of the primary account

Anfrage Körper
Inhalt Typ
application/json

from

string

Erforderlich

Beispiel7c9738e6

string

Erforderlich

Beispielad6dc56f

amount

number

Erforderlich

Beispiel123.45

reference

string

BeispielThis gets added to the audit log

Beispiel Anfrage

{
   "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"
}

Antworten
Inhalt Typ
application/json

Balance transfer response

balance_transfer_id

string

Beispiel07b5-46e1-a527-85530e625800

Unique balance transfer ID

amount

number

Beispiel123.45

Balance transfer amount

from

string

Beispiel7c9738e6

Account the balance is transferred from

string

Beispielad6dc56f

Account the balance is transferred to

reference

string

BeispielThis gets added to the audit log

Reference for the balance transfer

created_at

string

Beispiel2019-03-02T16:34:49Z

The date and time when the balance transfer was executed

Beispiel Antwort

{
   "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

Authentifizierung

Schlüssel	Beschreibung	Wo	Beispiel
Authorization	Base64-kodierter API-Schlüssel und Geheimnis, verbunden durch einen Doppelpunkt. Mehr lesen	Headers	`Basic <base64>`

Pfad Parameter

api_key

string

Erforderlich

ID of the primary account.

Anfrage Körper
Inhalt Typ
application/json

from

string

Beispiel7c9738e6

string

Beispielad6dc56f

number

Beispiel23507703696

country

string

BeispielGB

Beispiel Anfrage

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

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

Antworten
Inhalt Typ
application/json

Number transfer response

number

string

Beispiel235077036

Number transfered

country

string

BeispielGB

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

from

string

Beispiel7c9738e6

Account the number is transferred from

string

Beispielad6dc56f

Account the number is transferred to

Beispiel Antwort

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

Fehler

Im Folgenden finden Sie eine nicht erschöpfende Liste von Fehlercodes, die bei der Verwendung dieser API auftreten können.

Diese Codes gelten zusätzlich zu unseren generische Fehlercodes.

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

Subaccounts API

Subaccount Management

Verfügbare Operationen

Retrieve list of subaccounts

Authentifizierung

Pfad Parameter

Antworten Inhalt Typapplication/json

Beispiel Antwort

Create subaccount

Authentifizierung

Pfad Parameter

Anfrage Körper Inhalt Typapplication/json

Beispiel Anfrage

Antworten Inhalt Typapplication/json

Beispiel Antwort

Retrieve a subaccount

Authentifizierung

Pfad Parameter

Antworten Inhalt Typapplication/json

Beispiel Antwort

Modify a subaccount

Authentifizierung

Pfad Parameter

Anfrage Körper Inhalt Typapplication/json

Beispiel Anfrage

Antworten Inhalt Typapplication/json

Beispiel Antwort

Transfers

Verfügbare Operationen

Retrieve list of credit transfers

Authentifizierung

Pfad Parameter

Abfrage Parameter

Antworten Inhalt Typapplication/json

Beispiel Antwort

Transfer credit

Authentifizierung

Pfad Parameter

Anfrage Körper Inhalt Typapplication/json

Beispiel Anfrage

Antworten Inhalt Typapplication/json

Beispiel Antwort

Retrieve list of balance transfers

Authentifizierung

Pfad Parameter

Abfrage Parameter

Antworten Inhalt Typapplication/json

Beispiel Antwort

Transfer balance

Authentifizierung

Pfad Parameter

Anfrage Körper Inhalt Typapplication/json

Beispiel Anfrage

Antworten Inhalt Typapplication/json

Beispiel Antwort

Transfer number

Authentifizierung

Pfad Parameter

Anfrage Körper Inhalt Typapplication/json

Beispiel Anfrage

Antworten Inhalt Typapplication/json

Beispiel Antwort

Fehler

Antworten
Inhalt Typ
application/json

Anfrage Körper
Inhalt Typ
application/json

Antworten
Inhalt Typ
application/json

Antworten
Inhalt Typ
application/json

Anfrage Körper
Inhalt Typ
application/json

Antworten
Inhalt Typ
application/json

Antworten
Inhalt Typ
application/json

Anfrage Körper
Inhalt Typ
application/json

Antworten
Inhalt Typ
application/json

Antworten
Inhalt Typ
application/json

Anfrage Körper
Inhalt Typ
application/json

Antworten
Inhalt Typ
application/json

Anfrage Körper
Inhalt Typ
application/json

Antworten
Inhalt Typ
application/json