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

# Batch create or update objects

> Creates or updates up to 100 objects in a single request. Ideal for
scheduled syncs (e.g., pushing data every 5 minutes).

**Matching behavior:**
- If `match_by` and `match_value` are provided and a record is found, it is **updated**.
- If no match is found (or `match_by` is omitted), a new record is **created**.
- For contacts and companies, creation also deduplicates automatically (by email/domain).

**Error handling:**
- Each object is processed independently — a failure on one object does not abort the batch.
- Check the `results` array for per-object status.

Objects are processed sequentially to ensure correct deduplication.


## OpenAPI

````yaml /openapi.yaml post /api/objects/{objectType}/batch
openapi: 3.1.0
info:
  title: item API
  description: >
    The item API provides full CRUD access to your organization's data — People,
    Companies, and Custom Objects.


    Use it to:

    - Push structured data into item on a schedule

    - Sync custom field values across your stack

    - Pull filtered records and pre-configured views

    - Use item as your source of truth for customer data


    ## Authentication


    All requests require an API key passed in the `x-api-key` header.


    You can generate an API key from **Settings > System > API Key** in your
    item workspace.


    ```bash

    curl -H "x-api-key: sk_live_..." https://app.useitem.io/api/objects/contacts

    ```
  version: 1.0.0
  contact:
    name: item Support
servers:
  - url: https://app.useitem.io
    description: Production
  - url: http://localhost:3000
    description: Local development
security:
  - apiKey: []
tags:
  - name: Objects
    description: Create, read, update, and delete People, Companies, and Custom Objects.
  - name: Schema
    description: Discover available object types and their field definitions.
  - name: Users
    description: List organization members and their access levels.
  - name: Views
    description: List and execute pre-configured views to pull filtered data.
  - name: Batch
    description: Bulk create or update objects for high-frequency sync operations.
  - name: Webhooks
    description: Trigger skills (AI agents) via HTTP webhooks from external systems.
paths:
  /api/objects/{objectType}/batch:
    parameters:
      - $ref: '#/components/parameters/objectType'
    post:
      tags:
        - Batch
      summary: Batch create or update objects
      description: >
        Creates or updates up to 100 objects in a single request. Ideal for

        scheduled syncs (e.g., pushing data every 5 minutes).


        **Matching behavior:**

        - If `match_by` and `match_value` are provided and a record is found, it
        is **updated**.

        - If no match is found (or `match_by` is omitted), a new record is
        **created**.

        - For contacts and companies, creation also deduplicates automatically
        (by email/domain).


        **Error handling:**

        - Each object is processed independently — a failure on one object does
        not abort the batch.

        - Check the `results` array for per-object status.


        Objects are processed sequentially to ensure correct deduplication.
      operationId: batchUpsert
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - objects
              properties:
                objects:
                  type: array
                  maxitems: 100
                  items:
                    $ref: '#/components/schemas/BatchObjectInput'
            example:
              objects:
                - name: Alex Johnson
                  match_by: email
                  match_value: alex@acme.com
                  fields:
                    email: alex@acme.com
                    role: Senior Engineer
                    custom_score: 95
                - name: Acme Corp
                  match_by: id
                  match_value: 456
                  fields:
                    website_url: https://acme.com
                    industry: Technology
                - name: New Contact
                  fields:
                    email: new@example.com
                    role: Designer
      responses:
        '200':
          description: Batch processed
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/BatchResultitem'
                  summary:
                    $ref: '#/components/schemas/BatchSummary'
              example:
                results:
                  - id: 123
                    status: updated
                  - id: 456
                    status: updated
                  - id: 789
                    status: created
                summary:
                  total: 3
                  created: 1
                  updated: 2
                  failed: 0
        '400':
          description: Invalid request (missing objects array, batch too large, etc.)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                too_large:
                  value:
                    error: Batch size exceeds maximum of 100. Received 150 objects.
                missing_array:
                  value:
                    error: Request body must contain an "objects" array
        '401':
          description: Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Object type not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  parameters:
    objectType:
      name: objectType
      in: path
      required: true
      description: >
        The object type slug. Use `contacts` for People, `companies` for
        Companies,

        or the slug of a Custom Object (e.g., `deals`, `tickets`).


        Singular forms (`contact`, `company`) are also accepted.
      schema:
        type: string
      examples:
        contacts:
          value: contacts
          summary: People
        companies:
          value: companies
          summary: Companies
        custom:
          value: deals
          summary: Custom object
  schemas:
    BatchObjectInput:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Name of the object to create or update
          example: Alex Johnson
        match_by:
          type: string
          enum:
            - id
            - email
            - name
          description: |
            How to find an existing record to update.
            - `id` — match by record ID (all object types)
            - `email` — match by email (contacts only)
            - `name` — match by exact name (all object types)
        match_value:
          oneOf:
            - type: string
            - type: integer
          description: The value to match against (required when `match_by` is set)
          example: alex@acme.com
        fields:
          type: object
          additionalProperties: true
          description: Key-value pairs of fields to set
          example:
            email: alex@acme.com
            role: Engineer
            custom_score: 95
        profile_image_url:
          type: string
          format: uri
          description: URL for avatar (contacts) or logo (companies)
    BatchResultitem:
      type: object
      properties:
        id:
          type: integer
          nullable: true
          description: Record ID (null if failed)
          example: 123
        status:
          type: string
          enum:
            - created
            - updated
            - failed
          example: updated
        error:
          type: string
          description: Error message (only present when status is `failed`)
    BatchSummary:
      type: object
      properties:
        total:
          type: integer
          example: 3
        created:
          type: integer
          example: 1
        updated:
          type: integer
          example: 1
        failed:
          type: integer
          example: 1
    Error:
      type: object
      properties:
        error:
          type: string
          example: Object not found
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: Your organization's API key (starts with `sk_live_`)

````