Parties

A party is a person or an organisation under a client that owns entities through ownerships. A party sits above the entities it owns: a grant on an entity, a custody account or a cash account does not show its owners, a grant on a party shows that party, and a grant on the client shows the client's parties.

Data model

idstring: Stable identifier for the party. A UUID — treat it as opaque.
external_reference_idstring or null: Your own reference for the party, unique in the tenant. A party made through this API without one gets api: followed by a UUID.
client_idstring: The client the party belongs to.
namestring: The person's or organisation's name.
kindstring: person or organisation. Set at creation.
country_codestring or null: ISO 3166-1 alpha-2 country.
tax_residency_country_codestring or null: ISO 3166-1 alpha-2 country of tax residency.
created_atstring: When the party was recorded, UTC to the second.
originstring: legacy for a party mirrored from the legacy platform, v1 for one made through this API.

Reads need structure:read or access:read; writes need structure:write or access:write. Every write on this page takes ?dry_run=true and an Idempotency-Key header and is logged in the change list. A party that comes from the legacy platform answers 409 legacy_managed until your move to v1 is done. An unknown body field is 400. A party you cannot see answers 404, like one that doesn't exist. A refusal comes in this order: 400 for the body, then 404, then 403, then 409.

GET/v1/parties

List parties

Every party you can see, by name, in the standard v1 list envelope. An unknown query parameter is a 400.

Query parameters

limitinteger: Page size. Defaults to 100, at least 1, capped at 1 000.
cursorstring: Opaque cursor from the previous page's next_cursor. A cursor that does not decode is 400.

Request

GET/v1/parties

curl https://api.aleta.ai/v1/parties \
  -H "Authorization: Bearer {access_token}"

POST/v1/parties

Create a party

Creates a party under a client you can see; a client you cannot see is 404. It takes a grant that covers the client whole — the tenant, the client or a client above it that includes its sub-clients, or, for an advisor, a current assignment to the client — and is not read-only: a grant on one of its entities, custody accounts or cash accounts, or an auditor's or lens viewer's grant, is 403. Admins and Aleta create everywhere. Returns 201 with the party.

Body parameters

client_idstring: The client the party belongs to. Required.
namestring: Required, not blank.
kindstring: person or organisation. Required.
external_reference_idstring: Your own reference, unique in the tenant: one another party has is 409 external_reference_taken. It may not end in :party or :container (400), which the legacy mirror uses. Left out, the party gets api: followed by a UUID.
country_codestring: Two letters A-Z.
tax_residency_country_codestring: Two letters A-Z.

Request

POST/v1/parties

curl -X POST https://api.aleta.ai/v1/parties \
  -H "Authorization: Bearer {access_token}" \
  -H "Idempotency-Key: {unique_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "019dfeb0-0511-77a7-a8be-a911ab988a0a",
    "name": "Anna Hansen",
    "kind": "person",
    "external_reference_id": "crm-4411",
    "country_code": "DK"
  }'

GET/v1/parties/{id}

Retrieve a party

One party by id. 404 when it doesn't exist or you cannot see it.

Request

GET/v1/parties/{id}

curl https://api.aleta.ai/v1/parties/019eb3d2-fc2e-7782-973e-af78d0c10f01 \
  -H "Authorization: Bearer {access_token}"

PATCH/v1/parties/{id}

Update a party

Changes a party's name, country or tax residency. A body with none of the three is 400. It takes a grant that covers the party's client whole, as a create does: a grant on the party itself, or an auditor's or lens viewer's grant, is 403. On top of that, only an admin or Aleta changes the name or the tax residency (403 for anyone else). The kind never changes. A change is logged with its reason; a PATCH that changes nothing is not logged. Returns 200 with the party.

Body parameters

namestring: New name, not blank.
country_codestring: Two letters A-Z.
tax_residency_country_codestring: Two letters A-Z.
reasonstring: Why. Required, not blank.

Request

PATCH/v1/parties/{id}

curl -X PATCH https://api.aleta.ai/v1/parties/019eb3d2-fc2e-7782-973e-af78d0c10f01 \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{ "tax_residency_country_code": "SE", "reason": "moved to Sweden" }'

DELETE/v1/parties/{id}

Delete a party

Removes a party nothing refers to. Returns 204, 404 if you cannot see it. It takes a grant that covers the party's client whole, as a create does (403 otherwise). Sent again with the same Idempotency-Key after the party is gone, it answers the first 204 again.

A party that has ever owned an entity, or has any access grant or document, is not deleted: the answer is 409 in_use, its detail names what uses it (Party {id} is used by ownerships, access grants and documents.), and next_action points at the first thing that still blocks it, in this order: an ownership that has not ended (end_date, PATCH /v1/ownerships/{id} with valid_to), a grant that is neither revoked nor expired (archive, DELETE /v1/access-grants/{id}), a document not archived (archive, DELETE /v1/documents/{id}). An ownership that has ended, a revoked or expired grant, or an archived document still keeps the party, with next_action null.

The change list keeps no personal data of a deleted party: only its id, kind and client_id.

Request

DELETE/v1/parties/{id}

curl -X DELETE https://api.aleta.ai/v1/parties/019eb3d2-fc2e-7782-973e-af78d0c10f01 \
  -H "Authorization: Bearer {access_token}"

Entities — what parties own, and the ownerships.
Clients — the client a party belongs to.

Parties

Data model

List parties

Query parameters

Create a party

Body parameters

Retrieve a party

Update a party

Body parameters

Delete a party

Related