Identities

An identity is the core KYC/AML record in Seqlense. It represents a real-world party you need to know about: a person, a company, or a government body. Wallets, alerts, order-book clients, tags and notes all attach back to identities, so this is usually the first thing you create.

The three types

Each identity has a type and a matching block of type-specific fields.

Validation rules

gender, pep_status and jurisdiction_level are accepted in any case and stored uppercase. A failed check returns 400 with a message such as {"error": "nationality must be 2-letter ISO code"}.

Create an identity

POST /v1/identity/ with a type and that type's required fields. The response returns the new identity's UUID.

curl -X POST "https://monitoring.seqlense.com/api/v1/identity/" \
  -H "Authorization: Bearer sq_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "PERSON",
    "first_name": "Alice",
    "last_name": "Martin",
    "nationality": "FR",
    "date_of_birth": "1990-05-14",
    "pep_status": "NONE"
  }'

{ "status": "ok", "id": "6f9619ff-8b86-4d11-b42d-00c04fc964ff" }

curl -X POST "https://monitoring.seqlense.com/api/v1/identity/" \
  -H "Authorization: Bearer sq_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "COMPANY",
    "legal_name": "ACME SAS",
    "registration_number": "55210055400013",
    "country_of_incorporation": "FR"
  }'

List, search, and paginate

GET /v1/identity/ returns your active identities, newest first.

curl -H "Authorization: Bearer sq_YOUR_API_KEY" \
  "https://monitoring.seqlense.com/api/v1/identity/?type=COMPANY&q=acme&page=1&limit=50"

{
  "identities": [
    {
      "id": "6f9619ff-8b86-4d11-b42d-00c04fc964ff",
      "type": "COMPANY",
      "display_name": "ACME SAS",
      "country": "FR",
      "created_at": "2026-07-27 10:00:00",
      "updated_at": "2026-07-27 10:00:00"
    }
  ],
  "pagination": {
    "page": 1, "page_size": 50, "total": 1,
    "total_pages": 1, "has_next": false, "has_prev": false
  }
}

display_name is computed from the type-specific fields (person name, legal name or official name) and country from the nationality, country of incorporation or country code. Timestamps are YYYY-MM-DD HH:MM:SS.

Use GET /v1/identity/detail?id=… for the full record, which adds a person, company or government block (unset optional fields come back as empty strings), and GET /v1/identity/count for totals by type:

{ "total": 42, "persons": 30, "companies": 10, "governments": 2 }

Update

PUT /v1/identity/ is a partial update: pass the id plus only the fields you want to change. Fields you leave out keep their value, an empty string clears an optional field, and fields that do not belong to the identity's type are ignored. The same validation rules apply.

curl -X PUT "https://monitoring.seqlense.com/api/v1/identity/" \
  -H "Authorization: Bearer sq_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "id": "6f9619ff-8b86-4d11-b42d-00c04fc964ff", "pep_status": "PEP" }'

An identity in the trash cannot be read or updated (404) until it is restored.

Delete, trash, and restore

Deletes are soft: the API never hard-deletes an identity. A deleted identity leaves the active list, the counts and the detail endpoint, but keeps its data and its links to wallets, tags and notes.

• DELETE /v1/identity/?id=… moves an identity to the trash.
• GET /v1/identity/deleted lists the trash, with the same type, q, page and limit parameters as the main list.
• POST /v1/identity/restore with { "id": "…" } brings one back.

curl -X POST "https://monitoring.seqlense.com/api/v1/identity/restore" \
  -H "Authorization: Bearer sq_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "id": "6f9619ff-8b86-4d11-b42d-00c04fc964ff" }'

Merge duplicates

Duplicates happen: a bulk import creates "Jean Dupont", then an order-book roster creates the same person again. POST /v1/identity/merge folds the duplicate (source_id) into the record you keep (target_id):

1. Wallet links, order-book client links, tags and notes move from the source to the target. A wallet or tag both already had is kept once.
2. The source is soft-deleted and lands in the trash.
3. The merge is logged in the activity of both identities.

Everything happens in one transaction: if a step fails, nothing changes and you get 400 {"error": "The merge could not be completed; nothing was changed"}.

curl -X POST "https://monitoring.seqlense.com/api/v1/identity/merge" \
  -H "Authorization: Bearer sq_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_id": "0b7c3f55-1d2e-4a6b-9c8d-7e6f5a4b3c2d",
    "target_id": "6f9619ff-8b86-4d11-b42d-00c04fc964ff"
  }'

{
  "merged": true,
  "source_id": "0b7c3f55-1d2e-4a6b-9c8d-7e6f5a4b3c2d",
  "target_id": "6f9619ff-8b86-4d11-b42d-00c04fc964ff",
  "moved": { "wallets": 2, "ob_clients": 1, "tags": 3, "notes": 4 }
}

Rules: both ids must be different UUIDs from your organization (404 otherwise), and the target must be active (a target in the trash returns 404). The source's own fields (names, dates, registration number) are not copied, so update the target first if the duplicate held better data. Restoring the source afterwards brings back the record alone: its links stay on the target.

Bulk import and delete

Onboarding an existing book of clients? Use the bulk endpoints instead of looping:

• POST /v1/identity/bulk: 1 to 1000 items, each in the create shape. Items are created one by one; the response reports success, failed, and an errors array with the failed item's index and invalid type or creation failed.
• POST /v1/identity/bulk-delete: soft-delete 1 to 500 identities by ids. Ids that are invalid or not yours count as failed.

curl -X POST "https://monitoring.seqlense.com/api/v1/identity/bulk" \
  -H "Authorization: Bearer sq_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "type": "PERSON", "first_name": "Alice", "last_name": "Martin" },
      { "type": "COMPANY", "legal_name": "ACME SAS" }
    ]
  }'

{ "status": "ok", "success": 2, "failed": 0, "errors": [] }

Activity

Every identity change is recorded. GET /v1/identity/activity returns that history, newest first, 50 events per page (page to move on; an empty events array means you reached the end). Pass id to scope it to one identity, or q to search titles, details, actions and actor names.

{
  "events": [
    {
      "uuid": "9a1b2c3d-4e5f-4a6b-8c7d-0e1f2a3b4c5d",
      "entity_uuid": "6f9619ff-8b86-4d11-b42d-00c04fc964ff",
      "entity_title": "Alice Martin",
      "action": "CREATE",
      "detail": "Created PERSON identity",
      "severity": "INFO",
      "actor": "api_key",
      "actor_name": "API Key #12",
      "created_at": "2026-07-27T10:00:00+00:00"
    }
  ],
  "pagination": { "page": 1, "page_size": 50 }
}

actor is the user id, or api_key when the change came from an API key.

SIRET enrichment (French companies)

When a COMPANY has a valid French SIRET in registration_number (14 digits passing the Luhn check) and country_of_incorporation is FR or empty, Seqlense fetches its SIRENE registry data while it handles the create or update: SIREN, legal form, NAF activity code, headcount, capital, address, geolocation, status, and whether the company has ceased trading.

• GET /v1/identity/siret?id=… returns the stored data, or 404 when there is none.
• POST /v1/identity/siret/refresh with { "id": "…" } re-fetches it now and returns the result.

Enrichment is best-effort: a failed lookup never blocks the identity write. If an update changes the registration number or country so that it no longer qualifies, the stored data is deleted. The refresh endpoint only accepts an identity id, never a raw SIRET, and returns 400 when the company has no valid SIRET or the registry lookup fails.

Tags and notes

Identities can carry colored tags and investigation notes. See Tags and notes.

Full reference

Every endpoint, parameter and schema is in the API Reference.