openapi: 3.1.0
info:
  title: Sendoso Sending Platform Inventory Recipients API
  description: Sendoso is a corporate gifting and direct mail platform that enables sales, marketing, and customer success teams to send physical and digital gifts at scale. The Sendoso API enables programmatic sending of gifts, swag, e-gifts, direct mail, and branded merchandise. Integrate gift-sending into CRM workflows, marketing automation, and customer engagement pipelines.
  version: '2.0'
  contact:
    name: Sendoso Developer Support
    url: https://developer.sendoso.com/
  license:
    name: Sendoso Terms of Service
    url: https://sendoso.com/terms-of-service/
servers:
- url: https://app.sendoso.com/api/v2
  description: Sendoso Production API v2
security:
- ApiKeyAuth: []
tags:
- name: Recipients
  description: Manage recipient contacts
paths:
  /recipients:
    get:
      operationId: listRecipients
      summary: List Recipients
      description: Returns a paginated list of recipient contacts.
      tags:
      - Recipients
      parameters:
      - name: page
        in: query
        schema:
          type: integer
          default: 1
      - name: per_page
        in: query
        schema:
          type: integer
          default: 25
      - name: search
        in: query
        schema:
          type: string
        description: Search by name or email
      responses:
        '200':
          description: List of recipients
          content:
            application/json:
              schema:
                type: object
                properties:
                  recipients:
                    type: array
                    items:
                      $ref: '#/components/schemas/Recipient'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
    post:
      operationId: createRecipient
      summary: Create Recipient
      description: Creates a new recipient contact in the Sendoso address book.
      tags:
      - Recipients
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecipientCreate'
      responses:
        '201':
          description: Recipient created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Recipient'
        '422':
          description: Validation error
  /recipients/{recipient_id}:
    get:
      operationId: retrieveRecipient
      summary: Retrieve Recipient
      description: Returns details for a specific recipient contact.
      tags:
      - Recipients
      parameters:
      - $ref: '#/components/parameters/RecipientId'
      responses:
        '200':
          description: Recipient details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Recipient'
        '404':
          description: Recipient not found
components:
  parameters:
    RecipientId:
      name: recipient_id
      in: path
      required: true
      schema:
        type: string
      description: Unique recipient identifier
  schemas:
    Address:
      type: object
      properties:
        street1:
          type: string
        street2:
          type: string
        city:
          type: string
        state:
          type: string
          description: State or province code
        postal_code:
          type: string
        country:
          type: string
          description: ISO 3166-1 alpha-2 country code
          default: US
    Recipient:
      type: object
      properties:
        id:
          type: string
        first_name:
          type: string
        last_name:
          type: string
        email:
          type: string
          format: email
        company:
          type: string
        title:
          type: string
        address:
          $ref: '#/components/schemas/Address'
        created_at:
          type: string
          format: date-time
    Pagination:
      type: object
      properties:
        page:
          type: integer
        per_page:
          type: integer
        total:
          type: integer
        total_pages:
          type: integer
    RecipientCreate:
      type: object
      required:
      - first_name
      - last_name
      - email
      properties:
        first_name:
          type: string
        last_name:
          type: string
        email:
          type: string
          format: email
        company:
          type: string
        title:
          type: string
        address:
          $ref: '#/components/schemas/Address'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
      description: Sendoso API key from Settings > API Keys