Skip to content
Sursa Developers

GET/v1/cards

List cards

list_cards

Returns cards with filters, sorting and pagination. With preview=1 (for the tile view), each card also has preview (the first 200 characters of text) and preview_tables (sheets with their row counts), within your data profile.

Authentication

Send an API key in the Authorization header: Authorization: Bearer <key>.

Query parameters

  • collectionstring | null
  • folderstring | null

    <folder ID> returns the cards of the folder and all its subfolders. none returns the cards of the collection that are not in any folder and requires collection (otherwise 400 cards.invalid_folder_filter). If the folder does not exist or is not visible to you, the request returns 404 folders.not_found.

    length ≤ 64

  • statusstring | null

    Allowed values: processingreadyerrorarchivedall

  • ownerstring | null

    me, none or a user ID.

  • owner_idinteger | null
  • verificationstring | null

    Allowed values: verifiedneeds_verificationstale

  • kindCardKind
  • typestring | null

    table returns cards with fact tables, text returns cards without them.

    Allowed values: tabletext

  • tagsstring | null

    Comma-separated tags (a card must have all of them).

  • idsstring | null

    Comma-separated card IDs.

  • searchstring | null
  • categorystring | null
  • sensitiveboolean | null
  • sortCardSort

    Default: "created_at"

  • orderstring

    Allowed values: ascdesc

    Default: "desc"

  • limitinteger

    Default: 200

  • offsetinteger

    Default: 0

  • previewboolean

    true adds preview (the first 200 characters) and preview_tables for the tile view.

    Default: false

  • updated_sincestring (date-time)

    Only cards with updated_at at or after this moment (RFC 3339 with an offset), for synchronization. Without explicit sort and order, the list is sorted by updated_at ascending, then by id. Deleted cards are not listed: deletions come as events.

  • metadatamap of string

    Filter by metadata: metadata[<key>]=<value> matches exactly. Up to 3 conditions, and all of them must match (?metadata[team]=support&metadata[crm_id]=A-1042). More than 3 conditions or an invalid key returns 400 api.metadata_invalid.

  • collection_idinteger

    Collection by ID. When collection is passed too, collection_id wins. A collection that does not exist in the organization or is not visible returns 404 collections.not_found.

  • external_idstring

    Only the card with this external_id.

  • cursorstring

    Cursor of the next page from X-Next-Cursor or next_cursor of the previous response with the same filters; it carries the page size. Together with offset: 422 validation.failed; a cursor of another list, other filters or a malformed one: 400 api.cursor_invalid.

    length ≤ 512

  • expand[]array of string

    Related objects to include in the response (since 1.62.0): a path from the x-expandable list of the operation. Repeat the parameter up to 10 times. A path has up to 2 segments separated by a dot (collection.default_owner). In a list, the path starts with data. and applies to every item of the page (expand[]=data.owner). An expanded object goes into the expanded object of the item, and the ID field stays. An object that the caller may not see under the checks of its own read operation is expanded as null. An unknown path, more than 10 paths or a path deeper than 2 segments returns 400 api.expand_invalid.

    items ≤ 10

Header parameters

  • X-View-Asstring

    For API keys with the admin role only. Makes the request as the data profile <profile>[:viewer|verifier|editor], for example employee:viewer. The installation key cannot use this header (403).

Cookie parameters

  • kb_view_asstring

    Cookie of the “View as” mode for a session. POST /auth/view-as sets it and DELETE /auth/view-as clears it.

Responses

200OK

Response headers

  • Link

    Address of the next page, <…>; rel="next". No header means this is the last page.

  • X-Next-Cursor

    Cursor of the next page for the cursor parameter. No header means this is the last page.

  • RateLimit-Policy

    Limits in effect, in the format of the IETF draft draft-ietf-httpapi-ratelimit-headers: comma-separated items "<name>";q=<quota>;w=<window in seconds>. key is the request rate of the API key (the quota is the burst, the window is the time to refill it fully; for a session it is user, without credentials ip); minute, day and month are the organization's quotas for the calendar minute, day and month in UTC.

  • RateLimit

    What is left of each limit in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit of the strictest entry in RateLimit-Policy (the one with the fewest requests left).

  • X-RateLimit-Remaining

    Requests left under the strictest limit.

  • X-RateLimit-Reset

    Seconds until the strictest limit resets.

application/json

Object: CardList

array of Card
  • expandedCardExpanded
  • permissionsObjectPermissionList
  • accessstring

    Allowed values: wholepartial

  • access_contactstring

    Whom to contact for access (only when access=partial).

  • aclobject
    Fields
    • verifybooleanrequired
    • writebooleanrequired
  • categorystringrequired
  • category_confidencenumber | nullrequired
  • category_lockedbooleanrequired
  • category_reviewbooleanrequired
  • category_sourceCategorySource | nullrequired
  • collectionstringrequired
  • collection_idintegerrequired
  • collection_titlestring
  • commentsarray of CardComment
  • content_jsonContentJSON | null

    Editor content of the latest published version. The field can be absent; in that case, get the editor content from a draft (POST /v1/drafts with card_id).

  • editing_lockEditingLock | null

    Active editing lock. The field can be absent; in that case, the editor learns who holds the lock from 409 cards.locked on POST /v1/cards/{card_id}/lock.

  • created_atstring (date-time)required
  • days_since_verifiedintegerrequired
  • errorstring | nullrequired
  • eventsarray of CardEvent
  • feedback_negintegerrequired
  • feedback_posintegerrequired
  • foldersarray of CardFolderRef

    Card list only: the folders that contain the card (those visible to the user), with their paths from the collection root. An empty list means the card is not in any folder.

  • has_tablesboolean

    Card list only.

  • hidden_partsboolean
  • idstringrequired
  • jobJob | null
  • kindCardKindrequired
  • org_idintegerrequired
  • owner_activeboolean | null
  • owner_idinteger | nullrequired
  • owner_namestring | nullrequired
  • pagesinteger | nullrequired
  • parserstring | nullrequired

    Document parser as a neutral code: document (full structure: pages, headings, tables, scanned pages), pdf (the PDF text layer), docx, xlsx, csv, markdown, html, text. The list can grow.

  • partsarray of CardPartrequired
  • sensitivebooleanrequired
  • sha256string | nullrequired
  • sizeintegerrequired
  • snoozed_atstring (date-time) | null
  • snoozed_byinteger | null
  • snoozed_untilstring | null
  • source_changedbooleanrequired
  • source_pathstring | nullrequired
  • source_urlstring | nullrequired
  • statusstringrequired

    Allowed values: processingreadyerrorarchived

  • tablesarray of CardTable
  • tagsarray of stringrequired
  • titlestringrequired
  • trustnumberrequired
  • trust_if_verifiednumber
  • trust_partsTrustPartsrequired
  • updated_atstring (date-time)required
  • verificationVerificationrequired
  • verified_atstring (date-time) | nullrequired
  • verified_byinteger | nullrequired
  • verified_by_namestring | null
  • verifier_idsarray of integerrequired
  • verifiersarray of object
    Fields
    • activebooleanrequired
    • idintegerrequired
    • namestringrequired
  • verify_interval_daysintegerrequired
  • versionintegerrequired
  • versionsarray of CardVersion
  • source_archiveArchiveSource
  • created_byinteger | null
  • manual_optionsobject

    Manual parsing settings (preview).

  • doc_kindDocKind | null

    Document type. null if the type is not determined (for example, for cards indexed before document types were introduced).

  • doc_kind_confidencenumber | null

    Confidence in the document type, from 0 to 1.

  • doc_kind_sourcestring | null

    What determined the type: rules (rules), a user (manual) or automatic classification. The list can grow: treat an unknown value as automatic classification.

    Allowed values: rulesmanualnull

  • invoiceDocInvoiceExtraction | null

    Fields of an invoice, credit note or receipt (only for these types, and only in the card, not in the list). null if you do not have access to the whole document, because the fields are extracted from the whole document.

  • warningsarray of ReviewWarning

    Document parsing warnings (ReviewWarning; only in the card, not in the list).

  • enrichmentCardEnrichmentStatus | null

    Enrichment status (only in the card, not in the list). The document type, invoice fields and financial records are added in the background after indexing and can be recalculated later; they appear in the card when they are ready. null means no status is available (the card was indexed without background enrichment).

  • external_idstring | null

    ID of the card in the integrator's system. It is unique in the organization among cards that do not come from sources; null means it is not set. /v1/cards-by-external-id/{external_id} reads and replaces the card by it.

    length ≤ 512

  • metadataMetadata
400The request is invalid: a parameter value or the state of the object does not allow the action (`detail` is a message).

Response headers

  • RateLimit-Policy

    Limits in effect, in the format of the IETF draft draft-ietf-httpapi-ratelimit-headers: comma-separated items "<name>";q=<quota>;w=<window in seconds>. key is the request rate of the API key (the quota is the burst, the window is the time to refill it fully; for a session it is user, without credentials ip); minute, day and month are the organization's quotas for the calendar minute, day and month in UTC.

  • RateLimit

    What is left of each limit in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit of the strictest entry in RateLimit-Policy (the one with the fewest requests left).

  • X-RateLimit-Remaining

    Requests left under the strictest limit.

  • X-RateLimit-Reset

    Seconds until the strictest limit resets.

application/json

Object: Error

401No credentials were sent (neither a session cookie nor an API key), or the key was not found.

Response headers

  • RateLimit-Policy

    Limits in effect, in the format of the IETF draft draft-ietf-httpapi-ratelimit-headers: comma-separated items "<name>";q=<quota>;w=<window in seconds>. key is the request rate of the API key (the quota is the burst, the window is the time to refill it fully; for a session it is user, without credentials ip); minute, day and month are the organization's quotas for the calendar minute, day and month in UTC.

  • RateLimit

    What is left of each limit in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit of the strictest entry in RateLimit-Policy (the one with the fewest requests left).

  • X-RateLimit-Remaining

    Requests left under the strictest limit.

  • X-RateLimit-Reset

    Seconds until the strictest limit resets.

application/json

Object: Error

403The action is not allowed: the role is insufficient, there is no access to the collection or card, the request runs in “View as” mode, or the organization is suspended or deleted (`detail` is an object with `code: org_suspended | org_deleted`).

Response headers

  • RateLimit-Policy

    Limits in effect, in the format of the IETF draft draft-ietf-httpapi-ratelimit-headers: comma-separated items "<name>";q=<quota>;w=<window in seconds>. key is the request rate of the API key (the quota is the burst, the window is the time to refill it fully; for a session it is user, without credentials ip); minute, day and month are the organization's quotas for the calendar minute, day and month in UTC.

  • RateLimit

    What is left of each limit in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit of the strictest entry in RateLimit-Policy (the one with the fewest requests left).

  • X-RateLimit-Remaining

    Requests left under the strictest limit.

  • X-RateLimit-Reset

    Seconds until the strictest limit resets.

application/json

Object: Error

404The object does not exist or is not available to you. The API does not confirm that a restricted object exists.

Response headers

  • RateLimit-Policy

    Limits in effect, in the format of the IETF draft draft-ietf-httpapi-ratelimit-headers: comma-separated items "<name>";q=<quota>;w=<window in seconds>. key is the request rate of the API key (the quota is the burst, the window is the time to refill it fully; for a session it is user, without credentials ip); minute, day and month are the organization's quotas for the calendar minute, day and month in UTC.

  • RateLimit

    What is left of each limit in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit of the strictest entry in RateLimit-Policy (the one with the fewest requests left).

  • X-RateLimit-Remaining

    Requests left under the strictest limit.

  • X-RateLimit-Reset

    Seconds until the strictest limit resets.

application/json

Object: Error

422Validation error: the body or parameters do not match the schema (`detail` is a list of validation errors), or a parameter value is out of range (`detail` is a message).

Response headers

  • RateLimit-Policy

    Limits in effect, in the format of the IETF draft draft-ietf-httpapi-ratelimit-headers: comma-separated items "<name>";q=<quota>;w=<window in seconds>. key is the request rate of the API key (the quota is the burst, the window is the time to refill it fully; for a session it is user, without credentials ip); minute, day and month are the organization's quotas for the calendar minute, day and month in UTC.

  • RateLimit

    What is left of each limit in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit of the strictest entry in RateLimit-Policy (the one with the fewest requests left).

  • X-RateLimit-Remaining

    Requests left under the strictest limit.

  • X-RateLimit-Reset

    Seconds until the strictest limit resets.

application/json

Object: Error

429Too many requests (`api.rate_limited`), the organization's quota for the minute, day or month is used up (`api.quota_exceeded`; `error.details` holds `quota`, `limit` and `reset_at`), the organization's limit is reached, or the answer service is busy (`answers.engine_busy`). Wait for the time in the `Retry-After` header.

Response headers

  • Retry-After

    Number of seconds to wait before you retry the request.

  • RateLimit-Policy

    Limits in effect, in the format of the IETF draft draft-ietf-httpapi-ratelimit-headers: comma-separated items "<name>";q=<quota>;w=<window in seconds>. key is the request rate of the API key (the quota is the burst, the window is the time to refill it fully; for a session it is user, without credentials ip); minute, day and month are the organization's quotas for the calendar minute, day and month in UTC.

  • RateLimit

    What is left of each limit in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit of the strictest entry in RateLimit-Policy (the one with the fewest requests left).

  • X-RateLimit-Remaining

    Requests left under the strictest limit.

  • X-RateLimit-Reset

    Seconds until the strictest limit resets.

application/json

Object: Error

Error codes

Codes this endpoint can return in error.code, besides the general codes of every request.

Rate limits

Responses carry the RateLimit and RateLimit-Policy headers and the earlier X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. A 429 response has Retry-After in seconds: wait and retry.

← cards · API reference