openapi: 3.2.0
info:
  title: Vonage Transfers 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 Transfers 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: Transfers
  description: This section shows how you execute credit, balance and number transfers, as well as viewing past transactions.
paths:
  /{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'
    servers:
    - url: https://api.nexmo.com/accounts
  /{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'
    servers:
    - url: https://api.nexmo.com/accounts
  /{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'
    servers:
    - url: https://api.nexmo.com/accounts
components:
  responses:
    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
    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
    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
    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
  schemas:
    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
    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
    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
    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
    ListBalanceTransfersResponse:
      properties:
        _embedded:
          type: object
          properties:
            balance_transfers:
              type: array
              items:
                $ref: '#/components/schemas/TransferBalanceResponse'
    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'
    TransferNumberRequest:
      type: object
      properties:
        from:
          type: string
          example: 7c9738e6
        to:
          type: string
          example: ad6dc56f
        number:
          type: number
          example: '23507703696'
        country:
          type: string
          example: GB
    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
    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
  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