Klaviyo Custom Objects API

openapi: 3.0.2
info:
  title: Klaviyo Accounts Custom Objects API
  version: '2026-04-15'
  description: The Klaviyo REST API. Please visit https://developers.klaviyo.com for more details.
  contact:
    name: Klaviyo Developer Experience Team
    email: developers@klaviyo.com
    url: https://developers.klaviyo.com
  termsOfService: https://www.klaviyo.com/legal/api-terms
  license:
    name: License
    url: https://www.klaviyo.com/legal
servers:
- url: https://a.klaviyo.com
  description: Production
security:
- Klaviyo-API-Key: []
tags:
- name: Custom Objects
  description: custom objects
paths:
  /api/data-sources:
    get:
      operationId: get_data_sources
      summary: Get Data Sources
      description: 'Get all data sources in an account.<br><br>*Rate limits*:<br>Burst: `3/s`<br>Steady: `60/m`


        **Scopes:**

        `custom-objects:read`'
      parameters:
      - name: fields[data-source]
        in: query
        description: For more information please visit https://developers.klaviyo.com/en/v2026-04-15/reference/api-overview#sparse-fieldsets
        required: false
        schema:
          type: array
          items:
            type: string
            enum:
            - description
            - namespace
            - title
            - visibility
        explode: false
      - name: page[cursor]
        in: query
        description: For more information please visit https://developers.klaviyo.com/en/v2026-04-15/reference/api-overview#pagination
        required: false
        schema:
          type: string
      - name: page[size]
        in: query
        description: 'Default: 20. Min: 1. Max: 100.'
        required: false
        schema:
          type: integer
          default: 20
          maximum: 100
          minimum: 1
      - name: revision
        in: header
        description: 'API endpoint revision (format: YYYY-MM-DD[.suffix])'
        required: true
        schema:
          type: string
          default: '2026-04-15'
      responses:
        '200':
          description: Success
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/GetDataSourceResponseCollection'
        4XX:
          $ref: '#/components/responses/ClientError'
        5XX:
          $ref: '#/components/responses/ServerError'
      tags:
      - Custom Objects
      x-klaviyo-pre-release: None
      x-klaviyo-ratelimit:
        burst: 3/s
        steady: 60/m
      x-klaviyo-scopes:
      - custom-objects:read
    post:
      operationId: create_data_source
      summary: Create Data Source
      description: 'Create a new data source in an account<br><br>*Rate limits*:<br>Burst: `3/s`<br>Steady: `60/m`


        **Scopes:**

        `custom-objects:write`'
      parameters:
      - name: revision
        in: header
        description: 'API endpoint revision (format: YYYY-MM-DD[.suffix])'
        required: true
        schema:
          type: string
          default: '2026-04-15'
      requestBody:
        description: Create data source
        required: true
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/DataSourceCreateQuery'
      responses:
        '201':
          description: Success
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/PostDataSourceResponse'
        4XX:
          $ref: '#/components/responses/ClientError'
        5XX:
          $ref: '#/components/responses/ServerError'
      tags:
      - Custom Objects
      x-klaviyo-pre-release: None
      x-klaviyo-ratelimit:
        burst: 3/s
        steady: 60/m
      x-klaviyo-scopes:
      - custom-objects:write
  /api/data-sources/{id}:
    get:
      operationId: get_data_source
      summary: Get Data Source
      description: 'Retrieve a data source in an account.<br><br>*Rate limits*:<br>Burst: `3/s`<br>Steady: `60/m`


        **Scopes:**

        `custom-objects:read`'
      parameters:
      - name: id
        in: path
        description: The ID of the data source
        required: true
        schema:
          description: The ID of the data source
          type: string
      - name: fields[data-source]
        in: query
        description: For more information please visit https://developers.klaviyo.com/en/v2026-04-15/reference/api-overview#sparse-fieldsets
        required: false
        schema:
          type: array
          items:
            type: string
            enum:
            - description
            - namespace
            - title
            - visibility
        explode: false
      - name: revision
        in: header
        description: 'API endpoint revision (format: YYYY-MM-DD[.suffix])'
        required: true
        schema:
          type: string
          default: '2026-04-15'
      responses:
        '200':
          description: Success
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/GetDataSourceResponse'
        4XX:
          $ref: '#/components/responses/ClientError'
        5XX:
          $ref: '#/components/responses/ServerError'
      tags:
      - Custom Objects
      x-klaviyo-pre-release: None
      x-klaviyo-ratelimit:
        burst: 3/s
        steady: 60/m
      x-klaviyo-scopes:
      - custom-objects:read
    delete:
      operationId: delete_data_source
      summary: Delete Data Source
      description: 'Delete a data source in an account.<br><br>*Rate limits*:<br>Burst: `3/s`<br>Steady: `60/m`


        **Scopes:**

        `custom-objects:write`'
      parameters:
      - name: id
        in: path
        description: The ID of the data source to delete
        required: true
        schema:
          description: The ID of the data source to delete
          type: string
      - name: revision
        in: header
        description: 'API endpoint revision (format: YYYY-MM-DD[.suffix])'
        required: true
        schema:
          type: string
          default: '2026-04-15'
      responses:
        '204':
          description: Success
        4XX:
          $ref: '#/components/responses/ClientError'
        5XX:
          $ref: '#/components/responses/ServerError'
      tags:
      - Custom Objects
      x-klaviyo-pre-release: None
      x-klaviyo-ratelimit:
        burst: 3/s
        steady: 60/m
      x-klaviyo-scopes:
      - custom-objects:write
  /api/data-source-record-bulk-create-jobs:
    post:
      operationId: bulk_create_data_source_records
      summary: Bulk Create Data Source Records
      description: 'Create a bulk data source record import job to create a batch of records.


        Accepts up to 500 records per request. The maximum allowed payload size is 4MB. The maximum allowed payload size per-record is 512KB.


        To learn more, see our [Custom Objects API overview](https://developers.klaviyo.com/en/reference/custom_objects_api_overview).<br><br>*Rate limits*:<br>Burst: `3/s`<br>Steady: `15/m`


        **Scopes:**

        `custom-objects:write`'
      parameters:
      - name: revision
        in: header
        description: 'API endpoint revision (format: YYYY-MM-DD[.suffix])'
        required: true
        schema:
          type: string
          default: '2026-04-15'
      requestBody:
        description: Create a data source record job
        required: true
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/DataSourceRecordBulkCreateJobCreateQuery'
      responses:
        '204':
          description: Success
        4XX:
          $ref: '#/components/responses/ClientError'
        5XX:
          $ref: '#/components/responses/ServerError'
      tags:
      - Custom Objects
      x-klaviyo-operation-aliases:
      - create_data_source_record_bulk_create_job
      x-klaviyo-pre-release: None
      x-klaviyo-ratelimit:
        burst: 3/s
        steady: 15/m
      x-klaviyo-scopes:
      - custom-objects:write
  /api/data-source-record-create-jobs:
    post:
      operationId: create_data_source_record
      summary: Create Data Source Record
      description: 'Create a data source record import job to create a single record.


        The maximum allowed payload size per-record is 512KB.


        To learn more, see our [Custom Objects API overview](https://developers.klaviyo.com/en/reference/custom_objects_api_overview).<br><br>*Rate limits*:<br>Burst: `75/s`<br>Steady: `750/m`


        **Scopes:**

        `custom-objects:write`'
      parameters:
      - name: revision
        in: header
        description: 'API endpoint revision (format: YYYY-MM-DD[.suffix])'
        required: true
        schema:
          type: string
          default: '2026-04-15'
      requestBody:
        description: Create a data source record job
        required: true
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/DataSourceRecordCreateJobCreateQuery'
      responses:
        '204':
          description: Success
        4XX:
          $ref: '#/components/responses/ClientError'
        5XX:
          $ref: '#/components/responses/ServerError'
      tags:
      - Custom Objects
      x-klaviyo-operation-aliases:
      - create_data_source_record_create_job
      x-klaviyo-pre-release: None
      x-klaviyo-ratelimit:
        burst: 75/s
        steady: 750/m
      x-klaviyo-scopes:
      - custom-objects:write
components:
  schemas:
    DataSourceRecordCreateJobCreateQuery:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/DataSourceRecordCreateJobCreateQueryResourceObject'
      required:
      - data
    DataSourceRecordBulkCreateJobCreateQueryResourceObject:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/DataSourceRecordBulkCreateJobEnum'
        attributes:
          type: object
          properties:
            data-source-records:
              description: The records to ingest.
              type: object
              example:
                data:
                - type: data-source-record
                  attributes:
                    record:
                      key1: value1
                      key2: value2
              nullable: true
              properties:
                data:
                  type: array
                  items:
                    $ref: '#/components/schemas/DataSourceRecordResourceObject'
              required:
              - data
        relationships:
          type: object
          properties:
            data-source:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    type:
                      $ref: '#/components/schemas/DataSourceEnum'
                    id:
                      description: The data source to which the records belong.
                      type: string
                      example: 01J7C23V8XWMRG13FMD7VZN6GW
                  required:
                  - type
                  - id
      required:
      - type
      - attributes
    DataSourceRecordBulkCreateJobCreateQuery:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/DataSourceRecordBulkCreateJobCreateQueryResourceObject'
      required:
      - data
    GetDataSourceResponseCollection:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/DataSourceResponseObjectResource'
        links:
          $ref: '#/components/schemas/CollectionLinks'
      required:
      - data
    DataSourceCreateQuery:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/DataSourceCreateQueryResourceObject'
      required:
      - data
    DataSourceRecordCreateJobEnum:
      type: string
      enum:
      - data-source-record-create-job
    DataSourceRecordCreateJobCreateQueryResourceObject:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/DataSourceRecordCreateJobEnum'
        attributes:
          type: object
          properties:
            data-source-record:
              description: The records to ingest.
              type: object
              example:
                data:
                  type: data-source-record
                  attributes:
                    record:
                      key1: value1
                      key2: value2
              properties:
                data:
                  $ref: '#/components/schemas/DataSourceRecordResourceObject'
              required:
              - data
          required:
          - data-source-record
        relationships:
          type: object
          properties:
            data-source:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    type:
                      $ref: '#/components/schemas/DataSourceEnum'
                    id:
                      description: The data source to which the records belong.
                      type: string
                      example: 01J7C23V8XWMRG13FMD7VZN6GW
                  required:
                  - type
                  - id
      required:
      - type
      - attributes
    DataSourceEnum:
      type: string
      enum:
      - data-source
    DataSourceResponseObjectResource:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/DataSourceEnum'
        id:
          description: The ID of the data source
          type: string
          example: 01KH1D6P9Y8TJ7Q6MHXWZMPDN3
        attributes:
          type: object
          properties:
            title:
              description: The title of the data source
              type: string
              example: My Data Source
            visibility:
              description: The status of the data source
              type: string
              enum:
              - private
              - shared
            description:
              description: The description of the data source
              type: string
              example: This is a data source
            namespace:
              description: The namespace of the data source
              type: string
              example: custom-objects
          required:
          - title
          - visibility
          - description
          - namespace
        links:
          $ref: '#/components/schemas/ObjectLinks'
      required:
      - type
      - id
      - attributes
      - links
    DataSourceCreateQueryResourceObject:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/DataSourceEnum'
        attributes:
          type: object
          properties:
            title:
              description: The title of the data source. Must be between 1 and 255 characters and unique within the namespace.
              type: string
            visibility:
              description: Visibility of data source.
              type: string
              example: private
              default: private
              enum:
              - private
              - shared
              nullable: true
            description:
              type: string
              default: ''
              nullable: true
            namespace:
              description: The namespace of the data source.
              type: string
              example: custom-objects
              default: custom-objects
              nullable: true
          required:
          - title
      required:
      - type
      - attributes
    DataSourceRecordBulkCreateJobEnum:
      type: string
      enum:
      - data-source-record-bulk-create-job
    DataSourceRecordEnum:
      type: string
      enum:
      - data-source-record
    PostDataSourceResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            type:
              $ref: '#/components/schemas/DataSourceEnum'
            id:
              description: The ID of the data source
              type: string
              example: 01KH1D6P9Y8TJ7Q6MHXWZMPDN3
            attributes:
              type: object
              properties:
                title:
                  description: The title of the data source
                  type: string
                  example: My Data Source
                visibility:
                  description: The status of the data source
                  type: string
                  enum:
                  - private
                  - shared
                description:
                  description: The description of the data source
                  type: string
                  example: This is a data source
                namespace:
                  description: The namespace of the data source
                  type: string
                  example: custom-objects
              required:
              - title
              - visibility
              - description
              - namespace
            links:
              $ref: '#/components/schemas/ObjectLinks'
          required:
          - type
          - id
          - attributes
          - links
        links:
          $ref: '#/components/schemas/ObjectLinks'
      required:
      - data
    DataSourceRecordResourceObject:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/DataSourceRecordEnum'
        attributes:
          type: object
          properties:
            record:
              type: object
          required:
          - record
      required:
      - type
      - attributes
    GetDataSourceResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/DataSourceResponseObjectResource'
        links:
          $ref: '#/components/schemas/ObjectLinks'
      required:
      - data
    ObjectLinks:
      type: object
      properties:
        self:
          type: string
          format: uri
      required:
      - self
    CollectionLinks:
      type: object
      properties:
        self:
          type: string
          format: uri
        first:
          type: string
          format: uri
        last:
          type: string
          format: uri
        prev:
          type: string
          format: uri
        next:
          type: string
          format: uri
      required:
      - self
  responses:
    ClientError:
      description: Client Error
      content:
        application/vnd.api+json:
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  type: object
                  required:
                  - id
                  - code
                  - title
                  - detail
                  properties:
                    id:
                      type: string
                    code:
                      type: string
                    title:
                      type: string
                    detail:
                      type: string
                    source:
                      type: object
                      properties:
                        pointer:
                          type: string
                        parameter:
                          type: string
            required:
            - errors
    ServerError:
      description: Server Error
      content:
        application/vnd.api+json:
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  type: object
                  required:
                  - id
                  - code
                  - title
                  - detail
                  properties:
                    id:
                      type: string
                    code:
                      type: string
                    title:
                      type: string
                    detail:
                      type: string
                    source:
                      type: object
                      properties:
                        pointer:
                          type: string
                        parameter:
                          type: string
            required:
            - errors
  securitySchemes:
    Klaviyo-API-Key:
      type: apiKey
      in: header
      name: Authorization
      description: Private key authentication for /api/ endpoints is performed by setting the `Authorization` header to `Klaviyo-API-Key your-private-api-key`<br>For more information please visit https://developers.klaviyo.com/en/v2026-04-15/reference/api-overview#authentication
      x-default: Klaviyo-API-Key your-private-api-key
x-readme:
  explorer-enabled: false
  proxy-enabled: true
  samples-enabled: true