Imports — PassportCraft API

Start an asynchronous bulk import.

post/organizations/{organization}/imports

Scope: passports:write
Idempotency-Key: Accepted
Returns: 202

Path parameters

organizationstringRequired

The organization this request acts for. The credential must hold a grant for it.

Request body

rowsarray of objectsRequired

Between 1 and 500 rows. Exceeding the ceiling is refused with its own max_rows rule, which is the refusal a batching loop branches on. An unrecognised key anywhere in a row is an error, not a silently dropped field.

categorystringRequired

A category id from GET /categories.

dataobjectRequired

The passport document, exactly as POST /passports takes it.

external_idstringOptional

Your identifier for the row. Echoed back on the per-row result, which is how a failed row is reconciled.

Errors

Every refusal this endpoint can return, with the status it arrives with.

Request

curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/imports" \
  -X POST \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "rows": [
    {
      "external_id": "SKU-4471-BLK",
      "category": "textile",
      "data": {
        "product_name": "Merino Crew Neck",
        "manufacturer_country": "FR"
      }
    },
    {
      "external_id": "SKU-4471-NVY",
      "category": "textile",
      "data": {
        "product_name": "Merino Crew Neck Navy",
        "manufacturer_country": "FR"
      }
    }
  ]
}'

Response · 202

{
  "object": "import_job",
  "id": "7b52909a-8f2c-4e1d-9b3a-6d5f4e3c2b1a",
  "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/imports/7b52909a-8f2c-4e1d-9b3a-6d5f4e3c2b1a",
  "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
  "livemode": true,
  "status": "queued",
  "total_rows": 2,
  "succeeded_rows": 0,
  "failed_rows": 0,
  "pending_rows": 2,
  "attempts": 0,
  "created_at": "2026-08-02T09:50:00.114Z",
  "started_at": null,
  "completed_at": null
}

POST /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/imports

List import jobs.

get/organizations/{organization}/imports

Scope: passports:read
Idempotency-Key: Not accepted
Returns: 200

Path parameters

organizationstringRequired

The organization this request acts for. The credential must hold a grant for it.

Query parameters

limitstringOptional

How many records to return. The server may return fewer.

cursorstringOptional

The next_cursor from the previous page. A cursor encodes the filters it was issued under; sending it with different filters is refused with cursor_invalid.

statusstringOptional

Return only jobs in this status.

Errors

Every refusal this endpoint can return, with the status it arrives with.

Request

curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/imports?status=completed" \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY"

Response · 200

{
  "object": "list",
  "data": [
    {
      "object": "import_job",
      "id": "7b52909a-8f2c-4e1d-9b3a-6d5f4e3c2b1a",
      "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/imports/7b52909a-8f2c-4e1d-9b3a-6d5f4e3c2b1a",
      "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
      "livemode": true,
      "status": "completed",
      "total_rows": 2,
      "succeeded_rows": 1,
      "failed_rows": 1,
      "pending_rows": 0,
      "attempts": 1,
      "created_at": "2026-08-02T09:50:00.114Z",
      "started_at": "2026-08-02T09:50:03.902Z",
      "completed_at": "2026-08-02T09:50:05.441Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

GET /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/imports?status=completed

Fetch one import job and its progress.

get/organizations/{organization}/imports/{id}

Scope: passports:read
Idempotency-Key: Not accepted
Returns: 200

Path parameters

organizationstringRequired

The organization this request acts for. The credential must hold a grant for it.

idstringRequired

The identifier of the resource. Treat it as an opaque string.

Query parameters

row_limitstringOptional

How many per-row results to include with the job.

after_row_indexstringOptional

Return per-row results after this row index, so a large job can be walked.

Errors

Every refusal this endpoint can return, with the status it arrives with.

Request

curl "https://passportcraft.com/api/v1/organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/imports/7b52909a-8f2c-4e1d-9b3a-6d5f4e3c2b1a?row_limit=50" \
  -H "Authorization: Bearer $PASSPORTCRAFT_API_KEY"

Response · 200

{
  "object": "import_job",
  "id": "7b52909a-8f2c-4e1d-9b3a-6d5f4e3c2b1a",
  "name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/imports/7b52909a-8f2c-4e1d-9b3a-6d5f4e3c2b1a",
  "organization_id": "8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2",
  "livemode": true,
  "status": "completed",
  "total_rows": 2,
  "succeeded_rows": 1,
  "failed_rows": 1,
  "pending_rows": 0,
  "attempts": 1,
  "created_at": "2026-08-02T09:50:00.114Z",
  "started_at": "2026-08-02T09:50:03.902Z",
  "completed_at": "2026-08-02T09:50:05.441Z",
  "rows": {
    "object": "list",
    "data": [
      {
        "object": "import_row",
        "row_index": 0,
        "external_id": "SKU-4471-BLK",
        "status": "succeeded",
        "passport_id": "2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
        "passport_name": "organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/passports/2c1f9e07-3b4d-4a18-9f6c-5e0a7b8d3c41",
        "error": null,
        "processed_at": "2026-08-02T09:50:04.771Z"
      },
      {
        "object": "import_row",
        "row_index": 1,
        "external_id": "SKU-4471-NVY",
        "status": "failed",
        "passport_id": null,
        "passport_name": null,
        "error": {
          "code": "unknown_category",
          "detail": null
        },
        "processed_at": "2026-08-02T09:50:05.180Z"
      }
    ],
    "has_more": false,
    "next_after_row_index": null
  }
}

GET /organizations/8f14e45f-ceea-467a-9a5f-8dc7d9c6a1b2/imports/7b52909a-8f2c-4e1d-9b3a-6d5f4e3c2b1a?row_limit=50