BulkSMS Blocked Numbers API

openapi: 3.2.0
info:
  title: BulkSMS JSON REST Blocked Numbers API
  version: 1.1.0
  x-logo:
    url: /developer/images/bulksms-logo-main.svg
    backgroundColor: '#FFFFFF'
  description: '## Overview


    The JSON REST API allows you to submit and receive BulkSMS messages.'
servers:
- url: https://api.bulksms.com/v1
  description: Production
security:
- basicAuth: []
tags:
- name: Blocked Numbers
  description: Blocked number management operations
paths:
  /blocked-numbers:
    get:
      tags:
      - Blocked Numbers
      operationId: blocked.list
      summary: List blocked numbers
      description: Returns a list of phone numbers that are blocked for this account.
      parameters:
      - in: query
        name: min-id
        description: Records with an `id` that is greater or equal to min-id will be returned. The default value is `0`.  You can add 1 to an id that you previously retrieved, to return subsequent records.
        schema:
          type: integer
          format: int32
      - in: query
        name: limit
        description: The maximum number of records to return. The default value is `10000`. The value cannot be greater than 10000.
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: A list of BlockedNumber objects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BlockedNumber'
    post:
      tags:
      - Blocked Numbers
      operationId: blocked.create
      summary: Create a blocked number
      description: 'Blocked numbers are phone numbers to which your account is not permitted to send messages.

        The numbers can be created via this API, by a recipient replying with a STOP message to one

        of your previous SENT messages, or by a BulkSMS administrator.


        Sending a message to a blocked number will result in the message being assigned a status of

        `FAILED.BLOCKED`. Messages sent to blocked numbers are billed to your account.'
      requestBody:
        required: true
        description: 'Maximum size: `1000` items'
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/PhoneNumber'
      responses:
        '200':
          description: Empty body upon success.
components:
  schemas:
    PhoneNumber:
      type: string
      example: '44123456789'
      description: A phone number in E.164 format
    BlockedNumber:
      type: object
      required:
      - id
      - phoneNumber
      properties:
        id:
          type: number
          format: int32
          example: 234
          description: A unique identifier that is assigned when the BlockedNumber is created.
        phoneNumber:
          allOf:
          - $ref: '#/components/schemas/PhoneNumber'
        created:
          type: string
          format: date-time
          description: The date-time when the blocked number was created.
        description:
          type: string
          description: A note describing why the number is blocked.
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: 'The API uses HTTP Basic Auth with an **API Token** for authentication.


        API tokens can be created by logging into your account and visiting _Settings > Developer Settings > API Tokens_.


        Supply the token ID as the username and the token secret as the password. The values must be [Base64 encoded](https://en.wikipedia.org/wiki/Base64) before using them in the `Authorization` header.


        For example, if the token ID is `BBDE1B476E03498AA768F66A286AABDC-01-B` and the token secret is `9jSbVDK20!MXdfRGiIIFu#ffUE8*S`, the unencoded header value is `BBDE1B476E03498AA768F66A286AABDC-01-B:9jSbVDK20!MXdfRGiIIFu#ffUE8*S`.  After encoding, the full header becomes


        ```

        Authorization: Basic QkJERTFCNDc2RTAzNDk4QUE3NjhGNjZBMjg2QUFCREMtMDEtQjo5alNiVkRLMjAhTVhkZlJHaUlJRnUjZmZVRTgqUw==

        ```


        You are requested to preemptively provide the `Authorization` header in your requests and not wait until the server has provided a `401 Unauthorized` response. Doing so will reduce the number of requests required to achieve your goal, which will improve overall performance.


        > **Username and password authentication is no longer supported.** Accounts created after 2026-04-29 can only authenticate with an API token. If you have a legacy integration that cannot be switched to token-based authentication, please [contact Support](https://www.bulksms.com/contact/) to request an exemption.

        '