---
title: "Search for events"
method: POST
path: "/events/search"
tags: ["Search"]
---

# Search for events

`POST /events/search`

## Request body

- object
  - `query` QueryType, required
    - `type` union, required
      - 'and'
      - 'or'
    - `clauses` union[], required
      - union
        - QueryExpression
          - `id` string
          - `eventType` string
          - `status` union
            - AnyOfStatus
              - …
            - ExactStatus
              - …
          - `createdAt` union
            - ExactDate
              - …
            - RangeDate
              - …
            - TimePeriod
              - …
          - `updatedAt` union
            - ExactDate
              - …
            - RangeDate
              - …
            - TimePeriod
              - …
          - `legalStatuses.DECLARED.createdAtLocation` Within
            - `type` 'within', required
            - `location` string, required
          - `legalStatuses.DECLARED.createdByRole` AnyOf
            - `type` 'anyOf', required
            - `terms` string[], required
          - `legalStatuses.REGISTERED.acceptedAt` union
            - ExactDate
              - …
            - RangeDate
              - …
            - TimePeriod
              - …
          - `legalStatuses.REGISTERED.createdAtLocation` Within
            - `type` 'within', required
            - `location` string, required
          - `legalStatuses.REGISTERED.createdByRole` AnyOf
            - `type` 'anyOf', required
            - `terms` string[], required
          - `legalStatuses.REGISTERED.registrationNumber` Exact
            - `type` 'exact', required
            - `term` string, required
          - `createdAtLocation` union
            - Within
              - …
            - Exact
              - …
          - `updatedAtLocation` union
            - Within
              - …
            - Exact
              - …
          - `assignedTo` Exact
            - `type` 'exact', required
            - `term` string, required
          - `createdByUserType` ExactUserType
            - `type` 'exact', required
            - `term` 'user' | 'system', required
          - `updatedByUserRole` Exact
            - `type` 'exact', required
            - `term` string, required
          - `createdBy` Exact
            - `type` 'exact', required
            - `term` string, required
          - `updatedBy` Exact
            - `type` 'exact', required
            - `term` string, required
          - `trackingId` Exact
            - `type` 'exact', required
            - `term` string, required
          - `flags` ContainsFlags
            - `anyOf` union[]
              - …
            - `noneOf` union[]
              - …
          - `data` union
            - union
              - …
            - object
        - QueryType — recursive
  - `limit` number
  - `offset` number
  - `sort` object[]
    - `field` string, required
    - `direction` 'asc' | 'desc'

## Response `200`

Successful response

- object
  - `results` EventIndex[], required
    - `id` string, uuid, required
    - `type` string, required — The type of event, such as birth, death, or marriage.
    - `status` 'CREATED' | 'NOTIFIED' | 'DECLARED' | 'REGISTERED' | 'ARCHIVED', required
    - `legalStatuses` object, required — Metadata related to the legal registration of the event, such as who registered it and when.
      - `DECLARED` object, nullable
        - `createdAt` string, date-time, required — The timestamp when the action request was created.
        - `createdBy` string, required — ID of the user who created the action request.
        - `createdAtLocation` string, uuid, nullable — Location of the user who created the action request.
        - `createdByUserType` 'user' | 'system', nullable — Whether the user is a normal user or a system.
        - `acceptedAt` string, date-time, required — Timestamp when the action request was accepted.
        - `createdByRole` string — Role of the user at the time of action request creation.
      - `REGISTERED` object, nullable
        - `createdAt` string, date-time, required — The timestamp when the action request was created.
        - `createdBy` string, required — ID of the user who created the action request.
        - `createdAtLocation` string, uuid, nullable — Location of the user who created the action request.
        - `createdByUserType` 'user' | 'system', nullable — Whether the user is a normal user or a system.
        - `acceptedAt` string, date-time, required — Timestamp when the action request was accepted.
        - `createdByRole` string — Role of the user at the time of action request creation.
        - `registrationNumber` string, required — Registration number of the event. Always present for accepted registrations.
    - `createdAt` string, date-time, required — The timestamp when the event was first created and saved.
    - `dateOfEvent` string, date, nullable
    - `placeOfEvent` string, uuid, nullable
    - `createdBy` string, required — ID of the user who created the event.
    - `createdByUserType` 'user' | 'system', nullable — Whether the user is a normal user or a system.
    - `updatedByUserRole` string, nullable — Role of the user who last changed the status.
    - `createdAtLocation` string, uuid, nullable — Location of the user who created the event.
    - `updatedAtLocation` string, uuid, nullable — Location of the user who last changed the status.
    - `updatedAt` string, date-time, required — Timestamp of the most recent *accepted* status change. Possibly 3rd party update, if action is validation asynchronously.
    - `assignedTo` string, nullable — ID of the user currently assigned to the event.
    - `updatedBy` string, nullable — ID of the user who last changed the status.
    - `trackingId` string, required — System-generated tracking ID used by informants or registrars to look up the event.
    - `potentialDuplicates` object[], required — List of event IDs and their tracking IDs that this event could be a duplicate of.
      - `id` string, uuid, required
      - `trackingId` string, required
    - `flags` union[], required
      - union
        - string
        - 'incomplete' | 'rejected' | 'correction-requested' | 'potential-duplicate' | 'edit-in-progress'
        - string — Custom flag identifier defined by the country config.
    - `declaration` object, required — Aggregate representation of event data after all actions have been applied, with all updates consolidated and null values removed.
  - `total` number, required

## Other responses

- `400` — Invalid input data
- `401` — Authorization not provided
- `403` — Insufficient access
- `500` — Internal server error

---

[API](https://skmtc.net/opencrvs/apis/opencrvs-api.md) · [All operations](https://skmtc.net/opencrvs/apis/opencrvs-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/opencrvs/opencrvs-api/revisions/6bb157c11b8d/schema)