API reference / Collectors

Certificates

Slab certificates: the grader’s record for a cert, and duplicate-claim checks.

GET/api/v1/certs/lookup

Graders we can look up

Signed in

Which grading companies’ records can be looked up here (the copy form only offers those).

SDK: collector.listCertProviders()
Key scopes: collection:read(API keys are coming soon)
Headers: If-None-MatchX-Request-Id

Responses

200Availability per grader.
object
- availablemap of booleanrequired
  Whether each grader’s records can be looked up here.
304Not modified: your copy (the ETag in If-None-Match) is current.

Errors (401, 500)

401unauthorized
unauthorized: Not signed in (no session or token, or an expired one).
500internal
internal: Something went wrong on our side (quote the requestId).

curl

curl 'https://collection.id/api/v1/certs/lookup' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN"

TypeScript SDK

await collector.listCertProviders();

POST/api/v1/certs/lookup

Look up a certificate

Signed in

The grader’s record for a cert, for the copy form before the copy is saved. Served from the shared cache while fresh; otherwise one call to the grader, within its daily budget. 60 lookups an hour.

SDK: collector.lookupCert()
Key scopes: collection:read(API keys are coming soon)
Headers: X-Request-Id

Request body (required, application/json)

object

companyenumrequired
One ofcgccbcspsapgxegshgaother
certstringrequired1–80 characters
refreshbooleanoptional
Ask the grader even if the cache is fresh.

Responses

200Found, not found, or why it can’t be looked up now.
object or object or object
1. Option 1: object
  companyenumrequired
  One ofcgccbcspsapgxegshgaother
  certstringrequired
  Normalized.
  status"found"required
  recordCertRecordrequired
  fetchedAtstring (date-time)required
  cachedbooleanrequired
2. Option 2: object
  companyenumrequired
  One ofcgccbcspsapgxegshgaother
  certstringrequired
  Normalized.
  status"not_found"required
  sourceUrlstring (uri) or nullrequired
  fetchedAtstring (date-time)required
  cachedbooleanrequired
3. Option 3: object
  companyenumrequired
  One ofcgccbcspsapgxegshgaother
  certstringrequired
  Normalized.
  status"unavailable"required
  reasonenumrequired
  One ofunsupporteddisabledbudgeterror
  messagestringrequired

Errors (400, 401, 429, 500)

400invalid_request invalid_json invalid_cert
invalid_request: The query or body doesn’t match the schema (see errors[]).
invalid_json: The body isn’t JSON.
invalid_cert: Cert numbers are 4–64 letters and digits.
401unauthorized
unauthorized: Not signed in (no session or token, or an expired one).
429rate_limited
rate_limited: More than 60 lookups an hour; wait the Retry-After seconds.
500internal
internal: Something went wrong on our side (quote the requestId).

curl

curl -X POST 'https://collection.id/api/v1/certs/lookup' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN" \
  -H 'Content-Type: application/json' \
  -d @body.json

TypeScript SDK

await collector.lookupCert({ body: { … } });

GET/api/v1/collection/cert-status

Is a certificate already claimed?

Signed in

A live duplicate check while a collector types a cert number: certificates are unique among unsold copies. Says only whether a claim exists, never whose.

SDK: collector.getCertStatus()
Key scopes: collection:read(API keys are coming soon)
Headers: If-None-MatchX-Request-Id

Parameters

Name	In	Type	About
`company`required	query	enum	One of `cgc`, `cbcs`, `psa`, `pgx`, `egs`, `hga`, `other`
`cert`required	query	string	1–80 characters
`exclude`optional	query	string (uuid)	A copy of yours to leave out (the one being edited).

Responses

200Whether the cert is free, yours, or claimed.
object
- companyenumrequired
  One ofcgccbcspsapgxegshgaother
- certstringrequired
  Normalized.
- statusenumrequired
  free: nobody holds it; mine: already in your collection; claimed: another collector holds it.
  One offreemineclaimed
- itemIdstring (uuid) or nullrequired
304Not modified: your copy (the ETag in If-None-Match) is current.

Errors (400, 401, 500)

400invalid_request invalid_cert
invalid_request: The query or body doesn’t match the schema (see errors[]).
invalid_cert: Cert numbers are 4–64 letters and digits.
401unauthorized
unauthorized: Not signed in (no session or token, or an expired one).
500internal
internal: Something went wrong on our side (quote the requestId).

curl

curl 'https://collection.id/api/v1/collection/cert-status' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN"

TypeScript SDK

await collector.getCertStatus({ query: { … } });

GET/api/v1/collection/items/{id}/cert-check

A copy’s certificate check

Signed in

The saved result of checking the copy’s slab certificate against the grader’s record, and the record from the shared cache. Never calls the grader.

SDK: collector.getCopyCertCheck()
Key scopes: collection:read(API keys are coming soon)
Headers: If-None-MatchX-Request-Id

Parameters

Name	In	Type	About
`id`required	path	string (uuid)

Responses

200The check (outcome is null).
object
- checkobject or nullrequired
  The saved result; null when the copy hasn’t been checked.
  Fields of check
  resultenumrequired
  One ofverifiedmismatchnot_found
  mismatchesarray of enumrequired
  One oftitleissueyearpublishergradelabelpage_quality
  checked_atstring (date-time)required
  record_fetched_atstring (date-time) or nullrequired
  companyenumrequired
  One ofcgccbcspsapgxegshgaother
  cert_numberstringrequired
  issue_idstring (uuid)required
  gradenumber or nullrequired
  label_typestring or nullrequired
  page_qualitystring or nullrequired
- recordCertRecord or nullrequired
  The grader’s record from the shared cache.
- lookupobjectrequired
  Fields of lookup
  availablebooleanrequired
  reasonenum or nullrequired
  One ofunsupporteddisabled
  messagestring or nullrequired
- outcomeobject or object or nullrequired
  What a POST did; null for GET.
  Fields of outcome
  Option 1: object
  statusenumrequired
  One ofcheckedno_certgone
  Option 2: object
  status"unavailable"required
  reasonenumrequired
  One ofunsupporteddisabledbudgeterror
  messagestringrequired
304Not modified: your copy (the ETag in If-None-Match) is current.

Errors (401, 404, 500)

401unauthorized
unauthorized: Not signed in (no session or token, or an expired one).
404not_found
not_found: Nothing at that address.
500internal
internal: Something went wrong on our side (quote the requestId).

curl

curl 'https://collection.id/api/v1/collection/items/<id>/cert-check' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN"

TypeScript SDK

await collector.getCopyCertCheck({ path: { id } });

POST/api/v1/collection/items/{id}/cert-check

Check a copy’s certificate now

Signed in

Checks the copy’s cert against the grader’s record (“Verify with PSA”): from the shared cache while it’s fresh, unless refresh: true. The body is optional. 60 an hour.

SDK: collector.checkCopyCert()
Key scopes: collection:write(API keys are coming soon)
Headers: X-Request-Id

Parameters

Name	In	Type	About
`id`required	path	string (uuid)

Request body (optional, application/json)

object

refreshbooleanoptional
Ask the grader even if the cache is fresh.

Responses

200The check, and what this request did.
object
- checkobject or nullrequired
  The saved result; null when the copy hasn’t been checked.
  Fields of check
  resultenumrequired
  One ofverifiedmismatchnot_found
  mismatchesarray of enumrequired
  One oftitleissueyearpublishergradelabelpage_quality
  checked_atstring (date-time)required
  record_fetched_atstring (date-time) or nullrequired
  companyenumrequired
  One ofcgccbcspsapgxegshgaother
  cert_numberstringrequired
  issue_idstring (uuid)required
  gradenumber or nullrequired
  label_typestring or nullrequired
  page_qualitystring or nullrequired
- recordCertRecord or nullrequired
  The grader’s record from the shared cache.
- lookupobjectrequired
  Fields of lookup
  availablebooleanrequired
  reasonenum or nullrequired
  One ofunsupporteddisabled
  messagestring or nullrequired
- outcomeobject or object or nullrequired
  What a POST did; null for GET.
  Fields of outcome
  Option 1: object
  statusenumrequired
  One ofcheckedno_certgone
  Option 2: object
  status"unavailable"required
  reasonenumrequired
  One ofunsupporteddisabledbudgeterror
  messagestringrequired

Errors (400, 401, 404, 429, 500)

400invalid_request invalid_json
invalid_request: The query or body doesn’t match the schema (see errors[]).
invalid_json: The body isn’t JSON.
401unauthorized
unauthorized: Not signed in (no session or token, or an expired one).
404not_found
not_found: Nothing at that address.
429rate_limited
rate_limited: More than 60 checks an hour; wait the Retry-After seconds.
500internal
internal: Something went wrong on our side (quote the requestId).

curl

curl -X POST 'https://collection.id/api/v1/collection/items/<id>/cert-check' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN" \
  -H 'Content-Type: application/json' \
  -d @body.json

TypeScript SDK

await collector.checkCopyCert({ path: { id }, body: { … } });