Bulk import

POST /api/v1/events/bulk loads up to 5000 records per request as one job, built for day-0 loads and migrations rather than the real-time path of POST /api/v1/events. This page covers the three things a large load needs: sending it, following it row by row, and checking afterwards that HubSpot holds what you sent.

A bulk import writes straight to HubSpot: it does not run your event flow manifest. There are no field_mappings, no when filters, no transforms, no associations and no plugin steps. Every key of an entity is written as a HubSpot property under that exact name, so send HubSpot’s internal property names. If your data needs mapping, send it through the real-time path instead (the entities shape takes up to 200 records per request).

All endpoints on this page authenticate with the connector API key in the x-api-key header, like the rest of the Event API. A job belongs to the connector whose key created it: reading it with another connector’s key answers 404 job_not_found.

Start a job

curl -X POST https://app.plugsync.com/api/v1/events/bulk \
  -H "x-api-key: ps_live_..." \
  -H "content-type: application/json" \
  -d '{
    "entity_type": "contact",
    "external_id_property": "erp_customer_id",
    "idempotency_key": "initial-load-2026-10-part-1",
    "entities": [
      {"erp_customer_id": "C-1", "email": "a@example.com", "firstname": "Ada"},
      {"erp_customer_id": "C-2", "email": "b@example.com", "firstname": "Bo"}
    ]
  }'

Request body

The whole request body may not exceed 10 MiB. Larger loads (for example 40,000 rows) go in consecutive requests of up to 5000 rows each, each with its own idempotency_key.

For each row, an external id that already has an identity mapping (under the same entity_type and store) updates the mapped HubSpot record; otherwise a record is created and mapped. The identity mappings written here are the same ones the real-time path reads, so events sent later for the same external id update these records instead of duplicating them.

entity_type and custom objects

The HubSpot object type a job writes is resolved, in order:

1. hs_object_type, when the request sets it.
2. The object_type of the hubspot schema of the entity named exactly entity_type in the connector’s published config.
3. For the standard types, the HubSpot plural: contact → contacts, company → companies, deal → deals, ticket → tickets, product → products, line_item → line_items, conversation → conversations.
4. entity_type itself, unchanged.

For a custom object HubSpot only accepts the fully qualified name (p<hubId>_<name>, for example p12345678_invoices) or the object type id (2-XXXXXXX, for example 2-1234567), never the display name. Sending "entity_type": "invoices" with no config entity of that name reaches HubSpot as invoices and every row fails with HubSpot’s Unable to infer object type error. Two ways to get it right:

• Use the entity name from your config ("entity_type": "invoice" when the config declares an invoice entity with "object_type": "p12345678_invoices"). The rows land under the same identity key the real-time path uses for that entity, which is what you want when events will keep the records up to date afterwards.
• Set hs_object_type explicitly, for a connector with no published config or to bypass the resolution for a one-off job. Keep entity_type equal to the entity name your flows use if they will later update these records.

HubSpot lists the fully qualified names and object type ids of a portal’s custom objects at GET /crm/v3/schemas.

Response

202 Accepted:

{
  "job_id": "3f6c1e0a-6a43-4c55-9a51-0f1d7b8f2a10",
  "status": "queued",
  "entities_count": 2,
  "chunks_total": 1
}

The rows are processed in chunks of 100 (chunks_total is the request’s row count divided by 100, rounded up), after the response.

Idempotency

Resending a request with the same idempotency_key on the same connector returns the job the key first created, with its current status, and starts nothing new. A request that reuses a key with a different number of entities is rejected with 409 and "detail": "body_mismatch". Only the entity count is compared, so use a new key for every distinct part of a load.

A job whose chunks could not be queued ends failed (see Errors), and resending with the same key returns that same failed job. Retry with a new key.

Quota and rate limits

• Monthly event quota: checked upfront for the whole request. If the rows of the request do not fit in what the organization has left this month, the request is rejected with 429 and the same quota_exceeded detail as the real-time path, and nothing is queued. Each row that succeeds counts as one event, when its chunk completes; failed rows are not counted.
• Per-second rate limit: every call on this page (starts, status polls, row pages, replays, verifications) counts against the organization’s per-second limit, reported in the X-RateLimit-* response headers. Poll /status every few seconds, not in a tight loop.

Errors

A paused connector does not reject the request: the job is accepted and its rows wait, see Held jobs.

Follow a job

Status

curl https://app.plugsync.com/api/v1/events/bulk/{job_id}/status \
  -H "x-api-key: ps_live_..."

{
  "job_id": "3f6c1e0a-6a43-4c55-9a51-0f1d7b8f2a10",
  "status": "partial_failure",
  "entities_total": 5000,
  "entities_succeeded": 4987,
  "entities_failed": 13,
  "entities_skipped": 0,
  "chunks_total": 50,
  "chunks_processed": 50,
  "started_at": "2026-10-14T09:12:03Z",
  "completed_at": "2026-10-14T09:15:41Z",
  "last_error": "chunk 37: 2 entities failed",
  "warning": null
}

Job statuses:

Poll until the status is terminal. A replay of one row recomputes the counters and sets the job to partial_failure or completed, whatever its status was before, failed included.

Held jobs

While the connector is paused or in error, the organization’s syncs are suspended, or an open circuit breaker can block the HubSpot object type the job writes, the job’s rows wait without being written or counted. /status keeps the job queued or running and sets warning to the cause, for example:

"warning": "Chunks are held: the connector is paused. It resumes on its own once the connector is active again."

For a breaker, the warning names each breaker that can hold the job, the object types its flow writes (or that it holds every object type, when opened by fatal errors) and when it can next be probed. The job does not record its object type, so the list includes every breaker that could apply.

Held rows resume on their own once the cause clears, not necessarily in their original order. A row is held for at most 3 days of uninterrupted blocking: past that it ends failed with error_category held_expired, without anything written, and can be replayed. A drain on the connector likewise ends its held rows failed with error_category drained. Rows of a job that is not held are written as usual during a drain.

A job that does not start

A job normally leaves queued within seconds. When it is still queued with started_at at null more than 10 minutes after it was created, and it is not held, warning says that no chunk has been picked up yet:

"warning": "Job queued for 742s and no chunk has been picked up yet. It keeps its place and runs once processing starts, so there is no need to resend it. If it is still queued in a few minutes, contact support@plugsync.com with job_id 6f1c2a9e-4b7d-4e2a-9c1f-3d8e5b0a7c21."

That is not a job waiting its turn. Keep polling for a few more minutes: the job keeps its place and runs once processing starts, so resending it is not needed. If it is still queued, contact support@plugsync.com with the job_id.

The warning covers a job that never starts. A running job whose chunks_processed stops moving across several polls gets no warning: report it to support the same way.

Rows

curl "https://app.plugsync.com/api/v1/events/bulk/{job_id}/rows?status=failed&limit=200&offset=0" \
  -H "x-api-key: ps_live_..."

{
  "job_id": "3f6c1e0a-6a43-4c55-9a51-0f1d7b8f2a10",
  "rows": [
    {
      "reference": "C-1042",
      "status": "failed",
      "error_category": "conflict",
      "error_message": "Contact already exists. Existing ID: 51234"
    },
    {
      "reference": "row:1877",
      "status": "failed",
      "error_category": "mapping",
      "error_message": "mapping_failed: no external id"
    }
  ],
  "total": 13,
  "limit": 200,
  "offset": 0,
  "has_more": false
}

Query parameters:

Rows come in processing order. total is the number of rows matching the filter, and has_more is true while offset plus the rows returned is below total: request the next page with offset increased by limit.

A row appears once its chunk has been processed: there is no pending row status, and a row not yet processed simply is not listed. Row statuses:

reference is the row’s stable handle: its external id, or row:<index> (the 0-based position in the request’s entities array) when the row has no external id or one longer than 300 characters. The same external id sent twice in a request is one row.

error_category

error_message is the readable cause, usually HubSpot’s own answer. error_category groups it:

Other values are HubSpot’s own error category for that record, passed through as HubSpot returned it (for example VALIDATION_ERROR). The field is null for a succeeded or skipped row, and can be null on a failed row when HubSpot gave no category. Transient HubSpot failures (rate limits, 5xx) are not row outcomes: the chunk is retried automatically and the rows report the outcome of the retry.

Replay a failed row

curl -X POST "https://app.plugsync.com/api/v1/events/bulk/{job_id}/rows/C-1042/replay" \
  -H "x-api-key: ps_live_..." \
  -H "content-type: application/json" \
  -d '{
    "entity": {"erp_customer_id": "C-1042", "email": "c.1042@example.com"},
    "entity_type": "contact",
    "external_id_property": "erp_customer_id"
  }'

Reprocesses one failed row with corrected data, through the same path as the original job, and records the outcome on the same row (the reference in the path), even if the correction changes the external id. The job’s counters and status follow.

202 Accepted with {"job_id": "...", "reference": "C-1042", "status": "queued", "warning": null}. For a row of a job started on this endpoint, warning is set when the replay is accepted but held (connector paused or in error, syncs suspended, an open breaker on its object type): it is queued, not lost, and runs once the cause clears. For a row of a file source job in flows emission, warning is always null: the row runs through its flow, whose circuit breakers apply as for any event. Check the outcome with /rows.

A replay needs one event left in the monthly quota (429 quota_exceeded otherwise), and counts as one event only if the row then succeeds. Other errors:

Verify a load against HubSpot

POST /api/v1/events/bulk/verify compares a set of records with what HubSpot holds now, record by record and property by property. It only reads HubSpot: it writes nothing and does not count against the monthly event quota (it does count against the per-second rate limit, like every call). plugsync does not keep the rows you sent, so you send them again, all of them or a subset.

curl -X POST https://app.plugsync.com/api/v1/events/bulk/verify \
  -H "x-api-key: ps_live_..." \
  -H "content-type: application/json" \
  -d '{
    "entity_type": "contact",
    "external_id_property": "erp_customer_id",
    "source_batch_id": "3f6c1e0a-6a43-4c55-9a51-0f1d7b8f2a10",
    "entities": [
      {"erp_customer_id": "C-1", "email": "a@example.com", "firstname": "Ada"}
    ]
  }'

202 Accepted:

{
  "job_id": "b2a7d4c9-1e0f-4f3a-8d6b-2c9e5a7f1b34",
  "status": "queued",
  "records_count": 1,
  "chunks_total": 1
}

Only the properties present in each record you send are compared, never the whole HubSpot record. Values are compared after normalization: null and "" are the same (no value), booleans compare as true / false, and whole numbers compare by value (10, 10.0 and "10.0" are equal).

Verification status

GET /api/v1/events/bulk/verify/{job_id}/status:

{
  "job_id": "b2a7d4c9-1e0f-4f3a-8d6b-2c9e5a7f1b34",
  "status": "completed",
  "records_total": 5000,
  "records_ok": 4990,
  "records_diff": 7,
  "records_absent": 3,
  "records_error": 0,
  "chunks_total": 50,
  "chunks_processed": 50,
  "last_error": null
}

The statuses have the same names as a bulk import’s: queued and running (poll again), completed (every record checked), partial_failure (some records could not be read from HubSpot: records_error of them, said in last_error), failed (no record could be checked, for example the connector has no usable HubSpot connection, or HubSpot read errors on every record; last_error says which). chunks_processed moves while the job runs; records_ok, records_diff, records_absent and records_error are filled in when it ends. A verification that stays running while chunks_processed no longer moves will not finish: start a new one for the records missing from its /rows.

Verification rows

GET /api/v1/events/bulk/verify/{job_id}/rows takes the same status, limit (default 200, max 1000) and offset parameters as the bulk rows, and pages the same way:

{
  "job_id": "b2a7d4c9-1e0f-4f3a-8d6b-2c9e5a7f1b34",
  "rows": [
    {
      "reference": "C-7",
      "status": "diff",
      "differences": {
        "firstname": {"expected": "Ada", "actual": "Adah"}
      },
      "error_message": null
    }
  ],
  "total": 7,
  "limit": 200,
  "offset": 0,
  "has_more": false
}

reference follows the bulk import rule: the external id, or row:<index> when there is none or it is longer than 300 characters. A record sent twice is one row.

Related reference

• Event API: the real-time path, its authentication and its 429 responses.
• Reliability: retry, failures, replay: circuit breakers and drains, which can hold a bulk job.
• Data export: bulk imports and verifications are part of a connector’s export.