openapi: 3.1.2
info:
  title: SendPulse SMS API
  description: >
    The SendPulse SMS API enables global mobile messaging, contact management, 
    and campaign orchestration. It supports alphanumeric sender IDs, bulk
    messaging,  and advanced segmentation through variables.
  version: 1.0.0
  x-ai-description: >
    Comprehensive SMS gateway for global mobile marketing and transactional
    notifications.  This API provides direct access to telecommunication routes
    with localized routing  intelligence and high-speed delivery capabilities.
  license:
    name: Apache 2.0
    identifier: Apache-2.0
servers:
  - url: https://api.sendpulse.com
paths:
  /sms/numbers:
    post:
      summary: Add phone numbers to a mailing list
      operationId: addSmsNumbers
      tags:
        - Contacts
      x-ai-role: sms_marketing_specialist
      x-ai-description: >
        Imports a batch of phone numbers into a designated address book.  This
        is the baseline operation for building a mobile audience.
      x-ai-reasoning-instructions:
        - Verify the `addressBookId` exists before attempting the import.
        - Ensure phone numbers are in international E.164 format (e.g., 380...).
      x-ai-responding-instructions:
        - Report the total number of successfully added contacts.
        - Note if any numbers were skipped due to existing in the list.
      x-ai-suggestions:
        - >-
          Use `addSmsNumbersWithVariables` if you have metadata like names or
          dates.
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
            - ResourceStateUpdate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - addressBookId
                - phones
              properties:
                addressBookId:
                  type: integer
                phones:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: Import result
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: boolean
                  counters:
                    type: object
                    properties:
                      added:
                        type: integer
                      exceptions:
                        type: integer
                      exists:
                        type: integer
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
    put:
      summary: Update variables for multiple phone numbers
      operationId: updateSmsVariablesBatch
      tags:
        - Contacts
      x-ai-role: sms_marketing_specialist
      x-ai-description: >
        Batch updates variable values for a set of phone numbers.  Critical for
        keeping contact data like 'Last Purchase' or 'Loyalty Points'
        synchronized.
      x-ai-reasoning-instructions:
        - >-
          Validate that the `variables` array contains correctly structured
          objects (name, type, value).
      x-ai-responding-instructions:
        - Confirm the number of contacts updated.
      x-ai-suggestions:
        - Use this to refresh campaign-specific variables before a blast.
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
            - ResourceStateUpdate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - addressBookId
                - phones
                - variables
              properties:
                addressBookId:
                  type: integer
                phones:
                  type: array
                  items:
                    type: string
                variables:
                  type: array
                  items:
                    type: object
                    required:
                      - name
                      - type
                      - value
                    properties:
                      name:
                        type: string
                      type:
                        type: string
                        enum:
                          - string
                          - number
                          - date
                      value:
                        oneOf:
                          - type: string
                          - type: number
      responses:
        '200':
          description: Update result
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    result:
                      type: boolean
                    counters:
                      type: object
                      properties:
                        updated:
                          type: integer
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
    delete:
      summary: Remove phone numbers from a mailing list
      operationId: removeSmsNumbers
      tags:
        - Contacts
      x-ai-role: compliance_officer
      x-ai-description: >
        Surgically removes specific mobile contacts from an address book. 
        Unlike the blacklist, this does not prevent future re-subscription.
      x-ai-reasoning-instructions:
        - Confirm the exact `addressBookId` to avoid cross-list deletions.
      x-ai-responding-instructions:
        - State clearly how many numbers were removed.
      x-ai-suggestions:
        - Use this for list hygiene (e.g., removing unengaged users).
      x-ai-capabilities:
        confirmation:
          type: Required
        security_info:
          data_handling:
            - ResourceStateUpdate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - addressBookId
                - phones
              properties:
                addressBookId:
                  type: integer
                phones:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: Deletion result
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: boolean
                  counters:
                    type: object
                    properties:
                      deleted:
                        type: integer
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
  /sms/numbers/variables:
    post:
      summary: Add phone numbers with complex variables
      operationId: addSmsNumbersWithVariables
      tags:
        - Contacts
      x-ai-role: sms_marketing_specialist
      x-ai-description: >
        Advanced contact ingestion endpoint that maps specific variables to 
        each phone number in a single payload. Ideal for personalized
        onboarding.
      x-ai-reasoning-instructions:
        - Note that `date` variable format must be `YYYY-MM-DD` (no time).
      x-ai-responding-instructions:
        - Confirm successful ingestion and variable mapping.
      x-ai-suggestions:
        - Structure your CRM export to match this schema for seamless sync.
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
            - ResourceStateUpdate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - addressBookId
                - phones
              properties:
                addressBookId:
                  type: integer
                phones:
                  type: object
                  additionalProperties:
                    type: array
                    items:
                      type: array
                      items:
                        type: object
                        required:
                          - name
                          - type
                          - value
                        properties:
                          name:
                            type: string
                          type:
                            type: string
                          value:
                            type: string
      responses:
        '200':
          description: Batch result
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    result:
                      type: boolean
                    counters:
                      type: object
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
  /addressbooks/{id}/phone:
    put:
      summary: Change a phone number for a contact
      operationId: updateContactPhone
      tags:
        - Contacts
      parameters: []
      x-ai-role: customer_engagement_specialist
      x-ai-description: >
        Maps an SMS identity to an existing email-based contact record.  Enables
        multi-channel communication (Email + SMS) for a single user entity.
      x-ai-reasoning-instructions:
        - Check if the contact exists by email first.
      x-ai-responding-instructions:
        - Confirm the user is now reachable via both Email and SMS.
      x-ai-suggestions:
        - >-
          Check if the phone number is already associated with another email to
          prevent duplication.
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
            - ResourceStateUpdate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - phone
              properties:
                email:
                  type: string
                phone:
                  type: string
      responses:
        '200':
          description: Successfully updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: boolean
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
  /addressbooks/{id}/phones/variable:
    post:
      summary: Change variables for a single phone contact
      operationId: updateSmsVariablesSingle
      tags:
        - Contacts
      parameters: []
      x-ai-role: customer_engagement_specialist
      x-ai-description: >
        Targeted update of metadata for a specific SMS contact within a list. 
        Useful for real-time updates (e.g., updating 'Last Visited' after a
        store visit).
      x-ai-reasoning-instructions:
        - Strictly follow the `YYYY-MM-DD` format for date variables.
      x-ai-responding-instructions:
        - Confirm the variables have been updated for the contact.
      x-ai-suggestions:
        - Ensure the `id` corresponds to the correct address book.
      x-ai-capabilities:
        confirmation:
          type: None
        security_info:
          data_handling:
            - ResourceStateUpdate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - phone
                - variables
              properties:
                phone:
                  type: string
                variables:
                  type: array
                  items:
                    type: object
                    required:
                      - name
                      - value
                    properties:
                      name:
                        type: string
                      value:
                        oneOf:
                          - type: string
                          - type: number
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: boolean
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
  /sms/numbers/info/{addressBookId}/{phoneNumber}:
    get:
      summary: Get information for a specific phone number
      operationId: getSmsNumberInfo
      tags:
        - Contacts
      parameters: []
      x-ai-role: customer_engagement_specialist
      x-ai-description: >
        Retrieves the profile of a mobile contact, including their current 
        variable values and the date they were added to the list.
      x-ai-reasoning-instructions:
        - Verify the status (e.g., 1 for active).
      x-ai-responding-instructions:
        - Summarize the contact's current metadata.
      x-ai-suggestions:
        - If status is inactive, investigate if the user was blacklisted.
      x-ai-capabilities:
        confirmation:
          type: None
      responses:
        '200':
          description: Contact profile
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    result:
                      type: boolean
                    data:
                      type: object
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
    parameters:
      - name: addressBookId
        in: path
        required: true
        schema:
          type: integer
      - name: phoneNumber
        in: path
        required: true
        schema:
          type: string
  /sms/black_list:
    post:
      summary: Add phone numbers to the blacklist
      operationId: addSmsBlacklist
      tags:
        - Compliance
      x-ai-role: compliance_officer
      x-ai-description: >
        Global suppression for SMS. Prevents any future messages from being 
        sent to these numbers across all address books.
      x-ai-reasoning-instructions:
        - >-
          Require a `description` to track the reason for blacklisting (e.g.,
          'Spam complaint').
      x-ai-responding-instructions:
        - Confirm global suppression is active for these numbers.
      x-ai-suggestions:
        - Use this for 'Do Not Call' requests.
      x-ai-capabilities:
        confirmation:
          type: Required
        security_info:
          data_handling:
            - ResourceStateUpdate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - phones
                - description
              properties:
                phones:
                  type: array
                  items:
                    type: string
                description:
                  type: string
      responses:
        '200':
          description: Blacklist result
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
    delete:
      summary: Remove a phone number from the blacklist
      operationId: removeSmsBlacklist
      tags:
        - Compliance
      x-ai-role: compliance_officer
      x-ai-description: >
        Lifts the global suppression for specific numbers.  Only perform this if
        the user has explicitly re-consented.
      x-ai-reasoning-instructions:
        - Ensure audit logs reflect why the suppression was lifted.
      x-ai-responding-instructions:
        - Confirm the numbers are no longer suppressed.
      x-ai-capabilities:
        confirmation:
          type: Required
        security_info:
          data_handling:
            - ResourceStateUpdate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - phones
              properties:
                phones:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: Removal result
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
    get:
      summary: Get a list of contacts in the blacklist
      operationId: getSmsBlacklist
      tags:
        - Compliance
      x-ai-role: compliance_officer
      x-ai-description: |
        Retrieves the master suppression list for auditing and external sync.
      x-ai-responding-instructions:
        - Present the current list of suppressed numbers.
      x-ai-suggestions:
        - Export this list for internal CRM synchronization.
      x-ai-capabilities:
        confirmation:
          type: None
      responses:
        '200':
          description: Blacklist data
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
  /sms/campaigns:
    post:
      summary: Create a campaign for a mailing list
      operationId: createSmsCampaign
      tags:
        - Campaigns
      x-ai-role: sms_marketing_specialist
      x-ai-description: >
        Triggers a bulk SMS broadcast to an entire address book.  Supports
        dynamic content, link tracking, and scheduled delivery.
      x-ai-reasoning-instructions:
        - 'Note: `sender` ID must be pre-registered (max 11 chars).'
        - 'Use `emulate: true` to test logic without burning credits.'
        - >-
          Consider `use_dynamic_list: true` for scheduled campaigns to include
          late subscribers.
      x-ai-responding-instructions:
        - Report the unique `campaign_id` generated.
        - Remind the user that moderation may delay delivery by a few minutes.
      x-ai-suggestions:
        - Newsletter_Launch
        - Flash_Sale_Promo
      x-ai-capabilities:
        confirmation:
          type: Required
        security_info:
          data_handling:
            - ResourceStateUpdate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - sender
                - addressBookId
                - body
              properties:
                sender:
                  type: string
                  maxLength: 11
                addressBookId:
                  type: integer
                body:
                  type: string
                route:
                  type: object
                  description: e.g. {'UA':'national'}
                date:
                  type: string
                  format: date-time
                emulate:
                  type: boolean
                  default: false
                use_dynamic_list:
                  type: boolean
                  default: false
                stat_link_tracking:
                  type: boolean
                  default: false
                stat_link_need_protocol:
                  type: boolean
                  default: false
      responses:
        '200':
          description: Campaign created
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: boolean
                  campaign_id:
                    type: integer
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
    delete:
      summary: Delete a campaign
      operationId: deleteSmsCampaign
      tags:
        - Campaigns
      x-ai-role: sms_marketing_specialist
      x-ai-description: >
        Permanently deletes a campaign record. Only available for campaigns that
        haven't started.
      x-ai-reasoning-instructions:
        - Check campaign status before attempting deletion.
      x-ai-responding-instructions:
        - Confirm deletion of the campaign.
      x-ai-capabilities:
        confirmation:
          type: Required
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - id
              properties:
                id:
                  type: integer
      responses:
        '200':
          description: Deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: boolean
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
  /sms/send:
    post:
      summary: Create a campaign for a list of phone numbers
      operationId: sendSmsToNumbers
      tags:
        - Campaigns
      x-ai-role: sms_marketing_specialist
      x-ai-description: >
        Fast-track broadcast for ad-hoc lists not stored in an address book. 
        Perfect for one-off alerts or external CRM triggers.
      x-ai-reasoning-instructions:
        - Validate all numbers in the `phones` array are valid.
      x-ai-responding-instructions:
        - Report how many messages were successfully queued.
      x-ai-suggestions:
        - Use for 2FA codes or urgent system alerts.
      x-ai-capabilities:
        confirmation:
          type: Required
        security_info:
          data_handling:
            - ResourceStateUpdate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - sender
                - phones
                - body
              properties:
                sender:
                  type: string
                phones:
                  type: array
                  items:
                    type: string
                body:
                  type: string
                date:
                  type: string
                route:
                  type: object
                emulate:
                  type: boolean
                stat_link_tracking:
                  type: boolean
                stat_link_need_protocol:
                  type: boolean
      responses:
        '200':
          description: Send result
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: boolean
                  campaign_id:
                    type: integer
                  counters:
                    type: object
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
  /sms/campaigns/list:
    get:
      summary: Get a list of campaigns by date
      operationId: getSmsCampaigns
      tags:
        - Campaigns
      x-ai-role: marketing_automation_specialist
      x-ai-description: >
        Retrieves campaign history within a specific time window.  Useful for
        building performance dashboards.
      x-ai-reasoning-instructions:
        - Use `dateFrom` and `dateTo` to avoid over-fetching.
      x-ai-responding-instructions:
        - Summarize the campaigns found in the requested period.
      x-ai-suggestions:
        - Track `company_price` to monitor spend trends.
      x-ai-capabilities:
        confirmation:
          type: None
      parameters:
        - name: dateFrom
          in: query
          schema:
            type: string
        - name: dateTo
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Campaign list
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: boolean
                  data:
                    type: array
                    items:
                      type: object
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
  /sms/campaigns/info/{id}:
    get:
      summary: Get campaign information
      operationId: getSmsCampaignInfo
      tags:
        - Campaigns
      parameters: []
      x-ai-role: sms_marketing_specialist
      x-ai-description: >
        Returns granular status for a campaign, including delivery breakdowns
        per phone.
      x-ai-reasoning-instructions:
        - Examine `status` (2 for Delivered, 12 for Not Delivered).
      x-ai-responding-instructions:
        - Report delivery success rates and spend for this campaign.
      x-ai-suggestions:
        - Re-send to 'Not delivered' contacts if the failure was transient.
      x-ai-capabilities:
        confirmation:
          type: None
      responses:
        '200':
          description: Campaign stats
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
  /sms/campaigns/cancel/{id}:
    put:
      summary: Cancel a campaign before sending has started
      operationId: cancelSmsCampaign
      tags:
        - Campaigns
      parameters: []
      x-ai-role: sms_marketing_specialist
      x-ai-description: >
        Stops a scheduled campaign from being sent.  Emergency override for
        erroneous scheduling.
      x-ai-reasoning-instructions:
        - Verify that sending has not already commenced.
      x-ai-responding-instructions:
        - Confirm the campaign has been successfully halted.
      x-ai-suggestions:
        - Check account balance to ensure credits are released.
      x-ai-capabilities:
        confirmation:
          type: Required
      responses:
        '200':
          description: Cancellation result
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: boolean
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
  /sms/campaigns/cost:
    get:
      summary: Calculate the cost of a campaign
      operationId: calculateSmsCost
      tags:
        - Campaigns
      x-ai-role: compliance_officer
      x-ai-description: >
        Estimates the total credit expenditure for a proposed campaign.  Crucial
        for budget planning before actual broadcast.
      x-ai-reasoning-instructions:
        - Note that parameters must be URL-encoded.
        - Provide either `addressBookId` or `phones` array.
      x-ai-responding-instructions:
        - Report the estimated price and currency.
      x-ai-suggestions:
        - >-
          Adjust the message `body` to fit within single SMS segments (160
          chars) to save costs.
      x-ai-capabilities:
        confirmation:
          type: None
      parameters:
        - name: addressBookId
          in: query
          schema:
            type: integer
        - name: phones
          in: query
          schema:
            type: array
            items:
              type: string
        - name: body
          in: query
          required: true
          schema:
            type: string
        - name: sender
          in: query
          required: true
          schema:
            type: string
        - name: route
          in: query
          schema:
            type: object
      responses:
        '200':
          description: Cost estimate
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: boolean
                  data:
                    type: object
                    properties:
                      price:
                        type: number
                      currency:
                        type: string
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
  /sms/senders:
    get:
      summary: Get list of sender IDs
      operationId: getSmsSenders
      tags:
        - Configuration
      x-ai-role: sms_marketing_specialist
      x-ai-description: >
        Retrieves all approved Alphanumeric Sender IDs.  Only IDs with status
        'Active' (1) can be used for campaigns.
      x-ai-reasoning-instructions:
        - 'Check `status` (0: Moderation, 1: Active, 2: Rejected).'
      x-ai-responding-instructions:
        - Present the list of available sender identities.
      x-ai-suggestions:
        - If a sender is 'On moderation', wait before scheduling campaigns.
      x-ai-capabilities:
        confirmation:
          type: None
      responses:
        '200':
          description: Sender ID list
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    sender:
                      type: string
                    country:
                      type: string
                    status:
                      type: integer
                    status_explain:
                      type: string
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
security:
  - apiKey: []
  - oauth2: []
components:
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >
        Static API Key authentication.  A long-lived token generated manually in
        the SendPulse account settings.
      x-ai-description: >
        Permanent authentication token. Ideal for simple integrations without
        token refresh logic.
    oauth2:
      type: oauth2
      description: OAuth 2.0 Client Credentials flow for temporary access tokens.
      flows:
        clientCredentials:
          tokenUrl: https://api.sendpulse.com/oauth/access_token
          scopes: {}
      x-ai-description: >
        Standard OAuth 2.0 flow using Client ID and Client Secret.  Provides
        temporary tokens (valid for 1 hour) for enhanced security.
