Imports

Imports load the benefits you granted before AbuseZero into your workspace's claim history, so protection starts with your full history on day one. Every imported outcome becomes history that later evaluations are checked against.

There are two ways in:

• JSON: send up to 1,000 granted outcomes in one request. They're queued and applied in the background, with no review step.
• CSV: upload up to 100,000 rows. AbuseZero validates every row and holds the import for your review. Nothing is applied until you confirm it.

For a walkthrough, see Import outcome history.

Examples on this page use a server client:

import { AbuseZero } from "abusezero/server";

const abusezero = new AbuseZero({ key: process.env.ABUSEZERO_SECRET_KEY!, outage: "throw" });

The import objectCopy Anchor Link

{
  "object": "import",
  "id": "imp_2b8e4d6f-1a3c-4f5e-9b7d-8c0a2e4f6b13",
  "state": "preview",
  "failure": null,
  "total": 1240,
  "validated": 1240,
  "processed": 0,
  "imported": 0,
  "skipped": 0,
  "rejected": 2,
  "created_at": "2026-10-29T11:20:05.000Z",
  "completed_at": null,
  "errors": [
    { "row": 18, "error": "Check this email address." },
    { "row": 907, "error": "Use the time the benefit was actually granted, not a future time." }
  ]
}

Import statesCopy Anchor Link

Failure reasonsCopy Anchor Link

New codes may be added within v1. Treat a code you don't recognize like import_failed.

Import outcomes as JSONCopy Anchor Link

Adds up to 1,000 granted outcomes in one request. The import is queued and applied in the background. Retrieve it to follow its progress.

Also available as abusezero imports create in the AbuseZero CLI, abusezero_create_outcome_import on the AbuseZero MCP server and importOutcomes() in the AbuseZero Node.js SDK.

Request bodyCopy Anchor Link

The body is at most 1 MiB.

ExampleCopy Anchor Link

const job = await abusezero.importOutcomes(
  [
    {
      outcome: "granted",
      benefit: "pro_trial",
      subject: { external_id: "user_4821", email: "jordan@example.com", email_verified: true },
      occurred_at: "2026-03-14T09:30:00Z",
      external_outcome_id: "grant_10293",
    },
  ],
  "history-batch-0001",
);

ResponseCopy Anchor Link

Returns 202.

{
  "object": "import",
  "id": "imp_5f1c7a3e-9d2b-4c6a-8e4f-1b3d5a7c9e20",
  "state": "queued"
}

Rows that can't be applied, for example because their benefit doesn't exist, are counted in rejected with a message in errors. The rest of the import still goes through.

ErrorsCopy Anchor Link

For every other code, see REST API errors.

Import a CSV fileCopy Anchor Link

A CSV import takes five steps:

1. Create an upload to get a one-time upload URL.
2. Upload the file to that URL.
3. Validate the import. AbuseZero checks every row.
4. Retrieve the import until it reaches preview, then review its counts and errors.
5. Confirm the import to apply it, or cancel it.

File formatCopy Anchor Link

The first row names the columns. Each column may appear once, and no other columns are accepted.

email,external_user_id,benefit_key,outcome,occurred_at,external_outcome_id
jordan@example.com,user_4821,pro_trial,granted,2026-03-14T09:30:00Z,grant_10293
sam@example.com,user_5307,pro_trial,granted,2026-04-02T16:05:00+02:00,grant_10377

A file holds 1 to 100,000 rows and is at most 25 MiB.

Create an uploadCopy Anchor Link

Creates a CSV import and returns the address to upload its file to.

Also available as abusezero imports create-csv in the AbuseZero CLI, abusezero_create_csv_import on the AbuseZero MCP server and createCsvImport() in the AbuseZero Node.js SDK.

The request has no fields. Send an empty JSON object.

ExampleCopy Anchor Link

const upload = await abusezero.createCsvImport("history-csv-2026-10-29") as {
  id: string;
  url: string;
  upload_headers: Record<string, string>;
};

ResponseCopy Anchor Link

Returns 202.

{
  "object": "import_upload",
  "id": "imp_2b8e4d6f-1a3c-4f5e-9b7d-8c0a2e4f6b13",
  "url": "https://api.abusezero.com/…",
  "upload_headers": {
    "Content-Type": "text/csv",
    "If-None-Match": "*"
  }
}

A retry with the same Idempotency-Key returns the same import with a fresh upload url, so a lost response never leaves an extra import behind.

ErrorsCopy Anchor Link

Upload the fileCopy Anchor Link

Send the file to url with a PUT request and every header in upload_headers. No API key is needed: the URL carries its own authorization. Send the whole file as one request body, as both samples do.

import { readFile } from "node:fs/promises";

const response = await fetch(upload.url, {
  method: "PUT",
  headers: upload.upload_headers,
  body: await readFile("history.csv"),
});
if (!response.ok) throw new Error(`Upload failed with status ${response.status}`);

A successful upload returns 204 with no body. A failed upload returns the standard error envelope:

Validate the importCopy Anchor Link

Starts validation of the uploaded file. Call it once the upload succeeds.

Also available as abusezero imports validate in the AbuseZero CLI, abusezero_validate_import on the AbuseZero MCP server and validateImport() in the AbuseZero Node.js SDK.

Path parametersCopy Anchor Link

ExampleCopy Anchor Link

const job = await abusezero.validateImport(upload.id, "validate-imp-2b8e4d6f");

ResponseCopy Anchor Link

Returns 201 with the import object, usually in validating. Calling it again after validation has started returns the import as it is.

Retrieve the import until it reaches preview or failed. A file fails validation when its columns don't match the file format, it has no rows or more than 100,000, it's larger than 25 MiB, it can't be read as CSV, or it changed during validation.

ErrorsCopy Anchor Link

Retrieve an importCopy Anchor Link

Also available as abusezero imports get in the AbuseZero CLI, abusezero_get_import on the AbuseZero MCP server and getImport() in the AbuseZero Node.js SDK.

Path parametersCopy Anchor Link

ExampleCopy Anchor Link

const job = await abusezero.getImport("imp_2b8e4d6f-1a3c-4f5e-9b7d-8c0a2e4f6b13");

ResponseCopy Anchor Link

Returns 200 with the import object, including up to the first 100 row errors.

ErrorsCopy Anchor Link

Download the error reportCopy Anchor Link

Creates a CSV of every row problem in an import, with the columns row and error.

Also available as abusezero imports errors in the AbuseZero CLI, abusezero_get_import_errors on the AbuseZero MCP server and call() in the AbuseZero Node.js SDK.

Path parametersCopy Anchor Link

ExampleCopy Anchor Link

const report = await abusezero.call("/v1/imports/imp_2b8e4d6f-1a3c-4f5e-9b7d-8c0a2e4f6b13/errors");

ResponseCopy Anchor Link

Returns 200. The link works for 5 minutes. Request the report again for a new link.

{
  "object": "import_error_report",
  "url": "https://api.abusezero.com/…"
}

ErrorsCopy Anchor Link

Confirm the importCopy Anchor Link

Applies an import that's in preview. Rows that were rejected during validation aren't applied.

Also available as abusezero imports confirm in the AbuseZero CLI, abusezero_confirm_import on the AbuseZero MCP server and confirmImport() in the AbuseZero Node.js SDK.

Path parametersCopy Anchor Link

ExampleCopy Anchor Link

await abusezero.confirmImport("imp_2b8e4d6f-1a3c-4f5e-9b7d-8c0a2e4f6b13", "confirm-imp-2b8e4d6f");

ResponseCopy Anchor Link

Returns 201.

{
  "object": "import",
  "id": "imp_2b8e4d6f-1a3c-4f5e-9b7d-8c0a2e4f6b13",
  "state": "queued"
}

ErrorsCopy Anchor Link

Cancel an importCopy Anchor Link

Also available as abusezero imports cancel in the AbuseZero CLI, abusezero_cancel_import on the AbuseZero MCP server and cancelImport() in the AbuseZero Node.js SDK.

Path parametersCopy Anchor Link

ExampleCopy Anchor Link

await abusezero.cancelImport("imp_2b8e4d6f-1a3c-4f5e-9b7d-8c0a2e4f6b13", "cancel-imp-2b8e4d6f");

ResponseCopy Anchor Link

Returns 201.

{
  "object": "import",
  "id": "imp_2b8e4d6f-1a3c-4f5e-9b7d-8c0a2e4f6b13",
  "state": "cancelled"
}

ErrorsCopy Anchor Link

List importsCopy Anchor Link

Returns imports newest first. List items don't include errors.

Also available as abusezero imports list in the AbuseZero CLI, abusezero_list_imports on the AbuseZero MCP server and imports() in the AbuseZero Node.js SDK.

Query parametersCopy Anchor Link

ExampleCopy Anchor Link

const page = await abusezero.imports({ limit: 20 });

ResponseCopy Anchor Link

Returns 200.

{
  "object": "list",
  "data": [
    {
      "object": "import",
      "id": "imp_2b8e4d6f-1a3c-4f5e-9b7d-8c0a2e4f6b13",
      "state": "complete",
      "total": 1240,
      "validated": 1240,
      "processed": 1240,
      "imported": 1191,
      "skipped": 47,
      "rejected": 2,
      "created_at": "2026-10-29T11:20:05.000Z",
      "completed_at": "2026-10-29T11:26:48.000Z"
    }
  ],
  "next_cursor": null
}

RelatedCopy Anchor Link