Sign in
Documents

List documents

Changed on

The company's paperwork, oldest first, paged on a cursor.

Both kinds of document. party is employee for a document about one of your people and counterparty for one a counterparty signs. Filter with party=employee or party=counterparty; leave it out for both.

signature.state is derived, because there is no column for it. none when nobody has to sign, then rejected, revoked, pending in that order of precedence, and signed only when every signer has. Refusal outranks an outstanding signature, so a document one person refused reads rejected even while others are still pending. completed_at is set only for signed, and is when the last signer signed.

Dates are three shapes in one payload. start_date, end_date and expiration_date are plain YYYY-MM-DD — they are date columns and carry no time or zone. created_at is an instant with an offset.

expires_after and expires_before are a plain range of dates.

effective_from and effective_to select documents valid during a window: a document starts on or before your effective_to and either has no end date or ends on or after your effective_from. Both are required together. A document with no start_date never matches — a row with no interval cannot overlap one.

locations, departments, positions and user_filters all reach the document through the person it is about, so a document with no user_id matches none of them. The web app files company-level documents that way.

updated_since reads only what changed, as an instant rather than a date so a caller polling every few minutes can say which minute. Two things it will not show you, and both are ours rather than yours: a document changed by a path inside the product that writes the row directly keeps its old timestamp, and so does one the back office modifies. Signature progress is the common case of the second — a signature completed through the web app does not move updated_at. Re-read with overlap if you depend on catching those.

Documents the product files for its own machinery are never listed.

get/company/v3/documents

Request

  • Base URL: https://api.clockster.com
  • URL: https://api.clockster.com/company/v3/documents
  • Auth: HTTP bearer

Query parameters

per_pageinteger

How many rows one page holds. Defaults to 50.

cursorstring nullable

The meta.next_cursor of the previous page. Omit it for the first. A cursor is bound to the filters it was issued under — change them and start again.

party'employee' | 'counterparty' nullable

Whose side of the document to read.

external_idsstring[] nullable

Only rows carrying these keys of yours. The other half of an upsert: write with your key, read back with it.

usersinteger[] nullable

Only rows belonging to these people, by id.

locationsinteger[] nullable

Only these locations, by id.

departmentsinteger[] nullable

Only these departments, by id.

positionsinteger[] nullable

Only these positions, by id.

user_filtersinteger[] nullable

Only these user filters, by id.

typesstring[] nullable

Only rows of these types.

employment_typesstring[] nullable

Only documents covering these employment terms.

searchstring nullable

Free text over the names the section lists.

updated_sincestring date-time nullable

Only rows changed at or after this instant (ISO 8601). The cheap way to sync: ask for what moved, not for everything.

expires_afterstring date nullable

Expiring after this date (YYYY-MM-DD) — how you find what is about to lapse.

expires_beforestring date nullable

Expiring before this date (YYYY-MM-DD).

effective_fromstring date nullable

In force at or after this date (YYYY-MM-DD).

effective_tostring date nullable

In force at or before this date (YYYY-MM-DD).

includestring[] nullable

Relations to load, comma-separated. Anything not named is absent from the answer rather than null.

Response

Success

Changes

  • v396f948c66816Revision changes
    • info

      the endpoint scheme security companyToken was added to the API

    • info

      for the query request parameter types, the maxItems was increased from 32 to 49

    • info

      added the enum value asp_certificate to the property items/ of the query request parameter types

    • info

      added the enum value attorney to the property items/ of the query request parameter types

    • info

      added the enum value disability_certificate to the property items/ of the query request parameter types

    • info

      added the enum value hunter to the property items/ of the query request parameter types

    • info

      added the enum value insurance_policy to the property items/ of the query request parameter types

    • info

      added the enum value large_family_certificate to the property items/ of the query request parameter types

    • info

      added the enum value lbg_card to the property items/ of the query request parameter types

    • info

      added the enum value oralman to the property items/ of the query request parameter types

    • info

      added the enum value pcr_certificate to the property items/ of the query request parameter types

    • info

      added the enum value pension to the property items/ of the query request parameter types

    • info

      added the enum value rk_passport to the property items/ of the query request parameter types

    • info

      added the enum value social_id to the property items/ of the query request parameter types

    • info

      added the enum value srts to the property items/ of the query request parameter types

    • info

      added the enum value student_card to the property items/ of the query request parameter types

    • info

      added the enum value tech_passport to the property items/ of the query request parameter types

    • info

      added the enum value vaccination to the property items/ of the query request parameter types

    • info

      added the enum value vnzh to the property items/ of the query request parameter types

  • v30b1170aa3044Revision changes
    • info

      for the query request parameter types, the maxItems was increased from 27 to 32

    • info

      added the enum value birth_certificate to the property items/ of the query request parameter types

    • info

      added the enum value change_fio_certificate to the property items/ of the query request parameter types

    • info

      added the enum value divorce_certificate to the property items/ of the query request parameter types

    • info

      added the enum value driver_license to the property items/ of the query request parameter types

    • info

      added the enum value marriage_certificate to the property items/ of the query request parameter types