POST legal_entities/search

Search for legal entities in Próspera by name or resident permit number (RPN).

Endpoint

POST /api/v1/registries/legal_entities/search

Authentication

Requires a valid API key in the Authorization header:

Authorization: Bearer <your-api-key>

Request Body

Field	Type	Required	Description
query	string	Yes	Search query - can be entity name or resident permit number

Example Request

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

Response

Success Response (200 OK)

Field	Type	Description
results	array	Array of matching entities

Entity Object

Field	Type	Description
id	string	Unique entity identifier
name	string	Entity name
extension	string	Entity type extension (e.g., "LLC", "Corp")
residentPermitNumber	string	Associated resident permit number

Example Response

{
  "results": [
    {
      "id": "ent_abc123",
      "name": "Acme Corporation",
      "extension": "LLC",
      "residentPermitNumber": "80000000000123"
    },
    {
      "id": "ent_def456", 
      "name": "ACME Holdings",
      "extension": "Corp",
      "residentPermitNumber": "80000000000456"
    }
  ]
}

Search Behavior

• Name Search: Searches entity names using case-insensitive partial matching
• Multi-word Search: Each word in the query is matched separately (AND logic)
• RPN Search: Exact or partial matching on resident permit numbers
• Active Entities: Only returns entities with active residency status

Error Responses

400 Bad Request

Missing or invalid query parameter:

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

401 Unauthorized

Invalid or missing API key:

{
  "error": "Invalid API key"
}

429 Too Many Requests

Rate limit exceeded:

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

500 Internal Server Error

Server error:

{
  "error": "Internal server error"
}

Rate Limits

• Per day: 5,000 requests
• Per minute: 50 requests

Rate limits are applied per API key.

Use Cases

• Entity Lookup: Find specific companies by name
• RPN Verification: Locate entities by their resident permit number
• Fuzzy Search: Partial name matching for entity discovery
• Due Diligence: Verify entity registration status