GET referral_codes/[code]/referrals

Retrieve a list of natural persons and legal entities referred using a specific referral code that you own.

Endpoint

GET /api/v1/referral-codes/{code}/referrals

Authentication

Requires a valid API key in the Authorization header:

Authorization: Bearer <your-api-key>

Path Parameters

Parameter	Type	Required	Description
code	string	Yes	The referral code

Example Request

curl -X GET https://portal.eprospera.com/api/v1/referral-codes/MYCODE123/referrals \
  -H "Authorization: Bearer <your-api-key>"

Response

Success Response (200 OK)

Field	Type	Description
code	string	The referral code
naturalPersons	array	List of natural persons referred with this code
legalEntities	array	List of legal entities referred with this code

Natural Person Object Fields

Field	Type	Description
fullName	string | null	Full name of the referred person. Can be null if the user has not yet applied or been approved for residency
referredAt	string | null	Timestamp when the user was referred (ISO 8601)

Legal Entity Object Fields

Field	Type	Description
name	string	Formatted name of the legal entity
rpn	string	Resident Permit Number of the legal entity
referredAt	string | null	Registration date of the legal entity (ISO 8601)

Example Response

{
  "code": "MYCODE123",
  "naturalPersons": [
    {
      "fullName": "John Doe",
      "referredAt": "2024-03-15T14:30:00.000Z"
    },
    {
      "fullName": null,
      "referredAt": "2024-03-20T09:15:00.000Z"
    }
  ],
  "legalEntities": [
    {
      "name": "Acme Corp LLC",
      "rpn": "80123456789012",
      "referredAt": "2024-04-01T12:00:00.000Z"
    }
  ]
}

Pagination

This endpoint is not currently paginated. The full result sets are returned in a single response under naturalPersons and legalEntities. Treat this as the current contract; in the future a pagination envelope (page/pageSize/totalCount/pageCount, matching /api/v1/nomadlayer/applications) may be added per array — design clients so an additional top-level pagination field would not break them. See Conventions → Pagination.

Error Responses

401 Unauthorized

Invalid or missing API key:

{
  "error": "Invalid API key"
}

404 Not Found

Referral code not found or you don't have access:

{
  "error": "Referral code not found"
}

500 Internal Server Error

Server error:

{
  "error": "Internal server error"
}

Access Control

You can only access referral codes that belong to you. This includes:

• Referral codes associated with your natural person account
• Referral codes associated with legal entities where you are a representative

Notes

• Natural-person referrals can appear before the referred user has a visible residency profile. In those cases, fullName may still be null.
• This endpoint reports referral attribution only. It does not expose checkout state, discount application state, or coupon redemption state.
• Eligible referred users currently receive 20% off the first paid natural-person residency application payment in the portal automatically, but that benefit is not represented in this response payload.