openapi: 3.1.0
info:
  title: MessageBird Balance Available Numbers Verify API
  description: The MessageBird Balance API provides developers with access to their account balance information. It returns the current payment type, available amount, and currency for the account associated with the API key. This API is useful for monitoring credit usage, building billing dashboards, and setting up automated alerts when account balances fall below a threshold.
  version: '1.0'
  contact:
    name: MessageBird Support
    url: https://support.messagebird.com
  termsOfService: https://www.messagebird.com/en/terms
servers:
- url: https://rest.messagebird.com
  description: Production Server
security:
- accessKey: []
tags:
- name: Verify
  description: Operations for creating, verifying, and managing verification tokens.
paths:
  /verify:
    post:
      operationId: createVerify
      summary: Create a verification
      description: Creates a new Verify object and sends a verification token to the specified recipient via SMS or voice call. The token is generated automatically by the platform.
      tags:
      - Verify
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyCreate'
      responses:
        '201':
          description: Verification created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Verify'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '422':
          description: Unprocessable entity
  /verify/{id}:
    get:
      operationId: viewVerify
      summary: View a verification
      description: Retrieves the details of an existing verification by its unique identifier.
      tags:
      - Verify
      parameters:
      - $ref: '#/components/parameters/verifyIdParam'
      responses:
        '200':
          description: Verification details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Verify'
        '401':
          description: Unauthorized
        '404':
          description: Verification not found
    delete:
      operationId: deleteVerify
      summary: Delete a verification
      description: Deletes an existing verification by its unique identifier, invalidating any pending token.
      tags:
      - Verify
      parameters:
      - $ref: '#/components/parameters/verifyIdParam'
      responses:
        '204':
          description: Verification deleted
        '401':
          description: Unauthorized
        '404':
          description: Verification not found
  /verify/{id}/verify:
    get:
      operationId: verifyToken
      summary: Verify a token
      description: Verifies a token that was sent to the recipient. The token parameter must match the token that was delivered.
      tags:
      - Verify
      parameters:
      - $ref: '#/components/parameters/verifyIdParam'
      - name: token
        in: query
        required: true
        description: The verification token to validate.
        schema:
          type: string
      responses:
        '200':
          description: Token verified successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Verify'
        '401':
          description: Unauthorized
        '404':
          description: Verification not found
        '422':
          description: Token is invalid or expired
components:
  schemas:
    Verify:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the verification.
        href:
          type: string
          format: uri
          description: The URL of the verification resource.
        recipient:
          type: string
          description: The phone number being verified.
        reference:
          type: string
          description: The client reference.
        status:
          type: string
          description: The status of the verification.
          enum:
          - sent
          - expired
          - failed
          - verified
          - deleted
        messages:
          type: object
          description: Links to the associated message objects.
          properties:
            href:
              type: string
              format: uri
              description: The URL of the associated messages.
        createdDatetime:
          type: string
          format: date-time
          description: The date and time when the verification was created.
        validUntilDatetime:
          type: string
          format: date-time
          description: The date and time when the verification token expires.
    VerifyCreate:
      type: object
      required:
      - recipient
      properties:
        recipient:
          type: string
          description: The phone number to verify in international format.
        originator:
          type: string
          description: The sender ID for the verification message.
        reference:
          type: string
          description: A client reference for tracking purposes.
        type:
          type: string
          description: The delivery channel for the verification token.
          enum:
          - sms
          - tts
          default: sms
        template:
          type: string
          description: A custom message template. Use %token to indicate where the token should be placed.
        datacoding:
          type: string
          description: The encoding for the SMS message body.
          enum:
          - plain
          - unicode
          - auto
        timeout:
          type: integer
          description: The expiration time of the token in seconds.
          minimum: 30
          maximum: 259200
          default: 30
        tokenLength:
          type: integer
          description: The number of digits in the verification token.
          minimum: 4
          maximum: 10
          default: 6
        voice:
          type: string
          description: The voice gender for text-to-speech delivery.
          enum:
          - male
          - female
        language:
          type: string
          description: The language for text-to-speech delivery.
  parameters:
    verifyIdParam:
      name: id
      in: path
      required: true
      description: The unique identifier of the verification.
      schema:
        type: string
  securitySchemes:
    accessKey:
      type: apiKey
      in: header
      name: Authorization
      description: Access key authentication in the form of 'AccessKey {accessKey}'.
externalDocs:
  description: Balance API Documentation
  url: https://developers.messagebird.com/api/balance/