Follow an import

GET/collection/imports/{id}

Signed in

Poll it after POST /collection/imports: queued, then matching (progress counts rows), then importing (progress counts the matched rows written), then complete, or failed with an error. The counts grow as it goes. Once it has added copies, undo says where to take them back.

SDK method: collector.getCollectionImport()
Key scopes: collection:read
Headers: X-Request-Id

Path parameters

idstring (uuid)required

Responses

200OKThe import.

ImportJob

A collection file sent to the API, matched and imported in the background: poll it until it’s complete.

idstring (uuid)required
The job’s id, which is also its import’s id (undo).
statusenumrequired
One ofqueuedmatchingimportingcompletefailed
formatenumrequired
What the header says the file is.
One ofcollectorclzlocggeneric
fileNamestring or nullrequired
optionsobjectrequired
ShowHide the fields of options
- defaultStatusenumrequired
  One ofownedwishlist
- needsReviewenumrequired
  One ofskipimport
progressobjectrequired
Matching counts rows; importing counts the matched rows written so far.
ShowHide the fields of progress
- phaseenumrequired
  One ofqueuedmatchingimportingdone
- doneintegerrequired
- totalintegerrequired
countsobjectrequired
So far; final once complete.
ShowHide the fields of counts
- rowsintegerrequired
  Rows after the header.
- matchedintegerrequired
  Rows matched to a catalog issue, to import.
- needsReviewintegerrequired
  Rows held back: more than one series could be meant.
- notFoundintegerrequired
  Rows the catalog has no issue for (yet).
- skippedintegerrequired
  Rows that aren’t a comic, or not in your collection or wishlist.
- failedintegerrequired
  Rows whose copies couldn’t be added.
- createdintegerrequired
  Copies added (a row with a quantity adds that many).
- existingintegerrequired
  Copies already in your collection from an earlier import: not added again.
undoobject or nullrequired
Once the import has added copies, for 30 days.
ShowHide the fields of undo
- hrefstringrequired
  POST it to remove the copies this import added.
- untilstring (date-time)required
errorstring or nullrequired
requestedAtstring (date-time)required
startedAtstring (date-time) or nullrequired
completedAtstring (date-time) or nullrequired

4Errors401 · 404 · 429 · 500

401
unauthorized
unauthorized: Not signed in (no session or token, or an expired one).
404
not_found import_not_found
not_found: Nothing at that address.
import_not_found: No import of yours with that id.
429
rate_limited temporarily_blocked
rate_limited: Over the caller’s limit: the per-minute burst or the per-day quota (RateLimit headers; wait Retry-After seconds).
temporarily_blocked: Too many refused requests in a row: blocked for a while (Retry-After says how long).
500
internal
internal: Something went wrong on our side (quote the requestId).

curl 'https://api.collection.id/v1/collection/imports/2b7e4c1a-5d3f-4a8e-9c6b-0f1e2d3c4b5a' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN"

{
  "id": "2b7e4c1a-5d3f-4a8e-9c6b-0f1e2d3c4b5a",
  "status": "complete",
  "format": "generic",
  "fileName": "my-comics.csv",
  "options": {
    "defaultStatus": "owned",
    "needsReview": "skip"
  },
  "progress": {
    "phase": "done",
    "done": 2,
    "total": 2
  },
  "counts": {
    "rows": 4,
    "matched": 2,
    "needsReview": 1,
    "notFound": 1,
    "skipped": 0,
    "failed": 0,
    "created": 2,
    "existing": 0
  },
  "undo": {
    "href": "/api/v1/collection/imports/2b7e4c1a-5d3f-4a8e-9c6b-0f1e2d3c4b5a/undo",
    "until": "2026-11-11T09:30:00.000Z"
  },
  "error": null,
  "requestedAt": "2026-10-12T09:30:00.000Z",
  "startedAt": "2026-10-12T09:30:01.204Z",
  "completedAt": "2026-10-12T09:30:09.861Z"
}

Responses

200OKThe import.

ImportJob

A collection file sent to the API, matched and imported in the background: poll it until it’s complete.

idstring (uuid)required
The job’s id, which is also its import’s id (undo).
statusenumrequired
One ofqueuedmatchingimportingcompletefailed
formatenumrequired
What the header says the file is.
One ofcollectorclzlocggeneric
fileNamestring or nullrequired
optionsobjectrequired
ShowHide the fields of options
- defaultStatusenumrequired
  One ofownedwishlist
- needsReviewenumrequired
  One ofskipimport
progressobjectrequired
Matching counts rows; importing counts the matched rows written so far.
ShowHide the fields of progress
- phaseenumrequired
  One ofqueuedmatchingimportingdone
- doneintegerrequired
- totalintegerrequired
countsobjectrequired
So far; final once complete.
ShowHide the fields of counts
- rowsintegerrequired
  Rows after the header.
- matchedintegerrequired
  Rows matched to a catalog issue, to import.
- needsReviewintegerrequired
  Rows held back: more than one series could be meant.
- notFoundintegerrequired
  Rows the catalog has no issue for (yet).
- skippedintegerrequired
  Rows that aren’t a comic, or not in your collection or wishlist.
- failedintegerrequired
  Rows whose copies couldn’t be added.
- createdintegerrequired
  Copies added (a row with a quantity adds that many).
- existingintegerrequired
  Copies already in your collection from an earlier import: not added again.
undoobject or nullrequired
Once the import has added copies, for 30 days.
ShowHide the fields of undo
- hrefstringrequired
  POST it to remove the copies this import added.
- untilstring (date-time)required
errorstring or nullrequired
requestedAtstring (date-time)required
startedAtstring (date-time) or nullrequired
completedAtstring (date-time) or nullrequired

4Errors401 · 404 · 429 · 500

401
unauthorized
unauthorized: Not signed in (no session or token, or an expired one).
404
not_found import_not_found
not_found: Nothing at that address.
import_not_found: No import of yours with that id.
429
rate_limited temporarily_blocked
rate_limited: Over the caller’s limit: the per-minute burst or the per-day quota (RateLimit headers; wait Retry-After seconds).
temporarily_blocked: Too many refused requests in a row: blocked for a while (Retry-After says how long).
500
internal
internal: Something went wrong on our side (quote the requestId).

{ "id": "2b7e4c1a-5d3f-4a8e-9c6b-0f1e2d3c4b5a", "status": "complete", "format": "generic", "fileName": "my-comics.csv", "options": { "defaultStatus": "owned", "needsReview": "skip" }, "progress": { "phase": "done", "done": 2, "total": 2 }, "counts": { "rows": 4, "matched": 2, "needsReview": 1, "notFound": 1, "skipped": 0, "failed": 0, "created": 2, "existing": 0 }, "undo": { "href": "/api/v1/collection/imports/2b7e4c1a-5d3f-4a8e-9c6b-0f1e2d3c4b5a/undo", "until": "2026-11-11T09:30:00.000Z" }, "error": null, "requestedAt": "2026-10-12T09:30:00.000Z", "startedAt": "2026-10-12T09:30:01.204Z", "completedAt": "2026-10-12T09:30:09.861Z" }