Skip to main content

Transfer SMS Balance

The SMS balance transfer operation allows you to transfer SMS channel balance between two organizations.

The specified balance amount is deducted from the source organization and added to the destination organization.

Parameters​

The operation accepts the following fields:

  • sourceOrganizationId – Identifier of the organization from which the balance will be deducted
  • destinationOrganizationId – Identifier of the organization to which the balance will be added
  • amount – Amount of balance to transfer between the two organizations
  • countryId – Country code for the SMS traffic balance to be transferred. This code must follow the ISO 3166-1 alpha-2 standard. In addition to the countries defined by the standard, you may also specify the RoW destination, which represents a balance counter for an unspecified country. Both organizations involved in the transfer must have this destination previously contracted for it to be eligible for balance transfer operations.
  • reason – Free-text description of the transfer

Example:

{
  "sourceOrganizationId":"2ebcea9a-a354-4ef3-b240-69bd56043ace",
  "destinationOrganizationId":"55f06978-2ba9-4e61-842b-3c1d33022173",
  "amount":"1000",
  "reason":"Fulfilling sales department request",
  "countryId": "PT"
}

Response​

The response returns the current balance information for both organizations involved in the transfer. It contains a transferResult object with the following fields:

  • sourceOrganization – Current balance information for the source organization
  • destinationOrganization – Current balance information for the destination organization

Example:

{
  "transferResult": {
    "sourceOrganization": {
      "organizationId": "2ebcea9a-a354-4ef3-b240-69bd56043ace",
      "channels": {
        "email": {
          "values": [
            {
              "balance": 1588
            }
          ]
        },
        "sms": {
          "values": [
            {
              "countryId": "PT",
              "balance": 88
            },
            {
              "countryId": "RoW",
              "balance": 78
            }
          ]
        }
      },
      "error": null
    },
    "destinationOrganization": {
      "organizationId": "55f06978-2ba9-4e61-842b-3c1d33022173",
      "channels": {
        "email": {
          "values": [
            {
              "balance": 69
            }
          ]
        },
        "sms": {
          "values": [
            {
              "countryId": "PT",
              "balance": 9
            },
            {
              "countryId": "RoW",
              "balance": 97545
            }
          ]
        }
      },
      "error": null
    }
  },
  "error": {
    "code": null,
    "param": null,
    "description": null
  }
}

Errors​

In error scenarios, the errorCode property specifies the type of error that occurred. The complete list of error codes is available here.

Go to the API Reference