Person

Create a person

POST /{instanceName}/api/v1/{locale}/person

Creates a person and returns the full entity. 201 with a Location header.

RESTORING AN EXPORT: created/createdBy are accepted here and nowhere else — a later replace ignores them — and the identifiers of the person and of its email aliases and external ids are always newly minted.

Forespørselskropp

application/json → PersonCreateDto

Svar

Eksempel

curl -X POST "https://api.visena.example/acme/api/v1/en/person" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Kari",
    "lastName": "Nordmann",
    "primaryEmail": "kari.nordmann@example.com",
    "jobTitle": "Operations Manager"
  }'

Get a person

GET /{instanceName}/api/v1/{locale}/person/{personId}

Returns the full entity. 404 if unknown; 400 if the id cannot be unmasked.

Parametere

Svar

Eksempel

curl "https://api.visena.example/acme/api/v1/en/person/xK9mQ2" \
  -H "Authorization: Bearer $TOKEN"

List persons (offset-paginated)

GET /{instanceName}/api/v1/{locale}/person

The default collection view: offset/limit paging with a real total. Optional query (name/email/employeeNumber full-text), isActive, companyId (main relation), groupId (primary group), employeeNumber (exact, user accounts only), externalReference (exact), email (exact) filters and a created/modified/lastName sort. RFC 8288 navigation links are in the body. view selects the item projection: set view=full to receive, for every row, the same body the per-person read returns (createdBy/modifiedBy included) instead of the lean list item; allowed values are lean and full, the default is lean, and view=full caps limit at 100.

Parametere

Svar

Eksempel

curl "https://api.visena.example/acme/api/v1/en/person?offset=0&limit=20" \
  -H "Authorization: Bearer $TOKEN"

List persons (cursor-paginated, insert-stable)

GET /{instanceName}/api/v1/{locale}/person/cursor

Keyset paging over the monotonic entity id (insertion order). Pass the opaque cursor from a previous page's nextCursor/prevCursor; omit it for the first page. No total — keyset skips the count. Optional filters: query (name/email/employeeNumber full-text), isActive, companyId (main relation), groupId (primary group), employeeNumber (exact, user accounts only), externalReference (exact), email (exact, at most one match). Filters narrow the result but are not bound into the cursor. view selects the item projection: set view=full to receive, for every row, the same body the per-person read returns (createdBy/modifiedBy included) instead of the lean list item; allowed values are lean and full, the default is lean, and view=full caps limit at 100.

SYNC SEMANTICS: this is snapshot paging — a stable traversal of the persons that exist while you walk it — and not a resumable sync substrate. The entity id is allocated when a person is first written, not when that write is committed, so allocation order is not commit order: if a page is served while a lower-id person is still uncommitted, that person is never delivered to this traversal, and no later page recovers it. Walk it start to finish for a one-off extract; for ongoing synchronisation use the time-windowed list (listPersonsByTime), whose imprecision repeats rows instead of dropping them. Deleted persons never appear on any list, cursor or timeline response, and no list response reports a deletion — reconciling disappearances is the consumer's own responsibility.

Parametere

Svar

Eksempel

curl "https://api.visena.example/acme/api/v1/en/person/cursor?limit=100" \
  -H "Authorization: Bearer $TOKEN"

List persons (time-windowed, cursor-paginated)

GET /{instanceName}/api/v1/{locale}/person/timeline

Keyset paging from an optional since lower bound (open-ended upper bound) on a selectable key (created|modified). RFC 9557 Z timestamps. A cursor minted for a different key is rejected with 400. view selects the item projection: set view=full to receive, for every row, the same body the per-person read returns (createdBy/modifiedBy included) instead of the lean list item; allowed values are lean and full, the default is lean, and view=full caps limit at 100.

SYNC SEMANTICS: delivery is at-least-once. The seek timestamp is read back at millisecond precision from a column stored at microsecond precision, so a person whose key value carries sub-millisecond digits can be delivered again on the following page. The imprecision repeats rows, never omissions, so an overlapping re-scan always recovers the full window — but you must de-duplicate by person id. Resume by re-issuing the request with since set slightly behind the last value you observed; the lower bound is inclusive, which is what makes that overlap expressible. Deleted persons never appear on any list, cursor or timeline response, and no list response reports a deletion — a GDPR erasure reaches change consumers as a person update, never as a delete, so reconciling disappearances is the consumer's own responsibility.

Parametere

Svar

Eksempel

curl "https://api.visena.example/acme/api/v1/en/person/timeline?since=2026-08-20T02:00:00Z" \
  -H "Authorization: Bearer $TOKEN"

Search for potential duplicate persons

GET /{instanceName}/api/v1/{locale}/person/duplicates

Duplicate-detection probe for the create flow. Matches by full name (token-based, case-insensitive; optionally narrowed by an exact birthDate) and/or by exact email address (any of the person's addresses, case-insensitive). At least one of firstName, lastName or email is required; birthDate is only accepted together with a name. Exact email matches are listed first; results are capped by limit (default 20; values above 100 are clamped to 100).

Parametere

Svar

Eksempel

curl "https://api.visena.example/acme/api/v1/en/person/duplicates?email=kari.nordmann%40example.com" \
  -H "Authorization: Bearer $TOKEN"

Replace a person

PUT /{instanceName}/api/v1/{locale}/person/{personId}

Full replace (PUT): omitted optional fields are cleared.

Parametere

Forespørselskropp

application/json → PersonUpdateDto

Svar

Eksempel

curl -X PUT "https://api.visena.example/acme/api/v1/en/person/xK9mQ2" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Kari",
    "lastName": "Nordmann",
    "primaryEmail": "kari.nordmann@example.com",
    "jobTitle": "Head of Operations"
  }'

Partially update a person (RFC 7396 JSON Merge Patch)

PATCH /{instanceName}/api/v1/{locale}/person/{personId}

Absent fields are unchanged, JSON null clears, a value sets. An empty body {} is a no-op. Wrong content type → 415.

Parametere

Forespørselskropp

application/merge-patch+json → object

Svar

Eksempel

curl -X PATCH "https://api.visena.example/acme/api/v1/en/person/xK9mQ2" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/merge-patch+json" \
  -d '{
    "jobTitle": "Head of Operations",
    "directPhone": null
  }'

Delete a person

DELETE /{instanceName}/api/v1/{locale}/person/{personId}

Hard delete. 204 on success; a repeat delete → 404.

Parametere

Svar

Eksempel

curl -X DELETE "https://api.visena.example/acme/api/v1/en/person/xK9mQ2" \
  -H "Authorization: Bearer $TOKEN"

Set a person's planned deletion date

PUT /{instanceName}/api/v1/{locale}/person/{personId}/planned-deletion-date

Sets the person's planned deletion date — GDPR bookkeeping used to plan future deletions: the date is shown and filterable in Visena's person lists, and nothing is deleted automatically on that date (deletion itself is the separate GDPR-delete operation). Requires the GDPR person delete feature to be enabled for the instance. Returns the updated person.

Parametere

Forespørselskropp

application/json → PersonPlannedDeletionDto

Svar

Eksempel

curl -X PUT "https://api.visena.example/acme/api/v1/en/person/xK9mQ2/planned-deletion-date" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "plannedDeletionDate": "2027-01-01"
  }'

Clear a person's planned deletion date

DELETE /{instanceName}/api/v1/{locale}/person/{personId}/planned-deletion-date

Removes only the planned deletion date from the person — the person itself is NOT deleted and nothing else changes. Idempotent: 204 also when no date was set. Requires the GDPR person delete feature to be enabled for the instance.

Parametere

Svar

Eksempel

curl -X DELETE "https://api.visena.example/acme/api/v1/en/person/xK9mQ2/planned-deletion-date" \
  -H "Authorization: Bearer $TOKEN"

GDPR-delete a person

DELETE /{instanceName}/api/v1/{locale}/person/{personId}/gdpr

Marks the person deleted (PII is scrubbed immediately) and enqueues the asynchronous GDPR erasure job that removes associated data (emails, documents, customer controls, AML reports, budget lines, relations, ...). Requires the GDPR person delete feature to be enabled for the instance and an API client that is permitted to GDPR-delete persons (403 otherwise). excludeUsers (default true) selects how persons holding a Visena user account are treated: true rejects them with 409, false GDPR-deletes them together with their user account. 202 on enqueue; a repeat GDPR delete → 404.

Parametere

Svar

Eksempel

curl -X DELETE "https://api.visena.example/acme/api/v1/en/person/xK9mQ2/gdpr" \
  -H "Authorization: Bearer $TOKEN"