PATCH/v1/cards/{card_id}

Update a card

update_card

Authentication

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

Path parameters

card_idstringrequired

Header parameters

Idempotency-Keystring
Key for a safe retry of a write: 1 to 255 printable ASCII characters; a UUID v4 per logical operation is recommended. A retry with the same key within 24 hours does not run the operation again: it returns the saved response (status, headers and body) with the Idempotency-Replayed: true header. The same key with a different method, path, Content-Type or body returns 409 api.idempotency_mismatch; while the first request is still running, 409 api.idempotency_in_progress with Retry-After: 1. After a 5xx or 429 response the key is released, and a retry runs the operation again. The key is scoped to the organization and the caller (API key, user, or custom source key).
length ≥ 1, length ≤ 255
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.

Request body

application/json

Object: CardUpdate

external_idstring | null
Sets or changes the external_id of the card; "" or null removes it. If another card of the organization uses it, the request returns 409 cards.external_id_taken. The external_id of a source card does not change (409 cards.managed_by_source).
length ≤ 512
metadataMetadataPatch
titlestring | null
owner_idinteger | null
verifier_idsarray of integer | null
verify_interval_daysinteger | null
≥ 1, ≤ 3650
tagsarray of string | null
statusstring | null
source_urlstring | null
categorystring | null
sensitiveboolean | null
table_categoriesmap of object | null

Responses

200OK

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.
Idempotency-Replayed
true means the response was replayed from the saved one for this Idempotency-Key: the operation did not run again.

application/json

Object: 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.

Safe retries

Send an Idempotency-Key header (for example a UUID) with each POST and PATCH. A retry with the same key within 24 hours returns the saved response instead of running the request again.

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

curl -X PATCH 'https://api.sursa.com/v1/cards/CARD_ID' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"external_id":"crm-1042","metadata":{"key":"string"},"title":"Refund policy"}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

Try it

API key

The key stays in the memory of this tab and is sent only to https://api.sursa.com.

Requests act on the real data of your organization.

Idempotency-Key header

X-View-As header

card_id path *

Idempotency-Key

A new key is generated for each request when this is empty.

Request body (JSON)