Instances¶

Instances are the people, companies and objects a case is about. They live outside the case and can be shared between cases.

Add an instance to a case¶

POST /api/1/cases/{case_pk}/instances

Creates an instance of the given ontology inside the case. Identify the ontology by ontology_id or by ontology_key. fields sets initial values, keyed by information key.

Request body

fields (object)
ontology_id (integer)
ontology_key (string)

Send at least one of ontology_id, ontology_key.

{
  "fields": {
    "first_name": "Jane",
    "last_name": "Doe"
  },
  "ontology_key": "Person"
}

Example

curl -X POST \
  -H "Authorization: Api-Key $ATFINITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fields": {"first_name": "Jane", "last_name": "Doe"}, "ontology_key": "Person"}' \
  https://your-tenant.atfinity.app/api/1/cases/<case_pk>/instances

Response 201

The case. The listed properties are the stable ones. The payload also carries the fields the Atfinity frontend needs, which are not part of this contract and can change.

calculated_name (string, nullable)
color (string)
created (string, date-time)
given_name (string, nullable)
id (integer)
is_created (boolean)
is_dirty (boolean)
is_editable (boolean)
last_modified (string, date-time)
last_transition_at (string, date-time)
name (string)
outcome_instance_id (integer, nullable)
preferred_language (string, nullable)
state_id (integer, nullable)
state_key (string, nullable)
status (string)
use_given_name (boolean)
user_readable_id (string)

Further fields are present but are not part of this contract.

Remove an instance from a case¶

DELETE /api/1/cases/{case_pk}/instances/{id}

A draft instance is deleted. An instance that exists outside the case keeps existing: it is unlinked from the case and its values in that case are removed. Refused for managed ontologies.

Example

curl -X DELETE \
  -H "Authorization: Api-Key $ATFINITY_API_KEY" \
  https://your-tenant.atfinity.app/api/1/cases/<case_pk>/instances/<id>

Response 200

The case. The listed properties are the stable ones. The payload also carries the fields the Atfinity frontend needs, which are not part of this contract and can change.

calculated_name (string, nullable)
color (string)
created (string, date-time)
given_name (string, nullable)
id (integer)
is_created (boolean)
is_dirty (boolean)
is_editable (boolean)
last_modified (string, date-time)
last_transition_at (string, date-time)
name (string)
outcome_instance_id (integer, nullable)
preferred_language (string, nullable)
state_id (integer, nullable)
state_key (string, nullable)
status (string)
use_given_name (boolean)
user_readable_id (string)

Further fields are present but are not part of this contract.

Unlink a case instance¶

DELETE /api/1/cases/{case_pk}/instances/{id}/link

Gives the case its own copy of the instance again, so later changes stay inside this case.

Example

curl -X DELETE \
  -H "Authorization: Api-Key $ATFINITY_API_KEY" \
  https://your-tenant.atfinity.app/api/1/cases/<case_pk>/instances/<id>/link

Response 204

Link a case instance to a shared instance¶

POST /api/1/cases/{case_pk}/instances/{id}/link

Replaces the instance in the case with new_instance_id, so the case points at an instance that is shared with other cases. Refused when the instance does not allow link changes.

Request body

new_instance_id (integer)

{
  "new_instance_id": 5001
}

Example

curl -X POST \
  -H "Authorization: Api-Key $ATFINITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"new_instance_id": 5001}' \
  https://your-tenant.atfinity.app/api/1/cases/<case_pk>/instances/<id>/link

Response 200

The case. The listed properties are the stable ones. The payload also carries the fields the Atfinity frontend needs, which are not part of this contract and can change.

calculated_name (string, nullable)
color (string)
created (string, date-time)
given_name (string, nullable)
id (integer)
is_created (boolean)
is_dirty (boolean)
is_editable (boolean)
last_modified (string, date-time)
last_transition_at (string, date-time)
name (string)
outcome_instance_id (integer, nullable)
preferred_language (string, nullable)
state_id (integer, nullable)
state_key (string, nullable)
status (string)
use_given_name (boolean)
user_readable_id (string)

Further fields are present but are not part of this contract.

Give an instance a role in a case¶

POST /api/1/cases/{case_pk}/instances/{instance_pk}/roles

Identify the role by role_id or by role_key. The role has to be one the instance's ontology can hold.

Request body

role_id (integer)
role_key (string)

Send at least one of role_id, role_key.

{
  "role_key": "AccountHolder"
}

Example

curl -X POST \
  -H "Authorization: Api-Key $ATFINITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"role_key": "AccountHolder"}' \
  https://your-tenant.atfinity.app/api/1/cases/<case_pk>/instances/<instance_pk>/roles

Response 201

The case. The listed properties are the stable ones. The payload also carries the fields the Atfinity frontend needs, which are not part of this contract and can change.

calculated_name (string, nullable)
color (string)
created (string, date-time)
given_name (string, nullable)
id (integer)
is_created (boolean)
is_dirty (boolean)
is_editable (boolean)
last_modified (string, date-time)
last_transition_at (string, date-time)
name (string)
outcome_instance_id (integer, nullable)
preferred_language (string, nullable)
state_id (integer, nullable)
state_key (string, nullable)
status (string)
use_given_name (boolean)
user_readable_id (string)

Further fields are present but are not part of this contract.

Take a role away from an instance in a case¶

DELETE /api/1/cases/{case_pk}/instances/{instance_pk}/roles/{id}

The last path segment is the role id or the role key.

Example

curl -X DELETE \
  -H "Authorization: Api-Key $ATFINITY_API_KEY" \
  https://your-tenant.atfinity.app/api/1/cases/<case_pk>/instances/<instance_pk>/roles/<id>

Response 200

The case. The listed properties are the stable ones. The payload also carries the fields the Atfinity frontend needs, which are not part of this contract and can change.

calculated_name (string, nullable)
color (string)
created (string, date-time)
given_name (string, nullable)
id (integer)
is_created (boolean)
is_dirty (boolean)
is_editable (boolean)
last_modified (string, date-time)
last_transition_at (string, date-time)
name (string)
outcome_instance_id (integer, nullable)
preferred_language (string, nullable)
state_id (integer, nullable)
state_key (string, nullable)
status (string)
use_given_name (boolean)
user_readable_id (string)

Further fields are present but are not part of this contract.

List instances of an ontology¶

GET /api/1/instances-for-ontology-{ontology_id}

Example

curl -X GET \
  -H "Authorization: Api-Key $ATFINITY_API_KEY" \
  https://your-tenant.atfinity.app/api/1/instances-for-ontology-<ontology_id>

Response 200

One page of instances of the ontology, with the instance page columns.

data (array)
- id (integer)
- locked (boolean)
- name (string)
- ontology_id (integer)
- owner_id (integer, nullable)
- status (string)
- user_readable_id (string)
meta (object)
- pagination (object)

Create an instance outside a case¶

POST /api/1/instances/force_create

Creates a valid instance directly, without going through a case. Identify the ontology by ontology_id or ontology_key; fields sets values keyed by information key. Refused for ontologies whose instances are managed.

Request body

fields (object)
name (string)
ontology_id (integer)
ontology_key (string)

{
  "fields": {
    "first_name": "Jane",
    "last_name": "Doe"
  },
  "name": "Jane Doe",
  "ontology_key": "Person"
}

Example

curl -X POST \
  -H "Authorization: Api-Key $ATFINITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fields": {"first_name": "Jane", "last_name": "Doe"}, "name": "Jane Doe", "ontology_key": "Person"}' \
  https://your-tenant.atfinity.app/api/1/instances/force_create

Response 200

The instance. The listed properties are the stable ones. The payload also carries the fields the Atfinity frontend needs, which are not part of this contract and can change.

id (integer)
locked (boolean)
name (string)
ontology_id (integer)
owner_id (integer, nullable)
status (string)
user_readable_id (string)

Further fields are present but are not part of this contract.

Delete an instance¶

DELETE /api/1/instances/{id}

Deletes the instance itself, wherever it is used. Every lifecycle case whose outcome this instance is goes with it, and it is removed from the cases that merely link it. To take an instance out of a single case without deleting it, use the case's own instance endpoint.

Example

curl -X DELETE \
  -H "Authorization: Api-Key $ATFINITY_API_KEY" \
  https://your-tenant.atfinity.app/api/1/instances/<id>

Response 204

The instance and the cases it is the outcome of are deleted.

Get an instance¶

GET /api/1/instances/{id}

Example

curl -X GET \
  -H "Authorization: Api-Key $ATFINITY_API_KEY" \
  https://your-tenant.atfinity.app/api/1/instances/<id>

Response 200

The instance. The listed properties are the stable ones. The payload also carries the fields the Atfinity frontend needs, which are not part of this contract and can change.

id (integer)
locked (boolean)
name (string)
ontology_id (integer)
owner_id (integer, nullable)
status (string)
user_readable_id (string)

Further fields are present but are not part of this contract.

Update an instance¶

PATCH /api/1/instances/{id}

Request body

locked (boolean)
owner_email (string, email)
owner_id (integer)

Example

curl -X PATCH \
  -H "Authorization: Api-Key $ATFINITY_API_KEY" \
  https://your-tenant.atfinity.app/api/1/instances/<id>

Response 200

The instance. The listed properties are the stable ones. The payload also carries the fields the Atfinity frontend needs, which are not part of this contract and can change.

id (integer)
locked (boolean)
name (string)
ontology_id (integer)
owner_id (integer, nullable)
status (string)
user_readable_id (string)

Further fields are present but are not part of this contract.

Count the cases an instance is used in¶

GET /api/1/instances/{id}/case_count

Example

curl -X GET \
  -H "Authorization: Api-Key $ATFINITY_API_KEY" \
  https://your-tenant.atfinity.app/api/1/instances/<id>/case_count

Response 200

How many cases use the instance, split by how they use it.

data (object)
- linked_finished_case_count (integer)
- linked_ongoing_case_count (integer)
- outcome_case_count (integer)

Update the values of an instance¶

PATCH /api/1/instances/{id}/force_update

Writes information values on the instance itself, keyed by information key, without going through a case. Ongoing cases that use the instance are warned about the change. Pass reindex=false while importing many instances, then reindex once at the end.

reindex (string) - Set to false to skip reindexing this instance, then reindex once after a bulk import.

Request body

fields (object)
name (string)

{
  "fields": {
    "first_name": "Jane",
    "risk_score": 42
  }
}

Example

curl -X PATCH \
  -H "Authorization: Api-Key $ATFINITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fields": {"first_name": "Jane", "risk_score": 42}}' \
  https://your-tenant.atfinity.app/api/1/instances/<id>/force_update

Response 200

The instance. The listed properties are the stable ones. The payload also carries the fields the Atfinity frontend needs, which are not part of this contract and can change.

id (integer)
locked (boolean)
name (string)
ontology_id (integer)
owner_id (integer, nullable)
status (string)
user_readable_id (string)

Further fields are present but are not part of this contract.

List the value change history of an instance¶

GET /api/1/instances/{instance_pk}/history

_created (string)
_created_by_includes (string)
_created_by_starts (string)
_updated (string)
_updated_by_includes (string)
_updated_by_starts (string)
changed_by (integer)
manual_instance_action_key (string)
reason (string, one of API, CASE, CONFIGURATION_CHANGE, EXCEL_IMPORT, INTERACTION_LOG_ADDED, INTERACTION_LOG_DELETED, INTERACTION_LOG_EDITED, MANUAL_INSTANCE_ACTION, SCHEDULED_RULE)
source_key (string)

Accepts the standard list parameters.

Example

curl -X GET \
  -H "Authorization: Api-Key $ATFINITY_API_KEY" \
  https://your-tenant.atfinity.app/api/1/instances/<instance_pk>/history

Response 200

meta (object)
- pagination (object)
results (array)
- case_reference (integer, nullable)
- changed_by (string, required)
- id (integer, required)
- manual_instance_action_title (string, required)
- new_value (string, required)
- old_value (string, required)
- reason (string, required)
- source_name (string, required)
- timestamp (string, date-time, required)