Submit an assessment and get matching programmes

Stores the client's answers and returns eligible programmes ranked by score (0–100).

answers is grouped by step, then by question key — e.g. the client's
marital status is answers.applicant_profile.marital_status. Unknown keys are
dropped. Every question is optional to the API, but unanswered questions
are skipped by the matcher, so fewer answers mean broader, less precise matches.

The assessment is stored against your account and its id is returned as assessment
(null if the matches were computed but storing the assessment failed).

Request

Authorization

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Body Params application/jsonRequired

Example

{
    "mode": "declared",
    "objectives": [
        "66f1a2b3c4d5e6f708192a3b",
        "66f1a2b3c4d5e6f708192a3c"
    ],
    "answers": {
        "applicant_profile": {
            "full_name": "John Smith",
            "date_of_birth": "1985-04-12",
            "age": 41,
            "citizenship": "65a0c1d2e3f4a5b6c7d8e9f0",
            "residence": "65a0c1d2e3f4a5b6c7d8e9f1",
            "marital_status": "married"
        },
        "family": {
            "include_spouse": "yes",
            "include_children": "yes",
            "children_ages": "5, 12",
            "include_parents": "no",
            "include_parents_in_law": "no"
        },
        "destination_preferences": {
            "goals": [
                "66f1a2b3c4d5e6f708192a3b",
                "66f1a2b3c4d5e6f708192a3c"
            ],
            "preferred_countries": [
                "65a0c1d2e3f4a5b6c7d8e9f2"
            ],
            "regions": [
                "europe",
                "caribbean"
            ]
        },
        "additional_preferences": {
            "excluded_countries": [],
            "other_requirements": null
        },
        "physical_presence": {
            "relocation_preference": "maybe",
            "prefer_low_presence": "yes",
            "stay_tolerance": "31_90_days",
            "tax_residency_willing": "no"
        },
        "citizenship_objective": {
            "importance": "preferred",
            "pr_importance": "not_important",
            "citizenship_timeline": "5_10_years"
        },
        "lifestyle": {
            "lifestyle_priorities": [
                "safety",
                "visa_free_travel"
            ]
        },
        "investment_preference": {
            "budget": 750000,
            "budget_currency": "USD",
            "annual_income": 100000,
            "annual_income_currency": "USD",
            "net_worth": 3000000,
            "net_worth_currency": "USD",
            "deployment_types": [
                "PROPERTY",
                "INVESTMENT_FUND"
            ]
        },
        "professional_profile": {
            "qualification": "masters",
            "profession": "Engineer",
            "experience_years": 15,
            "has_job_offer": "no",
            "is_business_owner": "yes",
            "establish_company_overseas": "no"
        },
        "eligibility": {
            "clean_criminal_record": "yes",
            "funds_documented": "yes",
            "documents_available": "yes"
        }
    }
}

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

curl --location 'https://demoapi.base93.com/api/v1/user/external/agent//immigration/assessments' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
    "mode": "declared",
    "objectives": [
        "66f1a2b3c4d5e6f708192a3b",
        "66f1a2b3c4d5e6f708192a3c"
    ],
    "answers": {
        "applicant_profile": {
            "full_name": "John Smith",
            "date_of_birth": "1985-04-12",
            "age": 41,
            "citizenship": "65a0c1d2e3f4a5b6c7d8e9f0",
            "residence": "65a0c1d2e3f4a5b6c7d8e9f1",
            "marital_status": "married"
        },
        "family": {
            "include_spouse": "yes",
            "include_children": "yes",
            "children_ages": "5, 12",
            "include_parents": "no",
            "include_parents_in_law": "no"
        },
        "destination_preferences": {
            "goals": [
                "66f1a2b3c4d5e6f708192a3b",
                "66f1a2b3c4d5e6f708192a3c"
            ],
            "preferred_countries": [
                "65a0c1d2e3f4a5b6c7d8e9f2"
            ],
            "regions": [
                "europe",
                "caribbean"
            ]
        },
        "additional_preferences": {
            "excluded_countries": [],
            "other_requirements": null
        },
        "physical_presence": {
            "relocation_preference": "maybe",
            "prefer_low_presence": "yes",
            "stay_tolerance": "31_90_days",
            "tax_residency_willing": "no"
        },
        "citizenship_objective": {
            "importance": "preferred",
            "pr_importance": "not_important",
            "citizenship_timeline": "5_10_years"
        },
        "lifestyle": {
            "lifestyle_priorities": [
                "safety",
                "visa_free_travel"
            ]
        },
        "investment_preference": {
            "budget": 750000,
            "budget_currency": "USD",
            "annual_income": 100000,
            "annual_income_currency": "USD",
            "net_worth": 3000000,
            "net_worth_currency": "USD",
            "deployment_types": [
                "PROPERTY",
                "INVESTMENT_FUND"
            ]
        },
        "professional_profile": {
            "qualification": "masters",
            "profession": "Engineer",
            "experience_years": 15,
            "has_job_offer": "no",
            "is_business_owner": "yes",
            "establish_company_overseas": "no"
        },
        "eligibility": {
            "clean_criminal_record": "yes",
            "funds_documented": "yes",
            "documents_available": "yes"
        }
    }
}'

Responses

🟢200

application/json

Ranked matches

Bodyapplication/json

Example

{
    "status": true,
    "response_code": 200,
    "data": {
        "assessment": "6702f0a1b2c3d4e5f6a7b8c9",
        "matches": [
            {
                "rank": 1,
                "programme": "66e0b1c2d3e4f5a6b7c8d9e0",
                "name": "Golden Visa — Real Estate",
                "jurisdiction": {
                    "_id": "65a0c1d2e3f4a5b6c7d8e9f2",
                    "name": "Greece",
                    "logo": "https://…/gr.png"
                },
                "category": {
                    "_id": "66d0a1b2c3d4e5f6a7b8c9d0",
                    "name": "Residency by Investment"
                },
                "min_investment": 250000,
                "display": {
                    "investment": "$250,000 – $800,000",
                    "fees": "$12,500",
                    "min_stay": null,
                    "family": "Family included",
                    "citizenship": "Citizenship in 7–10 years"
                },
                "details": {
                    "route_type": "RESIDENCY",
                    "min_investment": 250000,
                    "max_investment": 800000,
                    "objective_ids": [
                        "66f1a2b3c4d5e6f708192a3b"
                    ]
                },
                "score": 86,
                "breakdown": {
                    "objective": 100,
                    "destination": 100,
                    "financial": 80,
                    "timeline": 50,
                    "presence": 100
                },
                "band": "strong",
                "budget_status": "within",
                "reasons": [
                    {
                        "text": "Second Passport",
                        "met": true
                    },
                    {
                        "text": "Citizenship may take longer than preferred",
                        "met": false
                    }
                ]
            }
        ]
    }
}

🟠400ValidationError

🟠401Unauthorized

🟠403Forbidden