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

Retrieve residency information for the authenticated user.

Endpoint

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

Authentication

Requires a valid OAuth access token with the eprospera:person.residency.read scope.

Authorization: Bearer <access-token>

Required Scopes

• eprospera:person.residency.read

Request

No request body or query parameters required.

Example Request

curl https://portal.eprospera.com/api/v1/me/natural-person/residency \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Response

Success Response (200 OK)

Returns residency information for the authenticated user.

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"
}

401 Unauthorized - Insufficient Scopes

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

500 Internal Server Error

{
  "error": "Internal server error"
}

Usage Notes

• A residency is considered "active" if:
  • The effectiveDate is in the past or today, AND
  • The terminationDate is either null or in the future
• wasEverResident is true if the user has ever had any residency agreement, even if it's no longer active
• The version field refers to the Agreement of Coexistence version the residency was established under
• Residency types and versions may be expanded in the future

Data Privacy

• Only the authenticated user's own data is accessible
• Data is only returned if the correct scope is granted during OAuth authorization
• All residency information is subject to e-Prospera's privacy policy
• Access tokens should be kept secure and never exposed in client-side code or logs

Related Endpoints

• GET /api/v1/me/natural-person - Retrieve personal information
• GET /api/v1/me/natural-person/id-verification - Retrieve ID verification documents