> ## Documentation Index
> Fetch the complete documentation index at: https://docs.occtoo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Verify an ingest payload

> Runs the same caller-access, payload, key, property and configured-size validation as ingest without enqueuing entries.

Verification applies payload-size ceilings but does not consume the tenant request-rate budget. A successful verification does not reserve capacity or guarantee that a later ingest will be accepted.



## OpenAPI

````yaml /api-reference/openapi/ingest.json post /datasources/{dataSource}/import/verify
openapi: 3.1.1
info:
  title: Occtoo Ingest API
  description: >-
    Submit source entries to the authenticated Occtoo tenant. Tenant identity
    always comes from the credential; it is never accepted from the route or
    request body.


    ## Authentication and access


    Select **Authorize** to reuse the existing Occtoo browser session, provide a
    tenant-scoped bearer token, or send an organization API key through
    `x-api-key`. The legacy import operations accept either the established
    `import-datasource` permission or the tenant-application `write:sources`
    scope. `POST /sources/<sourceId>` accepts only `write:sources`.


    Kinde application scopes are projected unchanged by the gateway.
    `AuthorizeAny` gives applications, users, and organization API keys one
    endpoint policy while preserving the established provider permission. Tenant
    applications use `write:sources` as the capability and Occtoo-owned resource
    grants to allow every source or selected sources. Legacy data-provider
    applications remain restricted to their assigned sources.


    The credential-exchange endpoint is an anonymous convenience for server-side
    data-provider integrations. It accepts a provider id and secret in the
    request body and is not an OAuth client-credentials endpoint.


    ## Payload rules


    - Entry keys must be unique within a request, compared case-insensitively.

    - Property ids are canonicalized to lowercase at rest.

    - A property id may repeat only when its language differs.

    - Reserved system properties are rejected.

    - Request, entry and property-value ceilings are tenant-configured and
    returned in validation errors when exceeded.


    `POST /sources/<sourceId>` accepts native JSON strings, numbers, booleans,
    nulls, and string arrays. Configured properties require the matching JSON
    shape. Missing or untyped properties are inferred from their JSON values;
    string arrays use the configured delimiter or `,` when none is set. Values
    are serialized to strings before they enter the existing asynchronous ingest
    pipeline.


    `POST /datasources/<dataSource>/import/verify` runs validation without
    queueing or consuming the request-rate budget. `POST
    /datasources/<dataSource>/import` returns `202` when accepted for
    asynchronous processing.


    Retry `429` and transient `5xx` responses with bounded exponential backoff.
    Do not retry a successful `202` merely because downstream processing has not
    completed.


    Machine-readable contract:
    [OpenAPI](https://api.occtoo.com/openapi/ingest.json)
  version: 1.0.0
  summary: Validate and ingest tenant-scoped source entries.
servers:
  - url: https://api.occtoo.com
    description: Occtoo public API
security: []
tags:
  - name: Ingest
    description: Verify source-entry payloads and submit them for asynchronous processing.
  - name: Sources
    description: Submit strongly typed JSON source entries.
  - name: Authentication
    description: Exchange registered data-provider credentials for an Occtoo bearer token.
paths:
  /datasources/{dataSource}/import/verify:
    post:
      tags:
        - Ingest
      summary: Verify an ingest payload
      description: >-
        Runs the same caller-access, payload, key, property and configured-size
        validation as ingest without enqueuing entries.


        Verification applies payload-size ceilings but does not consume the
        tenant request-rate budget. A successful verification does not reserve
        capacity or guarantee that a later ingest will be accepted.
      operationId: verifyIngestPayload
      parameters:
        - name: dataSource
          in: path
          description: Stable customer-facing source id within the authenticated tenant.
          required: true
          schema:
            minLength: 1
            type: string
            example: products
          example: products
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IngestRequest'
            examples:
              example:
                summary: Upsert and delete entries
                value:
                  entities:
                    - key: sku-123
                      delete: false
                      properties:
                        - id: name
                          value: Blue chair
                          language: en
                        - id: inStock
                          value: 'true'
                          type: Boolean
                        - id: tags
                          value: summer|sale
                          delimiter: '|'
                          type: List
                    - key: sku-obsolete
                      delete: true
                      properties: []
        required: true
      responses:
        '200':
          description: The payload and caller access are valid. Nothing was queued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
              examples:
                example:
                  value:
                    errors: []
                    requestId: 01JZP4FQ2Y7JYV5Y2R8B4X9Q3W
        '400':
          description: >-
            Malformed payload, invalid or duplicate keys/properties/languages,
            reserved properties, or a configured size ceiling was exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '401':
          description: Authentication is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '403':
          description: >-
            The caller has neither `import-datasource` nor `write:sources`, the
            tenant application is not granted this source, or a legacy
            data-provider application is inactive or not assigned to this
            source.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '404':
          description: The requested data source cannot be resolved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '409':
          description: The data source is being purged or is in another conflicting state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '429':
          description: >-
            The tenant request-rate budget is exhausted. Retry after the
            indicated delay using bounded exponential backoff.
          headers:
            Retry-After:
              description: Optional number of seconds to wait before retrying.
              schema:
                minimum: 1
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
        '500':
          description: >-
            The ingest operation failed unexpectedly. Retry transient failures
            with bounded exponential backoff.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
      security:
        - kindeOAuth: []
        - bearerAuth: []
        - apiKey: []
components:
  schemas:
    IngestRequest:
      required:
        - entities
      type: object
      properties:
        entities:
          minItems: 1
          type: array
          items:
            $ref: '#/components/schemas/IngestEntity'
          description: >-
            Non-empty collection of source entries. Keys must be unique within
            the request, compared case-insensitively.
      additionalProperties: false
    ApiResponse:
      required:
        - errors
        - requestId
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ApiError'
        requestId:
          type: string
          description: HTTP request id used for support and diagnostics.
      additionalProperties: false
    IngestEntity:
      required:
        - key
        - delete
        - properties
      type: object
      properties:
        key:
          maxLength: 256
          minLength: 1
          type: string
          description: Entry key unique within this request.
          example: sku-123
        delete:
          type: boolean
          description: When true, delete the entry and send an empty properties array.
          example: false
        properties:
          type: array
          items:
            $ref: '#/components/schemas/IngestProperty'
          description: >-
            Entry property values. Property ids are canonicalized to lowercase
            at rest.
      additionalProperties: false
    ApiError:
      required:
        - message
      type: object
      properties:
        message:
          type: string
          description: Human-readable error message.
        details:
          type:
            - 'null'
            - object
          description: Optional structured validation details.
      additionalProperties: false
    IngestProperty:
      required:
        - id
        - value
      type: object
      properties:
        id:
          maxLength: 256
          minLength: 1
          type: string
          description: >-
            Property id. Repeated ids are permitted only for distinct languages;
            reserved system ids are rejected.
          example: name
        value:
          type: string
          description: Property value encoded as text.
          example: Blue chair
        language:
          maxLength: 10
          minLength: 2
          type:
            - 'null'
            - string
          description: Optional language code for localized values.
          example: en
        delimiter:
          type:
            - 'null'
            - string
          description: Optional delimiter used to split list values.
          example: '|'
        type:
          enum:
            - Text
            - LocalizedText
            - List
            - LocalizedList
            - Boolean
            - Timestamp
            - Integer
            - Decimal
          type:
            - 'null'
            - string
          description: Optional value type hint.
      additionalProperties: false
  securitySchemes:
    kindeOAuth:
      type: oauth2
      description: >-
        Sign in with the existing Occtoo Studio identity and selected
        organization.
      flows:
        authorizationCode:
          authorizationUrl: >-
            https://auth.occtoo.com/oauth2/auth?audience=https%3A%2F%2Fapi-weu.occtoo.com
          tokenUrl: https://auth.occtoo.com/oauth2/token
          scopes:
            openid: Authenticate the user with OpenID Connect.
            profile: Read the user's basic profile.
            email: Read the user's email address.
            offline: Refresh the access token without another interactive sign-in.
          x-usePkce: SHA-256
          x-scalar-redirect-uri: https://api.occtoo.com/docs/
    bearerAuth:
      type: http
      description: >-
        Tenant-scoped Occtoo access token, including Kinde machine-to-machine
        application tokens.
      scheme: bearer
      bearerFormat: JWT
    apiKey:
      type: apiKey
      description: Occtoo organization API key.
      name: x-api-key
      in: header

````