New ASEAN Entrepreneurship Profiling API Docs

This site hosts the documentation for our ASEAN Entrepreneurship Profiling backend API service.

We commonly use URI/URL query parameters for passing parameters to GET requests and HTTP Form Data (i.e. application/x-www-form-urlencoded or multipart/form-data for files) for POST requests. Most HTTP request libraries understand these and their differences.

Our successful API request responses will be always in JSON, such as:

{
  "status": "OK",
  // ...
}

However, our endpoints may also return non-JSON data, such as redirects for unauthenticated requests (due to Laravel Sanctum blocking the request) and critical server errors (generated by Laravel). To prevent confusion with the results, we recommend you to request your HTTP request library/manager to:

Stop following any redirects,
Check whether the HTTP status code is 200,
Check whether the response body is valid JSON, and
Check whether the status is OK, as usual.

Authentication

Get CSRF/XSRF Token

In order to create further requests on AEP, you must request a limited-time, CSRF Token and put the token into the XSRF-TOKEN headers. This is managed by Laravel Sanctum which can be done by:

HEAD/GET http:///sanctum/csrf-cookie

The request will return two set-cookie headers which is meant to store both XSRF-TOKEN and asean_entrepreneurship_profiling_session. If your HTTP request manager allows you to save cookies, this is fine andd you can proceed to send further requests. However, we still recommend you to store the XSRF-TOKEN and reinsert them under the XSRF-TOKEN request header for subsequent requests to the API server.

To learn more about authentication, visit https://laravel.com/docs/9.x/sanctum.

Check Email

To improve the application’s signup/login user experience, you can request the backend to check whether such email address is registered by calling the following:

POST http:///api/check_user

Parameters (Form Data)	Required	Description
email	✅	The email address to be checked

Which will return the following:

Parameters (JSON)	Required	Description
status	✅	Will be either `OK` on success or `KO` on error
error	On error	Should be `INTERNAL` for unknown errors. Note that we don’t throw errors when the email address is registered or not registered; they will be contained into the `data` field instead
data	On success	Should be the Boolean value of `true` or `false`, where `true` means that the email address has been registered before into an account
email	On success	The requested email address, to re-check the request

In order to create a new account, you will need to call to the following:

POST http:///api/signup

Parameters (Form Data)	Required	Description
email	✅	User’s registered email address
password	✅	User’s account password
name	✅	User’s display name
date_of_birth	✅	User’s date of birth, in YYYY-MM-DD format (optional leading zero for month and date)
gender	✅	User’s gender. Acceptable values are `1` (male) and `2` (female).
default_region	❌	User’s default Region ID
device_name	✅	Used for Laravel Sanctum token names

This request will return a JSON data consisting of two parameters:

Parameters (JSON)	Required	Description
status	✅	Will be either `OK` on success or `KO` on error
error	On error	Will be either `USER_ALREADY_EXISTS` if the user is already registered into ASEAN Entrepreneurship Profiling, or `INTERNAL` for unknown errors.
token	On success	`Token` object as generated by Laravel Sanctum. Learn more on Common Objects.

Log In

In order to create a new account, you will need to call to the following:

POST http:///api/signup

Parameters (Form Data)	Required	Description
email	✅	User’s registered email address
password	✅	User’s account password
device_name	✅	Used for Laravel Sanctum token names

This request will return a JSON data consisting of two parameters:

Parameters (JSON)	Required	Description
status	✅	Will be either `OK` on success or `KO` on error
error	On error	Will be either `USER_NOT_FOUND` if the user is not yet registered into ASEAN Entrepreneurship Profiling, `INVALID_PASSWORD` for wrong password, or `INTERNAL` for unknown errors
token	On success	`Token` object as generated by Laravel Sanctum. Learn more on Common Objects.

Forgot Password

To send the recovery email address, perform a request to:

POST http:///api/forgot_password

Parameters (Form Data)	Required	Description
email	✅	User’s registered email address

The server will return the following status codes:

Parameters (JSON)	Required	Description
status	✅	Will be either `OK` on success or `KO` on error
error	On error	Will be either `USER_NOT_FOUND` when there is no user associated with the email address, `RESET_THROTTLED` if the user has requested too many times, or `INTERNAL` for unknown errors

Note that users must continue the password reset session in the AEP Website as required by Laravel Sanctum.

User Management

Get Current User Profile

To get the user’s current profile, perform a request to:

GET http:///api/user

Parameters (Query Parameter)	Required	Description
preferred_language	❌ (Defaults to `en`)	User’s preferred language, for displaying default region translation, in ISO 3166-1 two-letter country code (case-insensitive)

Since the backend is powered by Laravel Sanctum, unauthenticated result will result into a redirect to a login page of the https://aseanentrepreneurshipprofiling.com website. To prevent confusion with the results, we recommend you to request your HTTP request manager to:

Stop following redirects
Check whether the HTTP status code is 200, not 302
Check whether the status is OK, as usual

Parameters (JSON)	Required	Description
status	✅	Will be either `OK` on success or `KO` on error
error	On error	Will be `INTERNAL` for unknown errors
data	On success	A `User` object. Learn more on Common Objects.

Change User Profile

To change the current user profile, perform a request to:

POST http:///api/user

Parameters (Form Data)	Required	Description
date_of_birth	❌	User’s new date of birth, in YYYY-MM-DD format (optional leading zero for month and date)
default_region	❌	User’s new default region, in string (Region ID)
email	❌	User’s new email address. When changed, users will be required to reverify their account.
gender	❌	User’s gender. `1` for male and `2` for female.
name	❌	User’s displayed name, in string
password	❌	User’s new password. Note that there are no “confirm password” fields here.

Stop following redirects
Check whether the HTTP status code is 200, not 302
Check whether the status is OK, as usual

Parameters (JSON)	Required	Description
status	✅	Will be either `OK` on success or `KO` on error
error	On error	Will be `REGION_NOT_FOUND` for invalid region ID, `USER_ALREADY_EXISTS` if the new email has been shared with another account, or `INTERNAL` for unknown errors
data	On success	A `User` object. Learn more on Common Objects.
updated_fields	On success	An object of changed parameters. Similar to the `User` object, but the hashed password data will be shown as well.

Account Closure

To start requesting account closure, you will need to perform these two steps:

Generate confirmation CAPTCHA, and
Confirm account deletion with the CAPTCHA response

CAPTCHA validation is necessary to prevent possible abuse on our backend by unauthorized parties who may access or obtain information about our backend. This also adds another UX guard to users who wish to and not to close their accounts.

Request Account Closure (Step 1)

CAPTCHA can be requested by performing a HTTP request to:

POST http:///api/close_account/1

Parameters (Form Data)	Required	Description
password	✅	User’s current password

This endpoint will return the following data:

Parameters (JSON)	Required	Description
status	✅	Will be either `OK` on success or `KO` on error
error	On error	Will be `INVALID_PASSWORD` for invalid password, `INTERNAL_CAPTCHA` for CAPTCHA-related internal server errors, or `INTERNAL` for unknown errors
captcha_url	On success	A valid URL to download the CAPTCHA image

Confirm Account Closure (Step 2)

Finally, to confirm close account, send:

POST http:///api/close_account/2

Parameters (Form Data)	Required	Description
captcha	✅	CAPTCHA response
password	✅	User’s current password

This endpoint will return the following data:

Parameters (JSON)	Required	Description
status	✅	Will be either `OK` on success or `KO` on error
error	On error	Will be `ACCOUNT_CLOSURE_NOT_REQUESTED` if the user haven’t requested before, `INVALID_CAPTCHA` for wrong CAPTCHA response, `INVALID_PASSWORD` for invalid password, or `INTERNAL` for unknown errors
deleted_at	On success	A SQL timestamp string

Demographic Data Lists

Get current list of business sectors

To get the current list of business sectors, perform a request to:

GET http:///api/get_business_sectors

Parameters (Query Parameter)	Required	Description
preferred_language	❌ (Defaults to `en`)	User’s preferred language, for displaying default region translation, in ISO 3166-1 two-letter country code (case-insensitive)

The endpoint will return the following data:

Parameters (JSON)	Required	Description
status	✅	Will be either `OK` on success or `KO` on error
error	On error	Will be `INTERNAL` for unknown errors
data	On success	An array of `BusinessSector` objects. Learn more on Common Objects.

Get current list of countries

To get the current list of countries, perform a request to:

GET http:///api/get_countries

Parameters (Query Parameter)	Required	Description
preferred_language	❌ (Defaults to `en`)	User’s preferred language, for displaying default region translation, in ISO 3166-1 two-letter country code (case-insensitive)

The endpoint will return the following data:

Parameters (JSON)	Required	Description
status	✅	Will be either `OK` on success or `KO` on error
error	On error	Will be `INTERNAL` for unknown errors
data	On success	An array of `Region` objects. Learn more on Common Objects.

Search Regions

To search for regions, perform a request to:

GET http:///api/search_countries

Parameters (Query Parameter)	Required	Description
country	❌	Filter results by ISO 2-letter country ID. If the `q` parameter is not supplied, the backend will consider this search as “get all regions by country”.
lat	❌	If both `lat` and `lng` are defined, the results will be sorted by the place’s proximity to the defined location coordinates. This will override the `sort_by_alphabet` option.
lng	❌	If both `lat` and `lng` are defined, the results will be sorted by the place’s proximity to the defined location coordinates. This will override the `sort_by_alphabet` option.
preferred_language	❌ (Defaults to `en`)	User’s preferred language
q	❌	Search query (filter by name)
sort_by_alphabet	❌ (Defaults to `false`)	Unless `lat` and `lon` have been defined, setting this value to `true` will sort the results in place’s alphabetical order (including translations), instead of by the Region ID

The endpoint will return the following data:

Parameters (JSON)	Required	Description
status	✅	Will be either `OK` on success or `KO` on error
error	On error	Will be `INTERNAL` for unknown errors
data	On success	An array of `Region` objects. Learn more on Common Objects.

Self-Assessments

Get A List of Self-Assessments

GET http:///api/survey

Parameters (JSON)	Required	Description
index	🚫 (defaults to `1`, the minimum)	The index of the list. The response will be trimmed into a few results to avoid receiving large results for performing many self-assessments.

The endpoint will return the following data:

Parameters (JSON)	Required	Description
status	✅	Will be either `OK` on success or `KO` on error
error	On error	Will be `INTERNAL` for unknown errors
data	On success	A list of `Survey` objects. Learn more on Common Objects.
current_index	On success	The same value as the requested `index`. Use for endpoint confirmation purposes.
current_index	On success	Boolean value indicating that there are still more unlisted self-assessments performed by the user.

Create A New Self-Assessment

Perform the following request to create a new self-assessment:

POST http:///api/survey

Parameters (Form Data)	Required	Description
business_scale	✅	Business scale. `1` for start-ups, `2` for small enterprises, `3` for medium, and `4` for large enterprises
business_sector	✅	Business sector ID
region_id	✅	The business location in Region ID

The endpoint will return the following data:

Parameters (JSON)	Required	Description
status	✅	Will be either `OK` on success or `KO` on error
error	On error	Will be `INTERNAL` for unknown errors
data	On success	A `Survey` object. Learn more on Common Objects.

Update A Self-Assessment Session

Update a self-assessment session by performing the following request:

PUT/PATCH http:///api/survey/

Parameters (JSON)	Required	Description
business_scale	❌	Business scale. `1` for start-ups, `2` for small enterprises, `3` for medium, and `4` for large enterprises
business_sector	❌	Business sector ID
region_id	❌	The business location in Region ID

The endpoint will return the following data:

Parameters (JSON)	Required	Description
status	✅	Will be either `OK` on success or `KO` on error
error	On error	Will be `SURVEY_ALREADY_FINALIZED` if the session has already been finalized or `INTERNAL` for unknown errors
data	On success	An updated `Survey` object. Learn more on Common Objects.

Finalize the Self-Assessment Session

By finalizing the session, the user’s answers will be locked and submitted to generate their assessment report. Perform the following request to do so:

POST http:///api/survey/finalize/

The endpoint will return the following response:

Parameters (JSON)	Required	Description
status	✅	Will be either `OK` on success or `KO` on error
error	On error	Will be `INTERNAL` for unknown errors
data	On success	An updated `Survey` object. Learn more on Common Objects.

Statistics

Get Summary Line Chart Data

This endpoint generates the necessary data to build a line chart consisting of the average AEP score (from FINALIZED self-assessment attempts) collected over the past 5 years.

To get the necessary data to build the summary line chart, perform the following request:

POST http:///api/summary_line_chart_data

The endpoint will return the following response:

Parameters (JSON)	Required	Description
status	✅	Will be either `OK` on success or `KO` on error
error	On error	Will be `INTERNAL` for unknown errors
data	On success	A list of either `null` or a floating point, indicating the user’s average AEP score during the year. The list is sorted by descending year, starting with the first item indicating the data for the recent Gregorian year. The current maximum possible AEP score is *6 16 = 96**.

Get Survey Statistics

This endpoint provides statistics data for finalized survey attempts. To get the data, perform the following HTTP request:

GET http:///api/survey_statistics

Parameters (Query Parameter)	Required	Description
region_id	🚫	If given, the endpoint will mark the rank class of the specified self-assessment
survey_id	🚫	If given, the endpoint will mark the rank class of the specified self-assessment

The endpoint will return the following data:

Parameters (JSON)	Required	Description
status	✅	Will be either `OK` on success or `KO` on error
error	On error	Will be `SURVEY_NOT_FOUND` if the asked survey is not found, `SURVEY_UNFINISHED` if the survey itself has not been finalized, or `INTERNAL` for unknown errors
data	On success	A JSON containing the statistic data, which is defined below.

If successfull, the endpoint will return the following data:

{
    "overall": {},          // Overall (ASEAN)
    "overall_related": {},  // Overall (ASEAN), but the results are filtered by similar business sector and scale
    "national": {},         // National
    "national_related": {}, // National, but the results are filtered by similar business sector and scale
    "regional": {},         // Regional
    "regional_related": {}  // Regional,but the results are filtered by similar business sector and scale
}

Each value of the JSON keys above could be either null (no data) or another object describing the distribution of the scores:

[
    {
        "classes": [
            {
                "bottom_range": 43.5, // Bottom score range
                "top_range": 48.5,    // Highest score range
                "total": 37,          // Number of self-assessment sessions contained in this class
                "average": 46.37837837837838,       // The mean of the value
                "marked": false       // Does the survey, given by the survey_id parameter, is inside this class?
            },
            ... // (There are 5 )objects of same kind)
        ],
        "type": "aep_score",
    },
    {
        "classes": [...],
        "type": "dimen_1",
    },
    {
        "classes": [...],
        "type": "dimen_2",
    },
    {
        "classes": [...],
        "type": "dimen_3",
    },
    {
        "classes": [...],
        "type": "dimen_4",
    },
    {
        "classes": [...],
        "type": "indicator_1",
    },
    {
        "classes": [...],
        "type": "indicator_2",
    },
    {
        "classes": [...],
        "type": "indicator_3",
    },
    {
        "classes": [...],
        "type": "indicator_4",
    },
    {
        "classes": [...],
        "type": "indicator_5",
    },
    {
        "classes": [...],
        "type": "indicator_6",
    },
    {
        "classes": [...],
        "type": "indicator_7",
    },
    {
        "classes": [...],
        "type": "indicator_8",
    }
]

Common Objects

Laravel Sanctum Token

{
  "accessToken": {
    "name": "Device 1",                     // Same as `device_name` on SULI requests
    "abilities": ["*"],
    "expires_at": null|string,              // Should be in SQL DATETIME format
    "tokenable_id": 123,                    // Token ID
    "tokenable_type": "App\\Models\\User",
    "updated_at": "2022-11-18T03:37:48",    // Should be in SQL DATETIME format
    "created_at": "2022-11-18T03:37:48",    // Should be in SQL DATETIME format
    "id": 456                               // NOT User ID, obtain it from /api/user instead
  }
}

User

{
  "id": 123,                              // User ID
  "name": "User",
  "email": "user@example.com",
  "email_verified_at": null|string,        // Should be in SQL DATETIME format
  "two_factor_confirmed_at": null|string,  // Should be in SQL DATETIME format
  "updated_at": "2022-11-18T03:37:48",    // Should be in SQL DATETIME format
  "created_at": "2022-11-18T03:37:48",    // Should be in SQL DATETIME format
  "date_of_birth": "2001-12-31",          // YYYY-MM-DD
  "gender": 1,                            // 1 for male and 2 for female
  "region_id": null|string,               // The user's preferred region ID
  "default_region": undefined|Region       // The user's default region detail, as a Region object, if available
}

Business Sector

{
  "id": 1,                                                      // Business Sector ID
  "name": "Agriculture",                                        // Translated name
  "language" String|undefined,                                   // The language used in the business sector data translation. Defaults to `en` (English) if undefined.
  "created_at": "2022-05-11T09:19:33Z",                         // Should be in SQL DATETIME format
  "updated_at": "2022-05-11T09:19:33Z",                         // Should be in SQL DATETIME format
  "hint": "Agriculture, forestry, fisheries, plantations, etc.", // Category description (aka. "hint" in WizardStepChoice)
  "material_icon_id": null|string                               // String, for use with Material Icons (https://fonts.google.com/icons)
}

Region

{
  "id": "BN20",                         // Region ID
  "name": "Brunei",                     // Translated name
  "language" String|undefined,           // The language used in the region data translation. Defaults to `en` (English) if undefined.
  "admin_level": "2",                   // OpenStreetMap admin_level standard
  "parent_id": null|string,             // The ID of another Region with higher administrative level than this Region
  // The following data contains arbitrary, non-accurate coordinate values for:
  // C = Central (average of all points contained inside GeoJSON)
  // N = Northernmost
  // NE = Northeastmost
  // E = Eastmost
  // SE = Southeastmost
  // S = Southmost
  // SW = Southwestmost
  // W = Westmost
  // NW = Northwestmost
  "c_lat": 4.893648,
  "c_lng": 115.023381,
  "n_lat": 4.928261,
  "n_lng": 115.024104,
  "ne_lat": 4.910576,
  "ne_lng": 115.155341,
  "e_lat": 4.910576,
  "e_lng": 115.155341,
  "se_lat": 4.341919,
  "se_lng": 115.363303,
  "s_lat": 4.74818,
  "s_lng": 115.022028,
  "sw_lat": 4.142066,
  "sw_lng": 114.801317,
  "w_lat": 4.882855,
  "w_lng": 115.033786,
  "nw_lat": 4.951645,
  "nw_lng": 114.809474,
  "geojson": null,                        // Optional GeoJSON data
  "created_at": "2022-05-11T09:22:33Z",   // Should be in SQL DATETIME format
  "updated_at": "2022-05-11T09:22:33Z"    // Should be in SQL DATETIME format
}

Survey / Self Assessment

{
  {
    "id": 1771,
    "status": "DRAFT" | "FINISHED",               // DRAFT for unfinalized and FINISHED for finalized surveys
    "business_scale": 2,                          // 1 for start-ups, 2 for small, 3 for medium, and 4 for large enterprises
    "user_id": 1683,                              // The ID of the user initiating this self-assessment
    "region_id": "ID418",                         // The region ID of the user's business
    "business_sector_id": 6,                      // The ID of the BusinessSector
    "created_at": "2022-12-02T22:53:46.000000Z",  // Should be in SQL DATETIME format
    "updated_at": "2022-12-06T13:25:12.000000Z",  // Should be in SQL DATETIME format
    "age": 19,                                    // User's age at the time of creating/finalizing the survey
    "gender": 1,                                  // 1 for male and 2 for female
    "answers": Answer[],                          // List of filled answers, as an array of Answer object
    "business_sector": BusinessSector,            // The linked BusinessSector object
    "region": Region                              // The linked Region object
  }
}

Question

{
  "id": 82,                                     // The Question ID
  "name": "I'm capable of dealing complex...",  // The translated question
  "hint": String|null,                          // Additional, translated context hints to lead users understanding the given question or statement
  "language" String|undefined,                   // The language used in the question data translation. Defaults to `en` (English) if undefined.
  "created_at": "2022-05-11T09:19:36.000000Z",  // Should be in SQL DATETIME format
  "updated_at": "2022-05-11T09:19:36.000000Z"   // Should be in SQL DATETIME format
}

Answer

{
  "survey_id": 1771,                      
  "question_id": 82,
  "value": 3,
  "created_at": "2022-12-02T22:55:06.000000Z",
  "updated_at": "2022-12-02T22:55:06.000000Z",
  "question": Question                          // The linked Question object
}

New ASEAN Entrepreneurship Profiling API Docs

Authentication

Get CSRF/XSRF Token

Check Email

Sign Up / Create Account

Log In

Forgot Password

User Management

Get Current User Profile

Change User Profile

Account Closure

Request Account Closure (Step 1)

Confirm Account Closure (Step 2)

Demographic Data Lists

Get current list of business sectors

Get current list of countries

Search Regions

Self-Assessments

Get A List of Self-Assessments

Create A New Self-Assessment

Update A Self-Assessment Session

Finalize the Self-Assessment Session

Statistics

Get Summary Line Chart Data

Get Survey Statistics

Common Objects

Laravel Sanctum Token

User

Business Sector

Region

Survey / Self Assessment

Question

Answer