City List

Endpoint Overview

GET /api/v1/uae/city-list

Description

This endpoint retrieves a comprehensive list of cities in the United Arab Emirates (UAE) that are supported by the Vehicle Verification API. The returned data includes all major emirates and cities where vehicle verification services are available, enabling applications to present users with accurate location options for UAE-based vehicle verification requests.

Key Benefits

Provides a standardized list of UAE cities for consistent data collection in vehicle verification forms

Ensures applications only request vehicle verification in supported locations

Simplifies frontend implementation with ready-to-use city identifiers

Enables dynamic location-based service offerings within the UAE

Use Cases

Automotive

Insurance

Financial Services

Pre-populate dropdown menus in vehicle purchase/sale applications

Filter vehicle listings by city in automotive marketplaces

Customize vehicle verification requirements based on emirate-specific regulations

Technical Implementation

Authentication

All API requests require authentication using a JWT Bearer token. Authentication follows these steps:

Obtain API Credentials: Register with Surepass to receive your API key.

Generate JWT Token: Use your API key to generate a JWT token.

Include in Requests: Add the token to the Authorization header as Bearer TOKEN.

Different authentication tokens are used for sandbox and production environments:

Sandbox: https://sandbox.surepass.io

Production: https://kyc-api.surepass.io

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	JWT Bearer token for authentication. Format: `Bearer <your_jwt_token>`
Content-Type	Yes	Must be set to `application/json`

Request Body

This endpoint does not require a request body.

Process Response

Response Parameters

Parameter	Type	Description
data	array	List of supported UAE cities in snake_case format
status_code	integer	HTTP status code of the response (200 for success)
message_code	string	Short code indicating the result of the request
message	string	Human-readable description of the response status
success	boolean	Indicates whether the request was successful

Example Successful Response

{
    "data": [
        "abu_dhabi",
        "dubai",
        "sharjah",
        "ajman",
        "umm_al_quwain",
        "ras_al_khaimah",
        "fujairah"
    ],
    "status_code": 200,
    "message_code": "success",
    "message": "Success",
    "success": true
}

Possible Error Responses

Authentication Error

Server Error

{
    "status_code": 401,
    "message_code": "unauthorized",
    "message": "Invalid or expired token",
    "success": false
}

This error occurs when the JWT token is missing, invalid, or expired. Ensure you're using the correct token for the environment.

Integration Best Practices

Security Recommendations

Store JWT tokens securely and never expose them in client-side code

Implement token refresh mechanisms to handle token expiration gracefully

Use HTTPS for all API communications to ensure data security

Implement proper error handling to avoid exposing sensitive information

User Experience Guidelines

Cache the city list to reduce API calls and improve application performance

Present city names in a user-friendly format (e.g., "Dubai" instead of "dubai")

Implement search/filter functionality for city selection in applications with many form fields

Consider displaying cities in geographical order or by population size for better usability

Code Samples

cURL

Python

Node.js

Related APIs

Vehicle Verification API - Verifies vehicle details using registration information

License Plate Recognition API - Extracts and validates UAE license plate information

Vehicle Ownership Verification API - Confirms vehicle ownership details

Compliance and Legal Considerations

When using city data for vehicle verification, ensure compliance with UAE data protection laws and regulations. Vehicle verification services may have different requirements in different emirates, and users should be informed about data processing related to their vehicles in accordance with UAE Federal Law No. 45 of 2021 on Personal Data Protection.

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

{ "data": [ "abu_dhabi", "dubai", "sharjah", "ajman", "umm_al_quwain", "ras_al_khaimah", "fujairah" ], "status_code": 200, "message_code": "success", "message": "Success", "success": true }

City List

City List#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request

Responses

City List

Description

Use Cases

Technical Implementation

Request Headers

Request Body

Response Parameters

Example Successful Response

Possible Error Responses

Integration Best Practices

Code Samples