> ## Documentation Index
> Fetch the complete documentation index at: https://docs.avraapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Check SMS balance

> Read the balance associated with the configured QuickSend SMS integration.

Use this endpoint to read the balance for the active QuickSend SMS integration in the selected project environment. The result depends on how that integration was configured.

<Info>
  **Live Testing Guide:** Before using **Try it**, create a Development project, then enter its **Client ID** and **Client Secret**. Configure the relevant provider for that project before sending the request.
</Info>

## API endpoint

```text title="POST" theme={null}
https://avraapi.com/api/v1/sms/balance
```

## Request fields

This endpoint accepts an empty JSON object. AvraAPI resolves the configured SMS integration from your Project Client ID and `X-ENV`.

| Field | Required | Rules |
| - | - | - |
| *None* | No | Send `{}` when your HTTP client requires a JSON body. |

Outside the documentation Playground, keep the Project Client Secret on your backend. This endpoint is read-only and does not deduct AvraAPI credits.

## Result fields

| Field | Type | Notes |
| - | - | - |
| `source` | string | `apix_wallet` for a Managed integration, or `quicksend_direct` for a Manual (BYOK) integration. |
| `balance_formatted` | string | A human-readable balance value for the reported source. |
| `provider_response` | object | Present only for Manual (BYOK) integrations. It contains the provider's balance response. |

For a Managed integration, `balance_formatted` is the AvraAPI wallet balance in API credits. **1 USD equals 1,000,000 API credits**. For a Manual (BYOK) integration, the balance is read from the connected QuickSend account and remains provider-formatted.

## Request example

```bash curl theme={null} theme={null}
curl --request POST "https://avraapi.com/api/v1/sms/balance" \
  --header "X-API-KEY: YOUR_PROJECT_CLIENT_ID" \
  --header "X-API-SECRET: YOUR_PROJECT_CLIENT_SECRET" \
  --header "X-ENV: development" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{}'
```

## Response example — Manual (BYOK)

```json theme={null}
{
  "success": true,
  "request_id": "7a5b17fa-0716-45e1-b109-378322b8769f",
  "data": {
    "source": "quicksend_direct",
    "balance_formatted": "473.52",
    "provider_response": {
      "balance": "473.52"
    }
  }
}
```

## Response example — Managed

```json theme={null}
{
  "success": true,
  "request_id": "3251caf2-3d8a-4232-a1fb-b4cfc4846888",
  "data": {
    "source": "apix_wallet",
    "balance_formatted": "285,417,005 credits"
  }
}
```

## Error codes

| HTTP | `error.code` | When it happens | What to do |
| - | - | - | - |
| `401` | <span style={{ whiteSpace: 'nowrap' }}><code>unauthorized</code></span> | Credentials are missing, invalid, inactive, or do not match the selected environment. | Check your backend secret configuration and `X-ENV`. |
| `422` | <span style={{ whiteSpace: 'nowrap' }}><code>provider\_selection\_failed</code></span> | No active QuickSend SMS integration can be selected for the project environment. | Configure or enable the QuickSend integration for the selected environment. |
| `422` | <span style={{ whiteSpace: 'nowrap' }}><code>http\_error</code></span> | The active SMS integration is incomplete or its Manual (BYOK) credentials cannot be used. | Recheck the integration setup and credentials before retrying. |
| `429` | <span style={{ whiteSpace: 'nowrap' }}><code>rate\_limit\_exceeded</code></span> | The configured request limit was reached. | Respect `Retry-After` when present; do not retry in a tight loop. |
| `500` | <span style={{ whiteSpace: 'nowrap' }}><code>internal\_error</code></span> | The balance check could not complete unexpectedly. | Retry only if your workflow permits it, retaining the request ID. |
| `503` | <span style={{ whiteSpace: 'nowrap' }}><code>http\_error</code></span> | QuickSend could not be reached for a Manual (BYOK) balance check. | Retry later; a Managed balance does not call QuickSend. |
| `503` | <span style={{ whiteSpace: 'nowrap' }}><code>project\_paused</code></span> | The project is paused. | Reactivate the project before retrying. |

<Info>
  Keep the JSON `request_id` or `X-APIX-Request-ID` response header with your support record. It is the safest way for AvraAPI support to trace a request.
</Info>

See the [REST API guide](/api-reference/rest-api) for shared credential, privacy, and error-handling guidance.

## Playground resources

The generated reference below lists this endpoint's API standard details: request fields, authorizations, and response schema. The complete integration guide, request and response examples, and endpoint-specific error handling are above.


## OpenAPI

````yaml api-reference/provider-api.openapi.yaml POST /sms/balance
openapi: 3.0.3
info:
  title: AvraAPI Provider API
  version: 1.0.0
  description: >-
    The reviewed public contract for AvraAPI provider services. Operations are
    added to this document only after their route, validation, response,
    privacy, usage, and public-safety contracts have been verified.
servers:
  - url: https://avraapi.com/api/v1
    description: AvraAPI REST API v1
security:
  - ApiKeyHeader: []
    ApiSecretHeader: []
tags:
  - name: Currency
    description: Currency codes, exchange rates, and conversion.
  - name: SMS
    description: Messaging operations through configured AvraAPI providers.
  - name: Security
    description: IP and email security checks.
  - name: Location
    description: IP geolocation and intelligence.
  - name: Utilities
    description: QR code, barcode, and PDF generation.
paths:
  /sms/balance:
    post:
      tags:
        - SMS
      summary: Check SMS balance
      description: >-
        Reads the balance for the active QuickSend SMS integration. A Managed
        integration returns the caller's AvraAPI wallet credits. A Manual (BYOK)
        integration reads its connected QuickSend account balance. This
        operation is read-only and does not deduct AvraAPI credits.
      operationId: checkSmsBalance
      parameters:
        - $ref: '#/components/parameters/XEnvironmentHeader'
        - $ref: '#/components/parameters/AcceptJsonHeader'
        - $ref: '#/components/parameters/XPrivacyModeHeader'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
            examples:
              empty_body:
                summary: Empty JSON object
                value: {}
      responses:
        '200':
          description: Balance associated with the selected SMS integration.
          headers:
            X-APIX-Request-ID:
              $ref: '#/components/headers/RequestIdHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SmsBalanceResponse'
              examples:
                manual_byok:
                  summary: Manual (BYOK) QuickSend balance
                  value:
                    success: true
                    request_id: 7a5b17fa-0716-45e1-b109-378322b8769f
                    data:
                      source: quicksend_direct
                      balance_formatted: '473.52'
                      provider_response:
                        balance: '473.52'
                managed:
                  summary: Managed AvraAPI wallet credits
                  value:
                    success: true
                    request_id: 3251caf2-3d8a-4232-a1fb-b4cfc4846888
                    data:
                      source: apix_wallet
                      balance_formatted: 285,417,005 credits
        '401':
          description: >-
            Missing, invalid, inactive, or environment-mismatched project
            credentials.
          headers:
            X-APIX-Request-ID:
              $ref: '#/components/headers/RequestIdHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SmsUnauthorizedErrorEnvelope'
              examples:
                unauthorized:
                  value:
                    success: false
                    request_id: 3c90c3cc-0d44-4b50-8888-8dd25736052a
                    error:
                      code: unauthorized
                      message: <string>
                      details: {}
                    meta: {}
        '422':
          description: >-
            No active QuickSend SMS integration can be selected for the project
            environment.
          headers:
            X-APIX-Request-ID:
              $ref: '#/components/headers/RequestIdHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SmsProviderSelectionFailedErrorEnvelope'
              examples:
                provider_selection_failed:
                  value:
                    success: false
                    request_id: 3c90c3cc-0d44-4b50-8888-8dd25736052a
                    error:
                      code: provider_selection_failed
                      message: <string>
                      details: {}
                    meta: {}
        '429':
          description: The configured SMS request limit has been reached.
          headers:
            X-APIX-Request-ID:
              $ref: '#/components/headers/RequestIdHeader'
            Retry-After:
              $ref: '#/components/headers/RetryAfterHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SmsRateLimitedErrorEnvelope'
              examples:
                rate_limit_exceeded:
                  value:
                    success: false
                    request_id: 3c90c3cc-0d44-4b50-8888-8dd25736052a
                    error:
                      code: rate_limit_exceeded
                      message: <string>
                      details: {}
                    meta: {}
        '500':
          description: The balance check could not complete unexpectedly.
          headers:
            X-APIX-Request-ID:
              $ref: '#/components/headers/RequestIdHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SmsInternalErrorEnvelope'
              examples:
                internal_error:
                  value:
                    success: false
                    request_id: 3c90c3cc-0d44-4b50-8888-8dd25736052a
                    error:
                      code: internal_error
                      message: <string>
                      details: {}
                    meta: {}
        '503':
          description: QuickSend could not be reached for a Manual (BYOK) balance check.
          headers:
            X-APIX-Request-ID:
              $ref: '#/components/headers/RequestIdHeader'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SmsHttpErrorEnvelope'
              examples:
                http_error:
                  value:
                    success: false
                    request_id: 3c90c3cc-0d44-4b50-8888-8dd25736052a
                    error:
                      code: http_error
                      message: <string>
                      details: {}
                    meta: {}
components:
  parameters:
    XEnvironmentHeader:
      name: X-ENV
      in: header
      required: false
      description: >-
        Selects the Development credential environment. The Documentation
        Playground exposes Development values only; normal backend integrations
        may use their documented Production credentials outside this tool.
      schema:
        type: string
        enum:
          - dev
          - development
        default: development
    AcceptJsonHeader:
      name: Accept
      in: header
      required: false
      description: Requests a JSON response where the selected operation supports JSON.
      schema:
        type: string
        example: application/json
    XPrivacyModeHeader:
      name: X-Privacy-Mode
      in: header
      required: false
      description: >-
        Optional privacy override. Turn this on to request that AvraAPI suppress
        request-payload storage in observability logs for this request.
      schema:
        type: boolean
        default: false
        example: true
  headers:
    RequestIdHeader:
      description: AvraAPI request identifier for support and troubleshooting.
      schema:
        type: string
        format: uuid
    RetryAfterHeader:
      description: Seconds to wait before retrying a rate-limited request.
      schema:
        type: integer
        minimum: 0
  schemas:
    SmsBalanceResponse:
      allOf:
        - $ref: '#/components/schemas/ApiSuccessEnvelope'
        - type: object
          properties:
            data:
              $ref: '#/components/schemas/SmsBalanceData'
    SmsUnauthorizedErrorEnvelope:
      type: object
      required:
        - success
        - request_id
        - error
      properties:
        success:
          type: boolean
          enum:
            - false
        request_id:
          type: string
          format: uuid
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              enum:
                - unauthorized
              example: unauthorized
            message:
              type: string
            details:
              type: object
              additionalProperties: true
        meta:
          type: object
          additionalProperties: true
    SmsProviderSelectionFailedErrorEnvelope:
      type: object
      required:
        - success
        - request_id
        - error
      properties:
        success:
          type: boolean
          enum:
            - false
        request_id:
          type: string
          format: uuid
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              enum:
                - provider_selection_failed
              example: provider_selection_failed
            message:
              type: string
            details:
              type: object
              additionalProperties: true
        meta:
          type: object
          additionalProperties: true
    SmsRateLimitedErrorEnvelope:
      type: object
      required:
        - success
        - request_id
        - error
      properties:
        success:
          type: boolean
          enum:
            - false
        request_id:
          type: string
          format: uuid
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              enum:
                - rate_limit_exceeded
              example: rate_limit_exceeded
            message:
              type: string
            details:
              type: object
              additionalProperties: true
        meta:
          type: object
          additionalProperties: true
    SmsInternalErrorEnvelope:
      type: object
      required:
        - success
        - request_id
        - error
      properties:
        success:
          type: boolean
          enum:
            - false
        request_id:
          type: string
          format: uuid
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              enum:
                - internal_error
              example: internal_error
            message:
              type: string
            details:
              type: object
              additionalProperties: true
        meta:
          type: object
          additionalProperties: true
    SmsHttpErrorEnvelope:
      type: object
      required:
        - success
        - request_id
        - error
      properties:
        success:
          type: boolean
          enum:
            - false
        request_id:
          type: string
          format: uuid
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              enum:
                - http_error
              example: http_error
            message:
              type: string
            details:
              type: object
              additionalProperties: true
        meta:
          type: object
          additionalProperties: true
    ApiSuccessEnvelope:
      type: object
      required:
        - success
        - request_id
        - data
      properties:
        success:
          type: boolean
          enum:
            - true
        request_id:
          type: string
          format: uuid
          description: Include this value when contacting AvraAPI support.
        data:
          description: Operation-specific result data.
          nullable: true
    SmsBalanceData:
      type: object
      required:
        - source
        - balance_formatted
      properties:
        source:
          type: string
          enum:
            - apix_wallet
            - quicksend_direct
          description: The balance source selected by the integration setup method.
        balance_formatted:
          type: string
          description: Human-readable balance value for the reported source.
        provider_response:
          type: object
          nullable: true
          additionalProperties: true
          description: Present only for a Manual (BYOK) QuickSend integration.
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-API-KEY
      description: >-
        Your Development project's Client ID. Enter your own value in the
        Documentation Playground.
    ApiSecretHeader:
      type: apiKey
      in: header
      name: X-API-SECRET
      description: >-
        Your Development project's Client Secret. Mintlify does not proxy these
        requests; the browser sends them directly to AvraAPI. Never enter a
        Production secret in the Documentation Playground.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.