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