> ## Documentation Index > Fetch the complete documentation index at: https://docs.nlbs.ai/llms.txt > Use this file to discover all available pages before exploring further. # Search canonical entities > Search canonical entities by name, document, or both. At least one of name or document is required. Partial document searches require a name. ## OpenAPI ````yaml https://api.qa.nlbs.ai/api/openapi.json get /entities openapi: 3.1.0 info: description: >- NL Labs AI AML API. Use Bearer API keys for protected endpoints. The /live and /ready probes are public. title: NL Labs AI version: 0.1.0 servers: - url: https://api.qa.nlbs.ai/api security: - ApiKeyAuth: [] tags: - description: Runtime health checks and source freshness endpoints. name: health - description: Canonical entity lookup endpoints used before starting analyses. name: entities - description: AML analysis creation, status, result, and debug endpoints. name: analyses - description: Regulatory report (Motor 2) creation, status, result, and debug endpoints. name: reports - description: Versioned deterministic rules catalog endpoints. name: rules - description: Versioned regulatory reference catalog endpoints. name: regulatory - description: Webhook endpoint configuration and delivery-event operations. name: webhooks paths: /entities: get: tags: - entities summary: Search canonical entities description: >- Search canonical entities by name, document, or both. At least one of name or document is required. Partial document searches require a name. operationId: list_entities parameters: - description: Name fragment. Must contain at least 3 useful characters. in: query name: name required: false schema: anyOf: - type: string - type: 'null' description: Name fragment. Must contain at least 3 useful characters. examples: - Maria Silva title: Name - description: CPF or CNPJ search value. Partial values require name. in: query name: document required: false schema: anyOf: - type: string - type: 'null' description: CPF or CNPJ search value. Partial values require name. examples: - '12345678901' title: Document - description: Optional entity type filter. in: query name: entity_type required: false schema: anyOf: - $ref: '#/components/schemas/EntityType' - type: 'null' description: Optional entity type filter. title: Entity Type - description: Maximum page size. in: query name: limit required: false schema: default: 20 description: Maximum page size. maximum: 100 minimum: 1 title: Limit type: integer - description: Zero-based page offset. in: query name: offset required: false schema: default: 0 description: Zero-based page offset. minimum: 0 title: Offset type: integer - description: >- Testing: ignores the cached entity_id and forces lake resolution, reusing the cached PH3A payload (no new API call, no credit spend). Use to measure lake resolution latency repeatably. in: query name: bypass_entity_cache required: false schema: default: false description: >- Testing: ignores the cached entity_id and forces lake resolution, reusing the cached PH3A payload (no new API call, no credit spend). Use to measure lake resolution latency repeatably. title: Bypass Entity Cache type: boolean responses: '200': content: application/json: schema: $ref: '#/components/schemas/EntityListResponse' description: Successful Response '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Missing, malformed, expired, or invalid Bearer API key. '403': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: The authenticated API key does not have the required scope. '422': description: >- Invalid request body, path parameter, query parameter, or business rule. security: - HTTPBearer: [] components: schemas: EntityType: enum: - person - organization - government_agency - financial_institution - political_party - foreign_entity - vessel - aircraft title: EntityType type: string EntityListResponse: properties: items: description: Entities in the current page. items: $ref: '#/components/schemas/EntityListItem' title: Items type: array limit: description: Requested page size. examples: - 20 title: Limit type: integer offset: description: Requested zero-based offset. examples: - 0 title: Offset type: integer total: description: Total number of matching entities. examples: - 1 title: Total type: integer required: - items - total - limit - offset title: EntityListResponse type: object ErrorResponse: properties: detail: description: Stable public error message. examples: - Resource not found. title: Detail type: string required: - detail title: ErrorResponse type: object EntityListItem: examples: - aliases: - M. Silva display_name: Maria Silva entity_type: person id: 410752090310337400 identifiers: - identifier_type: CPF is_masked: true value: '***.123.456-**' legal_name: Maria Silva properties: aliases: description: Known aliases for the entity. items: type: string title: Aliases type: array display_name: description: Display name chosen for search results. title: Display Name type: string entity_type: $ref: '#/components/schemas/EntityType' description: Canonical entity type. id: description: External numeric identifier for the canonical entity. title: Id type: integer identifiers: description: Masked relevant identifiers. items: $ref: '#/components/schemas/EntityIdentifierSummary' title: Identifiers type: array legal_name: anyOf: - type: string - type: 'null' description: Legal name when available. title: Legal Name required: - id - entity_type - display_name - legal_name - identifiers - aliases title: EntityListItem type: object EntityIdentifierSummary: properties: identifier_type: $ref: '#/components/schemas/EntityIdentifierType' description: Identifier type, such as CPF or CNPJ. is_masked: description: Whether the identifier value is masked. title: Is Masked type: boolean value: description: Masked identifier value safe for API responses. title: Value type: string required: - identifier_type - value - is_masked title: EntityIdentifierSummary type: object EntityIdentifierType: enum: - CPF - CNPJ - CNPJ_ROOT - RG - PASSPORT - VOTER_ID - TSE_CANDIDATE_ID - OAB - CVM_CODE - OFAC_UID - UN_SANCTION_ID - LEI - INTERNAL_ID - TSE_PARTY_NUMBER - NIS - GOV_ORG_CODE title: EntityIdentifierType type: string securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key ````