GET /api/v1/me/natural-person

Retrieve personal profile information for the authenticated user.

Endpoint

GET /api/v1/me/natural-person

Authentication

This endpoint accepts either:

• an OAuth access token with the eprospera:person.details.read scope, or
• an Agent Key (ak-) with the agent:person.details.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.details.read
• agent:person.details.read

Example Request

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

Response

Success Response (200 OK)

Field	Type	Description
givenName	string	User's first/given name
surname	string	User's last name/surname
name	string	Full name (formatted combination of given name and surname)
residentPermitNumber	string	Próspera Resident Permit Number (RPN)
countryOfBirth	string | null	Country where the user was born
citizenships	string[]	Array of countries where the user holds citizenship
dateOfBirth	string | null	Date of birth in ISO 8601 format (YYYY-MM-DD)
sex	string | null	Biological sex (Male, Female, or Other)
address	object | null	Current residential address
address.country	string	Country
address.line1	string	Address line 1 (street address)
address.line2	string | null	Address line 2 (apartment, suite, etc.)
address.city	string	City
address.state	string | null	State/Province/Region
address.postalCode	string	Postal/ZIP code
phoneNumber	string | null	Formatted phone number with country code

Example Response

{
  "givenName": "Maria",
  "surname": "Rodriguez",
  "name": "Maria Rodriguez",
  "residentPermitNumber": "90000000000123",
  "countryOfBirth": "Honduras",
  "citizenships": ["Honduras", "United States"],
  "dateOfBirth": "1990-05-15",
  "sex": "Female",
  "address": {
    "country": "Honduras",
    "line1": "Calle Principal 123",
    "line2": "Apt 4B",
    "city": "Roatan",
    "state": "Islas de la Bahía",
    "postalCode": "34101"
  },
  "phoneNumber": "+50498765432"
}

Null User Response

If no natural person record exists for the authenticated user:

null

Error Responses

401 Unauthorized - Missing Token

{
  "error": "missing_token"
}

401 Unauthorized - Invalid Token

{
  "error": "invalid_token"
}

403 Forbidden - Insufficient Scopes

Returned when an OAuth token lacks the required scope:

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

403 Forbidden — Insufficient Scope

Returned when an Agent Key lacks the required scope:

{
  "error": "Insufficient permissions"
}

500 Internal Server Error

{
  "error": "Internal server error"
}

Notes

• Returns null if the user has no natural-person record (i.e., no approved residency application).
• Phone numbers use E.164 format. Dates use ISO 8601.
• The citizenships array may be empty if the user has not provided this information.