Atfinity API reference¶
Work with cases, instances, values, proofs and documents from your own systems.
Generated from the code. Do not edit these pages by hand: change the @public_api annotation on
the endpoint and regenerate.
Authentication¶
Every request needs an API key in the Authorization header:
See Generate API Keys.
Trace a request¶
Info
New in Atfinity 17.
Every response carries an X-Request-ID header, and the log lines of that request carry the same id.
Send your own id in an X-Request-ID request header to have Atfinity use it instead.
See Security Logging.
Run the requests¶
Download the Postman collection
and set the base_url and api_key collection variables. Every endpoint below is in it.
For any other client, take the OpenAPI spec these pages are built from.
List parameters¶
Every endpoint that returns a list accepts these query parameters, so they are not repeated per endpoint:
page(integer) - which page to return, starting at 1page_size(integer) - results per page, 10 by default. The cap depends on the endpoint, see belowordering(string) - field to sort by, prefix with-to reversesearch(string) - free text search over the searchable fields
A page past the last one returns the last page instead of an error, and a page below 1 returns the first page.
Endpoints that answer with results accept a page_size up to 1000, and -1 for the maximum;
anything outside that is rejected. Endpoints that answer with data accept up to 200 and quietly
reduce anything larger to it.
List responses carry the page itself next to the pagination:
The key holding the page is results on most endpoints and data on the case list, the case
history and the instance list. The schema of each operation below says which one it is.
Delay the recalculation¶
Info
New in Atfinity 17.
A request that changes a case runs the rule engine before it answers, so the response is the
recalculated case. Add keep_dirty=true to the query string to skip that run: the change is saved,
the case is marked dirty, and the response is the case as it stands, before the rules have seen the
change.
Send a batch of changes that way and the case is recalculated once, by the next operation that leaves the flag off. Every operation that takes the flag lists it among its query parameters, and the rest run the rules as they always have. A case created with the flag has not had its creation rules run yet, so the instances they build do not exist until the case is recalculated, and creating a case that is transitioned at the same time is refused, because the transition decides the outcome of the case from values the rules have not calculated. A case left dirty is not reindexed either; the recalculation that ends the batch indexes it once.
Reading the case back with GET /api/1/cases/{id} recalculates it. The other reads do not: the
value list, the booklets and the history serve what is stored, so they answer from before the rules
saw the batch.
Operations that never run the rule engine have nothing to postpone and take no flag: deleting a case, setting its tags, unassigning a proof, the booklets, and the operations on an instance outside a case. Transitioning a case always runs it, because the transition's condition is evaluated against the rules' own output, and so does starting a wizard, whose run is bound to the step the wizard opens on.
Skip the case response¶
Info
New in Atfinity 17.
Most operations on a case answer with the whole case, which is the larger part of the work for a
request that writes a single value. Add skip_case_response=true to the query string and the answer
is the case id alone, in the same data envelope, or the bare id for a request that asks for
text/plain.
An operation that creates something keeps reporting it beside the case id, so a batch can start with
a create and keep the new id: created_instance_id when adding an instance, created_proof_id when
uploading a proof, created_comment_id when commenting, and trigger_object when adding or
duplicating a structure occurrence. Creating a case and copying one answer with the new case as the
case id itself. Each of those also sets a Location header naming what it created, whether or not
the body is skipped.
It combines with keep_dirty and is worth having without it. A client writing a batch sends both on
every write, and GET /api/1/cases/{id}?skip_case_response=true then recalculates the case once
without paying to serialise it.
Sections¶
- Cases - 13 operations. Create cases, read their data, move them through their workflow and delete them.
- Values - 6 operations. Information values are the answers stored in a case. Each value belongs to an instance and to an information field identified by its key. A structured information holds its values in occurrences, which repeat the same set of fields.
- Instances - 15 operations. Instances are the people, companies and objects a case is about. They live outside the case and can be shared between cases.
- Proofs - 7 operations. Proofs are the files a case collects, for example an ID scan or a utility bill.
- Documents and booklets - 10 operations. Documents are generated from the case data. A booklet bundles several documents into one PDF.
- Wizards - 2 operations. Wizards are the forms an end user fills in outside the Case Manager. Another system can start one and hand the person the link to it.
- Meta - 1 operation.