openapi: 3.0.1
info:
  title: Africa's Talking API
  description: >-
    Unified REST API for Africa's Talking communications products: SMS (single,
    bulk, premium, subscriptions), USSD callbacks, Voice (call, transfer, media
    upload, queue status), Airtime, Mobile Data, and Payments (mobile C2B
    checkout, B2C, B2B). Requests authenticate with an `apiKey` header and a
    `username` parameter. Hosts differ per product: messaging, airtime, and
    subscriptions live under api.africastalking.com/version1; voice under
    voice.africastalking.com; mobile data under bundles.africastalking.com; and
    payments under payments.africastalking.com. Sandbox equivalents insert
    `.sandbox.` into each host.
  termsOfService: https://africastalking.com/terms
  contact:
    name: Africa's Talking Support
    url: https://help.africastalking.com
  version: 'version1'
servers:
  - url: https://api.africastalking.com/version1
    description: Messaging, Airtime and Subscription production host
  - url: https://api.sandbox.africastalking.com/version1
    description: Messaging, Airtime and Subscription sandbox host
  - url: https://voice.africastalking.com
    description: Voice production host
  - url: https://bundles.africastalking.com
    description: Mobile Data production host
  - url: https://payments.africastalking.com
    description: Payments production host
security:
  - apiKey: []
tags:
  - name: SMS
    description: Send single and bulk SMS and fetch inbox messages.
  - name: Premium SMS
    description: Premium SMS subscriptions and checkout tokens.
  - name: Voice
    description: Outbound calls, transfers, queue status, and media upload.
  - name: Airtime
    description: Distribute mobile airtime to recipients.
  - name: Mobile Data
    description: Disburse mobile data bundles to recipients.
  - name: Payments
    description: Mobile C2B checkout, B2C, and B2B mobile money transfers.
paths:
  /messaging:
    post:
      operationId: sendMessage
      tags:
        - SMS
      summary: Send SMS
      description: >-
        Send a single or bulk SMS to one or more recipients. Set `bulkSMSMode`
        to 1 for bulk delivery. Provide a registered `from` short code or sender
        ID where available.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/SendMessageRequest'
      responses:
        '201':
          description: Message accepted for delivery.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendMessageResponse'
        '400':
          description: Bad request.
        '401':
          description: Unauthorized - missing or invalid apiKey.
    get:
      operationId: fetchMessages
      tags:
        - SMS
      summary: Fetch inbox messages
      description: Retrieve messages sent to your registered short codes or sender IDs.
      parameters:
        - name: username
          in: query
          required: true
          schema:
            type: string
        - name: lastReceivedId
          in: query
          required: false
          description: ID of the message last processed; 0 fetches from the start.
          schema:
            type: string
            default: '0'
      responses:
        '200':
          description: Inbox messages.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FetchMessagesResponse'
  /checkout/token/create:
    post:
      operationId: createCheckoutToken
      tags:
        - Premium SMS
      summary: Create checkout token
      description: >-
        Generate a checkout token for a phone number, required before creating a
        premium SMS subscription.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - phoneNumber
              properties:
                phoneNumber:
                  type: string
                  description: Subscriber phone number in international format.
                  example: '+254711XXXYYY'
      responses:
        '201':
          description: Checkout token created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckoutTokenResponse'
  /subscription/create:
    post:
      operationId: createSubscription
      tags:
        - Premium SMS
      summary: Create premium SMS subscription
      description: Subscribe a phone number to a premium SMS product using a checkout token.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/SubscriptionRequest'
      responses:
        '201':
          description: Subscription created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionResponse'
  /subscription/delete:
    post:
      operationId: deleteSubscription
      tags:
        - Premium SMS
      summary: Delete premium SMS subscription
      description: Unsubscribe a phone number from a premium SMS product.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - username
                - shortCode
                - keyword
                - phoneNumber
              properties:
                username:
                  type: string
                shortCode:
                  type: string
                keyword:
                  type: string
                phoneNumber:
                  type: string
      responses:
        '201':
          description: Subscription deleted.
  /subscription:
    get:
      operationId: fetchSubscriptions
      tags:
        - Premium SMS
      summary: Fetch premium SMS subscriptions
      parameters:
        - name: username
          in: query
          required: true
          schema:
            type: string
        - name: shortCode
          in: query
          required: true
          schema:
            type: string
        - name: keyword
          in: query
          required: true
          schema:
            type: string
        - name: lastReceivedId
          in: query
          required: false
          schema:
            type: string
            default: '0'
      responses:
        '200':
          description: List of subscriptions.
  /airtime/send:
    post:
      operationId: sendAirtime
      tags:
        - Airtime
      summary: Send airtime
      description: Distribute airtime to one or more recipients. `recipients` is a JSON-encoded array.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/SendAirtimeRequest'
      responses:
        '201':
          description: Airtime request accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendAirtimeResponse'
  /call:
    post:
      operationId: makeCall
      tags:
        - Voice
      summary: Make outbound call
      description: >-
        Initiate an outbound call from a registered Africa's Talking number to
        one or more destination numbers. Served from voice.africastalking.com.
      servers:
        - url: https://voice.africastalking.com
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/MakeCallRequest'
      responses:
        '200':
          description: Call entries queued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MakeCallResponse'
  /queueStatus:
    post:
      operationId: queueStatus
      tags:
        - Voice
      summary: Get queued call status
      description: Return the number of calls currently queued on registered phone numbers.
      servers:
        - url: https://voice.africastalking.com
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - username
                - phoneNumbers
              properties:
                username:
                  type: string
                phoneNumbers:
                  type: string
                  description: Comma-separated list of registered phone numbers.
      responses:
        '200':
          description: Queue status entries.
  /mediaUpload:
    post:
      operationId: uploadMedia
      tags:
        - Voice
      summary: Upload voice media file
      description: Upload a media file to be played on demand by Play, musicOnHold, or ringBackTone.
      servers:
        - url: https://voice.africastalking.com
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - username
                - url
                - phoneNumber
              properties:
                username:
                  type: string
                url:
                  type: string
                  description: HTTP(S) URL of the media file to upload.
                phoneNumber:
                  type: string
                  description: Africa's Talking phone number mapped to your account.
      responses:
        '200':
          description: Media upload accepted.
  /mobile/data/request:
    post:
      operationId: sendMobileData
      tags:
        - Mobile Data
      summary: Send mobile data bundles
      description: Disburse mobile data bundles to a list of recipients. Served from bundles.africastalking.com.
      servers:
        - url: https://bundles.africastalking.com
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MobileDataRequest'
      responses:
        '201':
          description: Mobile data request accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MobileDataResponse'
  /mobile/checkout/request:
    post:
      operationId: mobileCheckout
      tags:
        - Payments
      summary: Mobile C2B checkout
      description: >-
        Initiate a mobile money checkout (customer-to-business) prompting the
        subscriber to authorize payment. Served from payments.africastalking.com.
      servers:
        - url: https://payments.africastalking.com
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MobileCheckoutRequest'
      responses:
        '201':
          description: Checkout initiated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MobileCheckoutResponse'
  /mobile/b2c/request:
    post:
      operationId: mobileB2C
      tags:
        - Payments
      summary: Mobile B2C payment
      description: Send money from your payment wallet to one or more mobile subscribers.
      servers:
        - url: https://payments.africastalking.com
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MobileB2CRequest'
      responses:
        '201':
          description: B2C request accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MobileB2CResponse'
  /mobile/b2b/request:
    post:
      operationId: mobileB2B
      tags:
        - Payments
      summary: Mobile B2B payment
      description: Send money from your business to another business over mobile money rails.
      servers:
        - url: https://payments.africastalking.com
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MobileB2BRequest'
      responses:
        '201':
          description: B2B request accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MobileB2BResponse'
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: apiKey
      description: Africa's Talking API key generated from your account dashboard.
  schemas:
    SendMessageRequest:
      type: object
      required:
        - username
        - to
        - message
      properties:
        username:
          type: string
          description: Your Africa's Talking application username.
        to:
          type: string
          description: Comma-separated recipient phone numbers in international format.
          example: '+254711XXXYYY,+254733YYYZZZ'
        message:
          type: string
          description: The message body to send.
        from:
          type: string
          description: Registered short code or alphanumeric sender ID.
        bulkSMSMode:
          type: integer
          description: Set to 1 to enable bulk SMS delivery.
          enum: [0, 1]
          default: 1
        enqueue:
          type: integer
          description: Set to 1 to enqueue large outbound batches.
          enum: [0, 1]
        keyword:
          type: string
          description: Premium SMS keyword (premium SMS only).
        linkId:
          type: string
          description: Link identifier from an onDemand premium SMS subscription.
        retryDurationInHours:
          type: integer
          description: Hours to retry premium SMS delivery before discarding.
    SendMessageResponse:
      type: object
      properties:
        SMSMessageData:
          type: object
          properties:
            Message:
              type: string
              example: 'Sent to 1/1 Total Cost: KES 0.8000'
            Recipients:
              type: array
              items:
                $ref: '#/components/schemas/Recipient'
    Recipient:
      type: object
      properties:
        statusCode:
          type: integer
          example: 101
        number:
          type: string
          example: '+254711XXXYYY'
        status:
          type: string
          example: Success
        cost:
          type: string
          example: KES 0.8000
        messageId:
          type: string
          example: ATPid_SampleTxnId123
    FetchMessagesResponse:
      type: object
      properties:
        SMSMessageData:
          type: object
          properties:
            Messages:
              type: array
              items:
                type: object
                properties:
                  linkId:
                    type: string
                  text:
                    type: string
                  to:
                    type: string
                  id:
                    type: integer
                  date:
                    type: string
                  from:
                    type: string
    CheckoutTokenResponse:
      type: object
      properties:
        description:
          type: string
          example: Success
        token:
          type: string
          example: CkTkn_SampleCkTknId123
    SubscriptionRequest:
      type: object
      required:
        - username
        - shortCode
        - keyword
        - phoneNumber
        - checkoutToken
      properties:
        username:
          type: string
        shortCode:
          type: string
          description: Premium SMS short code mapped to your account.
        keyword:
          type: string
          description: Premium SMS keyword mapped to your short code.
        phoneNumber:
          type: string
        checkoutToken:
          type: string
          description: Token returned by /checkout/token/create.
    SubscriptionResponse:
      type: object
      properties:
        status:
          type: string
          example: Success
        description:
          type: string
          example: Waiting for user input
    SendAirtimeRequest:
      type: object
      required:
        - username
        - recipients
      properties:
        username:
          type: string
        recipients:
          type: string
          description: >-
            JSON-encoded array of recipient objects, each with phoneNumber,
            currencyCode, amount, and optional maxNumRetry.
          example: '[{"phoneNumber":"+254711XXXYYY","currencyCode":"KES","amount":"100"}]'
        maxNumRetry:
          type: integer
          description: Maximum delivery retries in hours on failure.
    SendAirtimeResponse:
      type: object
      properties:
        errorMessage:
          type: string
          example: None
        numSent:
          type: integer
          example: 1
        totalAmount:
          type: string
          example: KES 100.0000
        totalDiscount:
          type: string
          example: KES 3.0000
        responses:
          type: array
          items:
            type: object
            properties:
              phoneNumber:
                type: string
              amount:
                type: string
              status:
                type: string
              requestId:
                type: string
              discount:
                type: string
              errorMessage:
                type: string
    MakeCallRequest:
      type: object
      required:
        - username
        - from
        - to
      properties:
        username:
          type: string
        from:
          type: string
          description: Registered Africa's Talking phone number to dial out with.
          example: '+254711XXXYYY'
        to:
          type: string
          description: Comma-separated destination phone numbers.
          example: '+254733YYYZZZ'
        clientRequestId:
          type: string
          description: Variable sent to your Events Callback URL for this call.
    MakeCallResponse:
      type: object
      properties:
        entries:
          type: array
          items:
            type: object
            properties:
              phoneNumber:
                type: string
              status:
                type: string
                example: Queued
              sessionId:
                type: string
        errorMessage:
          type: string
          example: None
    MobileDataRequest:
      type: object
      required:
        - username
        - productName
        - recipients
      properties:
        username:
          type: string
        productName:
          type: string
          description: Registered payment product name.
        recipients:
          type: array
          items:
            type: object
            required:
              - phoneNumber
              - quantity
              - unit
              - validity
            properties:
              phoneNumber:
                type: string
                example: '+254711XXXYYY'
              quantity:
                type: number
                example: 50
              unit:
                type: string
                enum: [MB, GB]
              validity:
                type: string
                enum: [Day, Week, Month]
              metadata:
                type: object
                additionalProperties:
                  type: string
    MobileDataResponse:
      type: object
      properties:
        entries:
          type: array
          items:
            type: object
            properties:
              phoneNumber:
                type: string
              provider:
                type: string
              status:
                type: string
                example: Queued
              transactionId:
                type: string
              value:
                type: string
    MobileCheckoutRequest:
      type: object
      required:
        - username
        - productName
        - phoneNumber
        - currencyCode
        - amount
      properties:
        username:
          type: string
        productName:
          type: string
        phoneNumber:
          type: string
          example: '+254711XXXYYY'
        currencyCode:
          type: string
          description: 3-letter ISO currency code.
          example: KES
        amount:
          type: number
          example: 100.5
        providerChannel:
          type: string
        metadata:
          type: object
          additionalProperties:
            type: string
    MobileCheckoutResponse:
      type: object
      properties:
        status:
          type: string
          example: PendingConfirmation
        description:
          type: string
          example: Waiting for user input
        transactionId:
          type: string
          example: ATPid_SampleTxnId123
    MobileB2CRequest:
      type: object
      required:
        - username
        - productName
        - recipients
      properties:
        username:
          type: string
        productName:
          type: string
        recipients:
          type: array
          items:
            type: object
            required:
              - phoneNumber
              - currencyCode
              - amount
            properties:
              phoneNumber:
                type: string
              currencyCode:
                type: string
                example: KES
              amount:
                type: number
              reason:
                type: string
                description: Purpose of payment, e.g. SalaryPayment, BusinessPayment.
              metadata:
                type: object
                additionalProperties:
                  type: string
    MobileB2CResponse:
      type: object
      properties:
        numQueued:
          type: integer
          example: 1
        totalValue:
          type: string
          example: KES 100.0000
        totalTransactionFee:
          type: string
        entries:
          type: array
          items:
            type: object
            properties:
              phoneNumber:
                type: string
              status:
                type: string
                example: Queued
              provider:
                type: string
              providerChannel:
                type: string
              value:
                type: string
              transactionId:
                type: string
              transactionFee:
                type: string
    MobileB2BRequest:
      type: object
      required:
        - username
        - productName
        - provider
        - transferType
        - currencyCode
        - amount
        - destinationChannel
        - destinationAccount
      properties:
        username:
          type: string
        productName:
          type: string
        provider:
          type: string
          description: Mobile money provider, e.g. Mpesa, Athena.
        transferType:
          type: string
          description: e.g. BusinessBuyGoods, BusinessPayBill, DisburseFundsToBusiness, BusinessToBusinessTransfer.
        currencyCode:
          type: string
          example: KES
        amount:
          type: number
        destinationChannel:
          type: string
          description: Paybill or till channel of the receiving business.
        destinationAccount:
          type: string
          description: Account name of the receiving business.
        metadata:
          type: object
          additionalProperties:
            type: string
    MobileB2BResponse:
      type: object
      properties:
        status:
          type: string
          example: Queued
        transactionId:
          type: string
        transactionFee:
          type: string
        providerChannel:
          type: string