osis-co Capabilities API

openapi: 3.2.0
info:
  title: Comms Capabilities API
  version: 1.0.0
  description: 'Send and receive texts, place and answer calls, and create payment requests from your Comms workspace. Base URL: `https://osis.co/api/v1/comms`. The Payments API has to be turned on for your workspace first.'
servers:
- url: https://osis.co/api/v1/comms
  description: Production
- url: https://comms.osis.co/api/v1/comms
  description: Comms host alias
security:
- bearerAuth: []
tags:
- name: Capabilities
paths:
  /capabilities:
    post:
      operationId: checkMessagingCapabilities
      summary: Check messaging capabilities
      description: See if a phone number or email can get iMessage, RCS, or WhatsApp, without sending anything. Needs comms_read. You don't need your own line. Each channel comes back true, false, or null (unknown). The answer is only true right now and doesn't promise delivery. Emails are only checked for iMessage, so RCS comes back false and WhatsApp comes back null, both with recipient_unsupported. WhatsApp answers are cached for a few hours and rate limited.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
              - to
              properties:
                to:
                  type: string
                  minLength: 1
                  maxLength: 256
                  description: A phone number, or an email address used for iMessage. Up to 254 characters.
                default_country:
                  type: string
                  description: Two-letter country code. Needed if the number is local and has no country code.
            example:
              to: '+12025550123'
      responses:
        '200':
          description: What Comms found right now. null means unknown. It never means false.
          headers:
            Cache-Control:
              schema:
                type: string
                const: no-store
          content:
            application/json:
              schema:
                type: object
                required:
                - to
                - imessage
                - rcs
                - whatsapp
                - checked_at
                - reasons
                properties:
                  to:
                    type: string
                    description: The phone number in E.164 format, or the email in lowercase.
                  imessage:
                    type:
                    - boolean
                    - 'null'
                    description: 'true: yes. false: no. null: unknown.'
                  rcs:
                    type:
                    - boolean
                    - 'null'
                    description: 'true: yes. false: no. null: unknown.'
                  whatsapp:
                    type:
                    - boolean
                    - 'null'
                    description: 'true: the number has a WhatsApp account. false: it doesn''t. null: unknown.'
                  checked_at:
                    type: string
                    format: date-time
                    description: When Comms checked.
                  reasons:
                    type: object
                    additionalProperties: false
                    description: Why a channel came back false or null. Channels that came back true have no reason.
                    properties:
                      imessage:
                        type: string
                        enum:
                        - recipient_unregistered
                        - recipient_unsupported
                        - lookup_inconclusive
                        - recipient_lookup_unavailable
                      rcs:
                        type: string
                        enum:
                        - recipient_unregistered
                        - recipient_unsupported
                        - lookup_inconclusive
                        - recipient_lookup_unavailable
                      whatsapp:
                        type: string
                        enum:
                        - recipient_unregistered
                        - recipient_unsupported
                        - recipient_lookup_unavailable
              example:
                to: '+12025550123'
                imessage: true
                rcs: true
                whatsapp: true
                checked_at: '2026-09-16T12:00:00.000Z'
                reasons: {}
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: string
        '401':
          description: API key is missing or wrong.
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: string
        '403':
          description: Key doesn't have the comms_read scope.
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: string
        '429':
          description: Too many requests.
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: string
        '502':
          description: The check couldn't finish.
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: string
        '503':
          description: Checks are down for a moment. Try again soon.
          content:
            application/json:
              schema:
                type: object
                required:
                - error
                properties:
                  error:
                    type: string
      tags:
      - Capabilities
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: Your API key from the Comms dashboard (`osis_…`).