GET /api/v1/me/natural-person/residency

Retrieve residency information for the authenticated user.

Endpoint

GET /api/v1/me/natural-person/residency

Authentication

This endpoint accepts either:

• an OAuth access token with the eprospera:person.residency.read scope, or
• an Agent Key (ak-) with the agent:person.residency.read scope

Standard API keys (sk-) are not supported on this endpoint.

Authorization: Bearer <access-token-or-agent-key>

Accepted Scopes

Provide the scope that matches the token type you are using:

• eprospera:person.residency.read
• agent:person.residency.read

Example Request

curl https://portal.eprospera.com/api/v1/me/natural-person/residency \
  -H "Authorization: Bearer <access-token-or-agent-key>"

Response

Success Response (200 OK)

Field	Type	Description
wasEverResident	boolean	Whether the user has ever held any residency status in Próspera
activeResidency	object | null	Current active residency details, or null if no active residency
activeResidency.effectiveDate	string	Date when the residency became effective (ISO 8601 format)
activeResidency.terminationDate	string | null	Date when the residency ends/ended, or null if not terminated. Can be a future date if residency is cancelled but not yet expired
activeResidency.residencyType	string	Type of residency (see Residency Types below)
activeResidency.version	string	Version of the Agreement of Coexistence (e.g., "v08.29.2024")

Residency Types

Type	Description
Limited e-Resident	Also known as "Visitor Pass"
e-Resident	e-Resident residency
Resident	Physical residency

Example Response (Active Resident)

{
  "wasEverResident": true,
  "activeResidency": {
    "effectiveDate": "2024-03-15T00:00:00.000Z",
    "terminationDate": null,
    "residencyType": "Resident",
    "version": "v08.29.2024"
  }
}

Example Response (Active e-Resident)

{
  "wasEverResident": true,
  "activeResidency": {
    "effectiveDate": "2023-11-01T00:00:00.000Z",
    "terminationDate": "2025-11-01T00:00:00.000Z",
    "residencyType": "Limited e-Resident",
    "version": "v10.20.2022"
  }
}

Example Response (No Active Residency)

{
  "wasEverResident": true,
  "activeResidency": null
}

Example Response (Never a Resident)

{
  "wasEverResident": false,
  "activeResidency": null
}

Error Responses

401 Unauthorized - Missing Token

{
  "error": "missing_token"
}

401 Unauthorized - Invalid Token

{
  "error": "invalid_token"
}

403 Forbidden - Insufficient Scopes (OAuth token)

Returned when an OAuth token lacks the required scope:

{
  "error": "missing_scopes: eprospera:person.residency.read"
}

403 Forbidden - Insufficient Scopes (Agent Key)

Returned when an Agent Key lacks the required scope:

{
  "error": "Insufficient permissions"
}

500 Internal Server Error

{
  "error": "Internal server error"
}

Notes

• A residency is "active" when effectiveDate is in the past and terminationDate is either null or in the future.
• wasEverResident is true if the user has ever held any residency, even if no longer active.
• The version field refers to the Agreement of Coexistence version the residency was established under.