Sendoso Campaigns API

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.
  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:
    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.'
    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
  parameters:
    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
    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
  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