Act-On Custom Objects Service

openapi: 3.1.0
info:
  title: Custom Objects Service
  description: API to manage and import custom objects
  version: 3.4.3
servers:
- url: https://api.actonsoftware.com/custom-objects
  description: Generated server url
security:
- bearerAuth: []
tags:
- name: Custom Data Dataset API
  description: Custom Data Dataset API
- name: Custom Data Schema API
  description: Custom Data Schema API
- name: Custom Data Query API
  description: Custom Data Query API
paths:
  /v1/{accountId}/schema/{objectId}:
    get:
      tags:
      - Custom Data Schema API
      summary: Returns a Custom Data schema
      description: Get a Custom Data schema
      operationId: getSchema
      parameters:
      - name: accountId
        in: path
        description: The Act-On account Id for this request
        required: true
        schema:
          type: string
      - name: objectId
        in: path
        description: The Custom Data Schema Id for this request
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Retrieved.
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Received a bad request.
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
        '401':
          description: Unauthorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
        '404':
          description: Object schema not found.
          content:
            application/json:
              schema:
                type: object
        '415':
          description: Unsupported Media Type.
          content:
            application/json:
              schema:
                type: object
        '500':
          description: Internal Server Error.
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
    put:
      tags:
      - Custom Data Schema API
      summary: Updates a Custom Data schema basic properties
      description: Updates a Custom Data schema basic properties
      operationId: updateSchema
      parameters:
      - name: accountId
        in: path
        description: The Act-On account Id for this request
        required: true
        schema:
          type: string
      - name: objectId
        in: path
        description: The Custom Data schema Id for this request
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSchemaRequestDTO'
        required: true
      responses:
        '200':
          description: Schema updated successfully
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Bad request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
        '401':
          description: Unauthorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
        '404':
          description: Schema not found
          content:
            application/json:
              schema:
                type: object
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
    delete:
      tags:
      - Custom Data Schema API
      summary: Deletes one Custom Data schema
      description: Deletes one Custom Data schema
      operationId: deleteSchema
      parameters:
      - name: accountId
        in: path
        description: The Act-On account Id for this request
        required: true
        schema:
          type: string
      - name: objectId
        in: path
        description: The Custom Data schema Id to delete
        required: true
        schema:
          type: string
      - name: hard
        in: query
        description: Whether to perform a hard delete
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: Retrieved.
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Received a bad request.
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
        '401':
          description: Unauthorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
        '404':
          description: Object Schema not found.
          content:
            application/json:
              schema:
                type: object
        '415':
          description: Unsupported Media Type.
          content:
            application/json:
              schema:
                type: object
        '500':
          description: Internal Server Error.
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
  /v1/{accountId}/schema/{objectId}/field:
    put:
      tags:
      - Custom Data Schema API
      summary: Updates Custom Data schema field properties
      description: Updates a Custom Data schema fields basic properties
      operationId: updateFields
      parameters:
      - name: accountId
        in: path
        description: The Act-On account Id for this request
        required: true
        schema:
          type: string
      - name: objectId
        in: path
        description: The Custom Data schema Id for this request
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: array
              description: The field definitions with updated properties
              items:
                $ref: '#/components/schemas/FieldDefinitionDTO'
        required: true
      responses:
        '200':
          description: Fields updated successfully
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Bad request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
        '401':
          description: Unauthorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
        '404':
          description: Schema or fields not found
          content:
            application/json:
              schema:
                type: object
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
    post:
      tags:
      - Custom Data Schema API
      summary: Adds fields to Custom Data schemas
      description: Adds fields to Custom Data schemas
      operationId: addFields
      parameters:
      - name: accountId
        in: path
        description: The Act-On account Id for this request
        required: true
        schema:
          type: string
      - name: objectId
        in: path
        description: The Custom Data schema Id for this request
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: array
              description: The fields to add
              items:
                $ref: '#/components/schemas/FieldDefinitionDTO'
        required: true
      responses:
        '200':
          description: Fields added successfully
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Received a bad request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
        '401':
          description: Unauthorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
        '404':
          description: Schema not found
          content:
            application/json:
              schema:
                type: object
        '415':
          description: Unsupported Media Type
          content:
            application/json:
              schema:
                type: object
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
    delete:
      tags:
      - Custom Data Schema API
      summary: Deletes fields from Custom Data schemas
      description: Deletes fields from Custom Data schemas
      operationId: deleteFields
      parameters:
      - name: accountId
        in: path
        description: The Act-On account Id for this request
        required: true
        schema:
          type: string
      - name: objectId
        in: path
        description: The Custom Data schema Id for this request
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: array
              description: The field names to delete
              items:
                type: string
        required: true
      responses:
        '200':
          description: Fields deleted successfully
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Received a bad request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
        '401':
          description: Unauthorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
        '404':
          description: Schema or fields not found
          content:
            application/json:
              schema:
                type: object
        '415':
          description: Unsupported Media Type
          content:
            application/json:
              schema:
                type: object
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
  /v1/{accountId}/schema:
    post:
      tags:
      - Custom Data Schema API
      summary: Create a Custom Data schema
      description: Create a Custom Data schema
      operationId: createSchema
      parameters:
      - name: accountId
        in: path
        description: The Act-On account Id for this request
        required: true
        schema:
          type: string
      - name: dryRun
        in: query
        description: When true, validates the request without creating the schema
        required: false
        schema:
          type: boolean
          default: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSchemaRequestDTO'
        required: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Bad request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
        '401':
          description: Unauthorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
        '409':
          description: Schema already exists
          content:
            application/json:
              schema:
                type: object
        '415':
          description: Unsupported Media Type
          content:
            application/json:
              schema:
                type: object
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
  /v1/{accountId}/query/{objectId}/{datasetId}/joinWithOther:
    post:
      tags:
      - Custom Data Query API
      summary: Query data from a Custom Data dataset
      description: Performs a query on Custom Data dataset with a simple join with Account Object Context
      operationId: queryData
      parameters:
      - name: accountId
        in: path
        description: Account ID
        required: true
        schema:
          type: string
      - name: objectId
        in: path
        description: The Custom Data Schema Id for this request
        required: true
        schema:
          type: string
      - name: datasetId
        in: path
        description: The Custom Data Dataset Id for this request
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataQueryRequestDTO'
        required: true
      responses:
        '200':
          description: Query executed successfully
          content:
            application/json:
              schema:
                type: object
            text/plain:
              schema:
                type: object
        '400':
          description: Bad request - invalid query parameters
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
        '401':
          description: Unauthorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
            text/plain:
              schema:
                type: object
        '404':
          description: Dataset or object not found
          content:
            application/json:
              schema:
                type: object
            text/plain:
              schema:
                type: object
        '500':
          description: Internal server error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
  /v1/{accountId}/query/{objectId}/{datasetId}/joinWithOtherInternal:
    post:
      tags:
      - Custom Data Query API
      summary: Internal query data from a custom object dataset
      description: Performs an internal query on custom object data with a simple join with Account Object
        Context
      operationId: internalQueryData
      parameters:
      - name: accountId
        in: path
        description: Account ID
        required: true
        schema:
          type: string
      - name: objectId
        in: path
        description: The Custom Object Schema Id for this request
        required: true
        schema:
          type: string
      - name: datasetId
        in: path
        description: The Custom Object Dataset Id for this request
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataQueryRequestDTO'
        required: true
      responses:
        '200':
          description: Query executed successfully
          content:
            application/json:
              schema:
                type: object
            text/plain:
              schema:
                type: object
        '400':
          description: Bad request - invalid query parameters
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
        '401':
          description: Unauthorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
            text/plain:
              schema:
                type: object
        '404':
          description: Dataset or object not found
          content:
            application/json:
              schema:
                type: object
            text/plain:
              schema:
                type: object
        '500':
          description: Internal server error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
  /v1/{accountId}/query/joinWithOtherPreflight:
    post:
      tags:
      - Custom Data Query API
      summary: Cache hydration preflight for query performance
      description: Performs cache hydration to optimize subsequent query performance
      operationId: cacheHydrationPreflight
      parameters:
      - name: accountId
        in: path
        description: Account ID
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Cache hydration completed successfully
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Bad Request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
        '401':
          description: Unauthorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
        '500':
          description: Internal server error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
  /v1/{accountId}/data/{objectId}:
    post:
      tags:
      - Custom Data Dataset API
      summary: Creates a new dataset for a Custom Data schema
      description: Creates an empty dataset for a specific Custom Data schema
      operationId: createDataset
      parameters:
      - name: accountId
        in: path
        description: The Act-On account Id for this request
        required: true
        schema:
          type: string
      - name: objectId
        in: path
        description: The schema ID for this request
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDatasetRequestDTO'
        required: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Bad request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
        '401':
          description: Unauthorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
        '500':
          description: Internal Server Error.
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
  /v1/{accountId}/data/{objectId}/{identifier}:
    get:
      tags:
      - Custom Data Dataset API
      summary: Retrieves the details for a dataset using its ID or name
      description: Returns detailed information about a dataset
      operationId: describeDataset
      parameters:
      - name: accountId
        in: path
        description: The Act-On account Id
        required: true
        schema:
          type: string
      - name: objectId
        in: path
        description: The Custom Object Id
        required: true
        schema:
          type: string
      - name: identifier
        in: path
        description: The dataset ID or name
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Dataset details retrieved successfully
          content:
            '*/*':
              schema:
                type: object
        '400':
          description: Bad request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
        '401':
          description: Unauthorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
        '403':
          description: Forbidden
          content:
            '*/*':
              schema:
                type: object
        '404':
          description: Dataset not found
          content:
            '*/*':
              schema:
                type: object
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
    post:
      tags:
      - Custom Data Dataset API
      summary: Updates a dataset's name and description
      description: Modifies metadata for an existing dataset
      operationId: updateDataset
      parameters:
      - name: accountId
        in: path
        description: The Act-On account Id
        required: true
        schema:
          type: string
      - name: objectId
        in: path
        description: The Custom Object Id
        required: true
        schema:
          type: string
      - name: identifier
        in: path
        description: The dataset ID or name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateDatasetRequestDTO'
        required: true
      responses:
        '200':
          description: Dataset successfully updated
          content:
            '*/*':
              schema:
                type: object
        '400':
          description: Bad request - invalid name format
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
        '401':
          description: Unauthorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
        '403':
          description: Forbidden
          content:
            '*/*':
              schema:
                type: object
        '404':
          description: Dataset not found
          content:
            '*/*':
              schema:
                type: object
        '409':
          description: Dataset name already exists
          content:
            '*/*':
              schema:
                type: object
        '500':
          description: Internal Server Error
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
    delete:
      tags:
      - Custom Data Dataset API
      summary: Deletes the dataset based on the provided dataset Id
      description: Permanently removes a dataset and all its data
      operationId: deleteDataset
      parameters:
      - name: accountId
        in: path
        description: The Act-On account Id for the deletion request
        required: true
        schema:
          type: string
      - name: objectId
        in: path
        description: The Custom Object Id for the deletion request
        required: true
        schema:
          type: string
      - name: identifier
        in: path
        description: The custom object dataset Id or dataset name for the deletion request
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            '*/*':
              schema:
                type: object
        '400':
          description: Bad request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
        '401':
          description: Unauthorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
        '403':
          description: Forbidden
          content:
            '*/*':
              schema:
                type: object
        '500':
          description: Internal Server Error.
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
  /v1/{accountId}/data/{objectId}/{identifier}/json:
    post:
      tags:
      - Custom Data Dataset API
      summary: Ingests a JSON stream for a specific dataset or object
      description: Processes a JSON data stream for the specified dataset
      operationId: ingestJsonStream
      parameters:
      - name: accountId
        in: path
        description: The Act-On account Id for this request
        required: true
        schema:
          type: string
      - name: objectId
        in: path
        description: The Custom ObjectId for this request
        required: true
        schema:
          type: string
      - name: identifier
        in: path
        description: The dataset ID or name
        required: true
        schema:
          type: string
      - name: ingestMode
        in: query
        description: The ingest mode (upsert, replace, or delete)
        required: true
        schema:
          type: string
      - name: abortOnInvalidRow
        in: query
        description: Whether to abort processing on invalid data
        required: true
        schema:
          type: boolean
      - name: description
        in: query
        description: Optional description for the dataset
        required: false
        schema:
          type: string
      - name: createNewDataset
        in: query
        description: Whether to create a new dataset
        required: false
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Bad request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
        '401':
          description: Unauthorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
        '409':
          description: JSON Validation failed
          content:
            application/json:
              schema:
                type: object
        '415':
          description: Unsupported Media Type.
          content:
            application/json:
              schema:
                type: object
        '500':
          description: Internal Server Error.
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
  /v1/{accountId}/data/{objectId}/{identifier}/file:
    post:
      tags:
      - Custom Data Dataset API
      summary: Ingests a CSV or JSON file for a specific dataset or object
      description: Uploads and processes a data file for the specified dataset
      operationId: ingestFile
      parameters:
      - name: accountId
        in: path
        description: The Act-On account Id for this request
        required: true
        schema:
          type: string
      - name: objectId
        in: path
        description: The Custom ObjectId for this request
        required: true
        schema:
          type: string
      - name: identifier
        in: path
        description: The dataset ID or name
        required: true
        schema:
          type: string
      - name: ingestMode
        in: query
        description: The ingest mode (UPSERT, REPLACE, or DELETE)
        required: false
        schema:
          type: string
          default: UPSERT
          enum:
          - UPSERT
          - REPLACE
          - DELETE
          - DELETE_DATASET
      - name: createNewDataset
        in: query
        description: Whether to create a new dataset
        required: false
        schema:
          type: boolean
          default: false
      - name: abortOnInvalidRow
        in: query
        description: Whether to abort on invalid row
        required: false
        schema:
          type: boolean
          default: false
      - name: description
        in: query
        description: Dataset description
        required: false
        schema:
          type: string
      - name: fileType
        in: query
        description: File type (csv or json)
        required: false
        schema:
          type: string
          default: csv
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
              required:
              - file
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Bad request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
        '401':
          description: Unauthorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
        '409':
          description: CSV Validation failed
          content:
            application/json:
              schema:
                type: object
        '415':
          description: Unsupported Media Type.
          content:
            application/json:
              schema:
                type: object
        '500':
          description: Internal Server Error.
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
  /v1/{accountId}/data/{objectId}/validate:
    post:
      tags:
      - Custom Data Dataset API
      summary: Validates a file against a schema without ingesting data
      description: Checks if a file is valid for the specified schema
      operationId: validateFile
      parameters:
      - name: accountId
        in: path
        description: The Act-On account Id for this request
        required: true
        schema:
          type: string
      - name: objectId
        in: path
        description: The schema Id for this request
        required: true
        schema:
          type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ValidationRequestDTO'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Bad request
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
        '401':
          description: Unauthorized
          content:
            '*/*':
              schema:
                $ref: '#/components/schemas/HttpErrorResponse'
        '403':
          description: Forbidden
          cont

# --- truncated at 32 KB (56 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/act-on/refs/heads/main/openapi/act-on-custom-objects-service-openapi.yml