openapi: 3.2.0
info:
  title: Sendoso Core Campaigns API
  version: '3'
  summary: Automate physical gift, direct mail and eGift sending, and read campaigns, users and teams.
  description: 'The Sendoso Core API (v3) lets you programmatically trigger sends, embed sending into your own forms, and read the campaigns ("touches"), users and team groups behind them. Sendoso describes the API as "organized around REST principles ... predictable, resource-oriented URLs ... HTTP response codes to indicate API errors", supporting GET and POST with JSON request and response bodies.


    Sendoso does not publish an OpenAPI document. This description was generated by API Evangelist from Sendoso''s own published reference pages at https://developer.sendoso.com — every path, method, parameter and response field below is traceable to the page named in that operation''s `externalDocs`.'
  contact:
    name: Sendoso Developer Support
    email: developers@sendoso.com
    url: https://developer.sendoso.com/
  x-generated-from: documentation
  x-generated-by: API Evangelist enrichment pipeline (local-v1)
  x-generated-on: '2026-08-13'
  x-source-docs: https://developer.sendoso.com/llms.txt
servers:
- url: https://app.sendoso.com
  description: Production
- url: https://app.staging.sendo.so
  description: Sandbox / staging (declared in Sendoso's own reference-page code samples)
security:
- OAuth2: []
tags:
- name: Campaigns
  description: Campaigns, called "touches" in the API.
paths:
  /api/v3/touches:
    get:
      operationId: getCampaigns
      summary: Get All Campaigns
      description: Retrieve a list of all active campaigns associated to the organization.
      tags:
      - Campaigns
      externalDocs:
        url: https://developer.sendoso.com/rest-api/reference/campaigns/get-campaigns
      parameters:
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PerPage'
      - name: delivery_type
        in: query
        required: false
        description: Filter results by gift type. `mail` returns physical item campaigns, `email` returns eGift campaigns.
        schema:
          type: string
          enum:
          - mail
          - email
      responses:
        '200':
          description: A page of campaigns.
          content:
            application/json:
              schema:
                type: object
                required:
                - current_page
                - per_page
                - total_posts
                - touches
                properties:
                  current_page:
                    type: integer
                  per_page:
                    type: integer
                  total_posts:
                    type: integer
                    description: The total number of campaigns.
                  touches:
                    type: array
                    items:
                      $ref: '#/components/schemas/Touch'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /api/v3/touches/{touch_id}:
    get:
      operationId: getCampaign
      summary: Get Campaign
      description: Retrieve additional details on a specific campaign.
      tags:
      - Campaigns
      externalDocs:
        url: https://developer.sendoso.com/rest-api/reference/campaigns/get-campaign
      parameters:
      - name: touch_id
        in: path
        required: true
        description: The campaign (touch) identifier.
        schema:
          type: integer
      responses:
        '200':
          description: The campaign.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Touch'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: 'Campaign not found. Documented message: "Touch not found".'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  responses:
    Unauthorized:
      description: 'Unauthorized. Documented message: "The access token is invalid".'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: Too Many Requests. Sendoso throttles application clients sending more than 10 requests/second; the client is temporarily blocked from making further requests.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      description: Sendoso's error envelope. Not RFC 9457 problem+json — errors are returned as `application/json` with a `success` flag and a human-readable `message`. Some documented 401 bodies use `description` and `expired` instead of `message`.
      properties:
        success:
          type: boolean
        message:
          type: string
        description:
          type: string
        expired:
          type: boolean
    Touch:
      type: object
      description: A campaign. Called a "touch" throughout the API.
      required:
      - id
      - name
      - start_date
      - description
      - created_at
      - user_id
      - gift_id
      - status
      - is_default_price
      - delivery_type
      properties:
        id:
          type: integer
        name:
          type: string
        start_date:
          type: string
          description: ISO 8601. Gifts cannot be sent for this campaign before this date.
        end_date:
          type: string
          description: ISO 8601. Gifts cannot be sent for this campaign after this date.
        description:
          type: string
        created_at:
          type: string
          description: ISO 8601.
        user_id:
          type: integer
          description: The identifier of the user that created this campaign.
        gift_id:
          type: integer
        starting_egift_price:
          type: number
          description: Lower bound of the eGift denomination range. eGift campaigns only.
        ending_egift_price:
          type: number
          description: Upper bound of the eGift denomination range. eGift campaigns only.
        status:
          type: string
          description: Always `Active` — this endpoint only returns active campaigns.
        is_default_price:
          type: boolean
        delivery_type:
          type: string
          enum:
          - mail
          - email
          description: '`mail` = physical item, `email` = eGift.'
  parameters:
    PerPage:
      name: per_page
      in: query
      required: false
      description: The number of results to be returned per page. Max is 100.
      schema:
        type: integer
        maximum: 100
    Page:
      name: page
      in: query
      required: false
      description: The page number of the results you want to retrieve. The first page is 1.
      schema:
        type: integer
        minimum: 1
  securitySchemes:
    OAuth2:
      type: oauth2
      description: 'OAuth 2.0 Authorization Code grant. Register your application by contacting developers@sendoso.com to receive a client ID and client secret. Access tokens live 7200 seconds (2 hours) and are refreshed at the same token endpoint. Tokens are sent as `Authorization: Bearer <token>`.'
      flows:
        authorizationCode:
          authorizationUrl: https://app.sendoso.com/oauth/authorize
          tokenUrl: https://app.sendoso.com/oauth/token
          refreshUrl: https://app.sendoso.com/oauth/token
          scopes:
            public: Access the user's basic information.
            write: Send gifts on the user's behalf.
            update: Update the user's account details.
            marketplace: Access the marketplace API.
            smartsend: Access the smartsend API.
externalDocs:
  description: Sendoso REST API documentation
  url: https://developer.sendoso.com/rest-api/overview/introduction