Customer.io Collections API

openapi: 3.1.0
info:
  title: Customer.io App Activities Collections API
  description: The Customer.io App API enables developers to manage workspace resources and send messages programmatically. It provides endpoints for sending transactional messages, triggering broadcasts, managing customers and segments, retrieving campaign and newsletter data, and exporting customer information. The API uses bearer token authentication with an App API key and is designed for operations that go beyond data ingestion, such as retrieving metrics, managing message templates, and automating outbound communications from Customer.io.
  version: 1.0.0
  contact:
    name: Customer.io Support
    url: https://customer.io/contact
  termsOfService: https://customer.io/legal/terms-of-service
servers:
- url: https://api.customer.io/v1
  description: US Production Server
- url: https://api-eu.customer.io/v1
  description: EU Production Server
security:
- bearerAuth: []
tags:
- name: Collections
  description: Manage collections of data used in message personalization.
paths:
  /api/collections:
    get:
      operationId: listCollections
      summary: List collections
      description: Returns a list of data collections in your workspace. Collections are used for personalizing messages with external data.
      tags:
      - Collections
      responses:
        '200':
          description: A list of collections.
          content:
            application/json:
              schema:
                type: object
                properties:
                  collections:
                    type: array
                    items:
                      $ref: '#/components/schemas/Collection'
        '401':
          description: Unauthorized. Invalid App API key.
    post:
      operationId: createCollection
      summary: Create a collection
      description: Creates a new data collection in your workspace.
      tags:
      - Collections
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCollectionRequest'
      responses:
        '200':
          description: Collection created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Collection'
        '400':
          description: Bad request. Invalid collection data.
        '401':
          description: Unauthorized. Invalid App API key.
  /api/collections/{collection_id}:
    get:
      operationId: getCollection
      summary: Get a collection
      description: Returns detailed information about a specific collection.
      tags:
      - Collections
      parameters:
      - $ref: '#/components/parameters/CollectionId'
      responses:
        '200':
          description: Collection details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Collection'
        '401':
          description: Unauthorized. Invalid App API key.
        '404':
          description: Collection not found.
    put:
      operationId: updateCollection
      summary: Update a collection
      description: Updates the contents or configuration of a data collection.
      tags:
      - Collections
      parameters:
      - $ref: '#/components/parameters/CollectionId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCollectionRequest'
      responses:
        '200':
          description: Collection updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Collection'
        '400':
          description: Bad request. Invalid collection data.
        '401':
          description: Unauthorized. Invalid App API key.
        '404':
          description: Collection not found.
    delete:
      operationId: deleteCollection
      summary: Delete a collection
      description: Deletes a data collection from your workspace.
      tags:
      - Collections
      parameters:
      - $ref: '#/components/parameters/CollectionId'
      responses:
        '200':
          description: Collection deleted successfully.
        '401':
          description: Unauthorized. Invalid App API key.
        '404':
          description: Collection not found.
components:
  parameters:
    CollectionId:
      name: collection_id
      in: path
      required: true
      description: The unique identifier for the collection.
      schema:
        type: integer
  schemas:
    CreateCollectionRequest:
      type: object
      required:
      - name
      - data
      description: A request to create or update a data collection.
      properties:
        name:
          type: string
          description: The collection name.
        data:
          type: array
          description: The collection data as an array of objects.
          items:
            type: object
        url:
          type: string
          format: uri
          description: A URL to fetch collection data from. Used for URL-backed collections.
    Collection:
      type: object
      description: A data collection used in message personalization.
      properties:
        id:
          type: integer
          description: The unique collection identifier.
        name:
          type: string
          description: The collection name.
        data_type:
          type: string
          description: The type of data in the collection.
        created_at:
          type: integer
          description: UNIX timestamp of when the collection was created.
        updated_at:
          type: integer
          description: UNIX timestamp of when the collection was last updated.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication using your App API key. Pass the key in the Authorization header as Bearer {app_api_key}.
externalDocs:
  description: App API Documentation
  url: https://docs.customer.io/integrations/api/app/