Search request fields

Use this page as a quick reference for valid search types and options used by POST /search.

Domain Name and IP Address remain valid Search API types for now, but they will soon stop being supported there. For new lookups, use their replacements: Domain Intelligence and IP Intelligence. No cutoff date has been announced.

Supported search types

Type value	Typical input
`Pseudonym`	`john_doe`
`Email Address`	`[email protected]`
`Domain Name`	`example.com`
`Cryptocurrency`	Wallet address
`IP Address`	`8.8.8.8` or IPv6

These values must match the OpenAPI enum exactly.

Request shape

{
  "query": {
    "type": "Email Address",
    "value": "[email protected]"
  },
  "features": {
    "breached_accounts": true,
    "registered_accounts": "include"
  },
  "cache": {
    "mode": "prefer"
  },
  "delivery": {
    "webhook": {
      "url": "https://client.example/webhooks/osintly",
      "secret": "super-secret-webhook-key"
    }
  }
}

Request sections

Field	Type	Notes
`query`	`object`	Required. Contains `type` and `value`.
`modules`	`object`	Optional. Use `mode: "selected"` plus `ids` to restrict execution.
`leaks`	`object`	Optional. Use `mode: "selected"` plus `sources` to restrict leak providers.
`features`	`object`	Optional. Controls `breached_accounts` and `registered_accounts`.
`cache`	`object`	Optional. Use `mode: "bypass"` to force a fresh execution.
`delivery`	`object`	Optional. Configure `delivery.webhook`.

Module selection behavior (`modules`)

Use modules when you want to restrict execution to a known set of modules. Fetch current module IDs from GET /modules for the selected search type. The UUIDs below illustrate the request shape; do not copy them into production requests without checking the live catalog.

{
  "query": {
    "type": "Email Address",
    "value": "[email protected]"
  },
  "modules": {
    "mode": "selected",
    "ids": [
      "4a8cbb96-70df-4bd6-8f4a-9c0bf5ffde1f",
      "95c36c17-f76e-4911-bd4e-8ea57515b2fb"
    ]
  }
}

Server-side validation rules:

Every module ID must exist
Every module ID must be listed and currently available
Every module ID must be compatible with the selected query.type

Default behavior:

If modules is omitted, Osintly runs the default module set for that search type
If modules.mode is selected, execution is limited to modules.ids

If validation fails, the API returns 400 with an explicit validation error.

ID and pagination parameters

id (path): search UUID
source (path): leak provider source code/name
page (query): leak source page number, minimum 1

Common errors

400 Validation error

Request shape or field values are invalid. Check enum values and data types.

401 Unauthorized

Missing or invalid bearer token.

429 Rate limit exceeded

Respect retry headers and retry after the reset window.

503 Dispatch unavailable

Search creation failed at dispatch layer. Retry with backoff.

API Overview

Endpoints

Supported search types

Request shape

Request sections

Module selection behavior (`modules`)

Common errors

​Supported search types

​Request shape

​Request sections

​Module selection behavior (modules)

​ID and pagination parameters

​Common errors

Supported search types

Request shape

Request sections

Module selection behavior (`modules`)

ID and pagination parameters

Common errors