POST registries/legal_entities/search

Search the Próspera legal-entity registry by name or by the entity's own resident permit number.

Endpoint

POST /api/v1/registries/legal_entities/search

Authentication

This endpoint accepts:

• a standard API key (sk-)
• an Agent Key (ak-) with the agent:registry.search scope

Send the key in the Authorization header:

Authorization: Bearer <your-api-key-or-agent-key>

Request Body

Field	Type	Required	Description
query	string	Yes	Free-text search input. The handler splits name searches on spaces and also checks the entity's own resident permit number for partial matches.

Example Request

curl -X POST https://portal.eprospera.com/api/v1/registries/legal_entities/search \
  -H "Authorization: Bearer <your-api-key-or-agent-key>" \
  -H "Content-Type: application/json" \
  -d '{"query": "Acme Holdings"}'

Response

Success Response (200 OK)

Field	Type	Description
results	array	Matching legal entities.

Result Object

Field	Type	Description
id	string	Legal-entity ID.
name	string	Legal name.
extension	string	Name extension such as LLC.
residentPermitNumber	string | null	The entity's own resident permit number.

Example Response

{
  "results": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "Acme Holdings",
      "extension": "LLC",
      "residentPermitNumber": "80000000000123"
    }
  ]
}

Search Behavior

• Name search is case-insensitive.
• Multi-word queries are split on spaces; each word is matched independently against entity names.
• RPN search is a partial contains match on the entity's own resident permit number.
• The current implementation does not filter results down to active entities only.

Error Responses

400 Bad Request

{
  "error": "Missing `query` parameter"
}

401 Unauthorized

{
  "error": "Missing API key"
}

or:

{
  "error": "Invalid API key"
}

403 Forbidden

Agent Key missing the required agent:registry.search scope:

{
  "error": "Insufficient permissions"
}

429 Too Many Requests

Rate limit exceeded:

{
  "error": "Rate limit exceeded. Maximum 5000 calls per day, 50 calls per minute."
}

500 Internal Server Error

{
  "error": "Internal server error"
}