Batch

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.

POST

api

objects

{objectType}

batch

Batch create or update objects

curl --request POST \
  --url https://app.useitem.io/api/objects/{objectType}/batch \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "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"
      }
    }
  ]
}
'

{
  "results": [
    {
      "id": 123,
      "status": "updated"
    },
    {
      "id": 456,
      "status": "updated"
    },
    {
      "id": 789,
      "status": "created"
    }
  ],
  "summary": {
    "total": 3,
    "created": 1,
    "updated": 2,
    "failed": 0
  }
}

Authorizations

x-api-key

string

header

required

Your organization's API key (starts with sk_live_)

Path Parameters

objectType

string

required

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.

Body

application/json

objects

object[]

required

Show child attributes

Response

Batch processed

results

object[]

Show child attributes

summary

object

Show child attributes

Get object schemaReturns all object types available to the organization along with their field definitions. Use this to discover what objects exist, what fields they have, and what select options are available. Includes both system object types (People, Companies) and any custom object types created by the organization.

Batch create or update objects

curl --request POST \
  --url https://app.useitem.io/api/objects/{objectType}/batch \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "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"
      }
    }
  ]
}
'

{
  "results": [
    {
      "id": 123,
      "status": "updated"
    },
    {
      "id": 456,
      "status": "updated"
    },
    {
      "id": 789,
      "status": "created"
    }
  ],
  "summary": {
    "total": 3,
    "created": 1,
    "updated": 2,
    "failed": 0
  }
}