openapi: 3.0.3
info:
  title: Prelude Lookup Transactional API
  description: 'Prelude is a phone and email verification, transactional messaging, phone number intelligence (lookup), and anti-fraud API - "the trust layer between your signups and your business." This document models Prelude''s public REST API v2 (base https://api.prelude.dev/v2) across four products: Verify (create / check one-time passcodes over SMS, WhatsApp, RCS, Viber, and voice), Notify (transactional messaging), Lookup / Intel (phone number intelligence - line type, carrier, ported / temporary flags, CNAM), and Watch (anti-fraud risk prediction and feedback). All requests authenticate with a Bearer API key (Authorization: Bearer YOUR_API_KEY) obtained from the Prelude dashboard under All Services > Configure > Keys. Endpoint paths and request / response schemas are grounded in the live Prelude documentation at docs.prelude.so as of 2026-07-11; the Watch events (dispatch-events) endpoint is modeled from documentation references and marked accordingly.'
  version: '2.0'
  contact:
    name: Prelude
    url: https://prelude.so
servers:
- url: https://api.prelude.dev/v2
  description: Prelude API v2
security:
- bearerAuth: []
tags:
- name: Transactional
  description: Send transactional messages over SMS, RCS, and WhatsApp.
paths:
  /notify:
    post:
      operationId: sendTransactionalMessage
      tags:
      - Transactional
      summary: Send a transactional message
      description: Sends a template-based transactional message to a recipient over the best available channel (SMS, RCS, or WhatsApp). Templates are configured with your Prelude Customer Success team.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendMessageRequest'
      responses:
        '200':
          description: The created message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  responses:
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: The request was invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    SendMessageRequest:
      type: object
      required:
      - to
      - template_id
      properties:
        to:
          type: string
          description: The recipient's phone number in E.164 format.
          example: '+30123456789'
        template_id:
          type: string
          description: Template identifier configured by your Customer Success team.
        from:
          type: string
          description: Sender ID.
        variables:
          type: object
          additionalProperties:
            type: string
        locale:
          type: string
          description: BCP-47 language code.
        schedule_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time
        callback_url:
          type: string
          format: uri
        correlation_id:
          type: string
          maxLength: 80
        preferred_channel:
          type: string
          enum:
          - sms
          - rcs
          - whatsapp
        document:
          type: object
          properties:
            url:
              type: string
              format: uri
            filename:
              type: string
        max_auto_retries:
          type: integer
          minimum: 0
          maximum: 6
    Message:
      type: object
      properties:
        id:
          type: string
        to:
          type: string
        template_id:
          type: string
        from:
          type: string
        variables:
          type: object
          additionalProperties:
            type: string
        callback_url:
          type: string
          format: uri
        correlation_id:
          type: string
        schedule_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
        estimated_segment_count:
          type: integer
        encoding:
          type: string
          enum:
          - GSM-7
          - UCS-2
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        type:
          type: string
        request_id:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Bearer API key passed as `Authorization: Bearer YOUR_API_KEY`. Obtain keys from the Prelude dashboard under All Services > Configure > Keys.'