openapi: 3.2.0
info:
  title: Vonage Subaccount Management API
  version: 1.0.8
  contact:
    name: Vonage DevRel
    email: devrel@vonage.com
    url: https://developer.nexmo.com/
  x-metaDescription: Find quick answers to questions about the Vonage Subaccounts API in this reference guide. Learn more in Vonage's API documentation.
  x-metaTitle: Vonage Subaccounts API Reference | Vonage API Documentation
  description: 'Operations tagged Subaccount Management across 2 of this provider''s published API definitions: vonage-subaccounts-openapi.json, vonage-subaccounts-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.nexmo.com/accounts
tags:
- name: Subaccount Management
  description: This section shows how you can create, retrieve and modify subaccounts of a primary account.
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'
    servers:
    - url: https://api.nexmo.com/accounts
  /{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'
    servers:
    - url: https://api.nexmo.com/accounts
components:
  responses:
    ForbiddenError:
      description: Action is forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UnprovisionedErrorResponse'
    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
    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
    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
  schemas:
    SubaccountsAllResponse:
      properties:
        _embedded:
          type: object
          properties:
            primary_account:
              $ref: '#/components/schemas/SubaccountResponse'
            subaccounts:
              type: array
              items:
                $ref: '#/components/schemas/SubaccountResponse'
    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
    SubaccountCreateResponse:
      allOf:
      - properties:
          secret:
            type: string
            example: Password123
            description: API secret of the subaccount.
      - $ref: '#/components/schemas/SubaccountResponse'
    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
    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.
    ModifySubaccountRequest:
      type: object
      properties:
        suspended:
          type: boolean
          example: true
        use_primary_account_balance:
          type: boolean
          example: false
        name:
          type: string
          example: Subaccount department B
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
x-refined-from:
- vonage-subaccounts-openapi.json
- vonage-subaccounts-openapi.yml
x-errors:
  validation:
    description: The provided payload is invalid
    resolution: 'Modify your request to provide a valid payload.

      * Minimum 8 characters

      * Maximum 25 characters

      * Minimum 1 lower case character

      * Minimum 1 upper case character

      * Minimum 1 digit

      '
    link:
      text: View API reference
      url: /api/account#createAPISecret
  delete-last-secret:
    description: You can not delete your only API secret
    resolution: Add another API secret before deleting this one