Entity batch failures

Endpoints

GET https://api.gu1.ai/batch-import/entity-jobs/{jobId}/failures.csv
GET https://api.gu1.ai/batch-import/entity-jobs/{jobId}/failures

Legacy CSV alias (same file):

GET https://api.gu1.ai/entities/automatic/bulk/imports/{jobId}/failures.csv

…/failures.csv → CSV download (failed rows only)
…/failures → JSON (failures[] + skips[] when applicable)

This endpoint also returns job status and counters when there are no row failures (failures: []). For generic polling across import kinds, prefer Get batch job status.

Authentication

Authorization: Bearer YOUR_API_KEY

Requires at least one of: transactions:create, entities:bulk_import, events:create.

HTTP responses

Status	When
`200`	Job found
`401`	Not authenticated
`403`	Missing permission
`404`	Job not found

CSV columns

Column	Description
`tax_id`	Row tax id
`type`	`person` or `company`
`outcome`	Always `failed` in this export
`code`	Stable failure code — see Failure codes
`error_message`	Human-readable detail

Duplicate taxId (bulk manual default): same taxId + same type → skipped_existing, code SKIPPED_DUPLICATE_TAX_ID. Does not appear in failures.csv. Use JSON skips[] or the full job report.

JSON response

{
  "success": true,
  "jobId": "…",
  "kind": "entity_automatic",
  "status": "completed",
  "totalItems": 100,
  "succeeded": 97,
  "failed": 2,
  "skipped": 1,
  "failures": [
    {
      "taxId": "20123456789",
      "type": "company",
      "outcome": "failed",
      "code": "DUPLICATE_EXTERNAL_ID",
      "message": "An entity with external ID \"X\" already exists…"
    }
  ],
  "truncated": false,
  "failuresTotal": 2,
  "skips": [
    {
      "taxId": "30111222333",
      "type": "person",
      "outcome": "skipped_existing",
      "code": "SKIPPED_DUPLICATE_TAX_ID"
    }
  ],
  "skipsTotal": 1
}

Skip code	Meaning
`SKIPPED_DUPLICATE_TAX_ID`	Manual bulk: taxId+type already existed
`SKIPPED_ENTITY_ALREADY_EXISTS`	Automatic bulk: entity already existed

failures.csv contains only outcome=failed rows. See also: Import entities (CSV), Failure codes.

User-event batch failures Requeue transaction batch job

⌘I

Getting Started

SDK

Use Cases

Webhooks

Workflows

Monitoring (entities)

Person

Messaging

Company

Transactions

Devices

Events

Know Your Customer (KYC)

Payment Methods

Rules

Custom lists

Risk Matrix

Alerts

Investigations

Data Ingestion

Bulk imports

Documents

Enrichment

Services

Integrations

Interactive Tutorials

Entity batch failures

Endpoints

Authentication

HTTP responses

CSV columns

JSON response

​Endpoints

​Authentication

​HTTP responses

​CSV columns

​JSON response

Endpoints

Authentication

HTTP responses

CSV columns

JSON response