Welcome to the IRIS Network API Documentation

The External API provides programmatic access to EV charging infrastructure data, including tariffs, customers, stations, charging sessions, and real-time charger status.

API Configuration

Configure your API credentials below to test endpoints directly from this page.

Select the environment (Sandbox or Production) for all API requests
Your API key is stored locally in your browser and never sent to our servers. Format: iris_...
Tip: Once configured, you can test any endpoint below by clicking "Try it out" and filling in the parameters.

Table of Contents

Overview

✨ Key Features

Secure Authentication

API key-based authentication with tenant isolation

RESTful Design

Standard HTTP methods and status codes

Geospatial Queries

Find chargers within a specified radius

Advanced Search

Search and filtering capabilities

Comprehensive Data

Access to all charging infrastructure data

Pagination Support

Efficient data retrieval with pagination

Authentication

Important: All API requests require authentication using an API key.

🔑 API Key Format

iris_your_encrypted_key

🛠️ Authentication Methods

Method Example Status
x-api-key Header x-api-key: iris_<key> ✅ Recommended
Bearer Token Authorization: Bearer iris_<key> ✅ Alternative

📥 Getting an API Key

  1. Log in to the IRIS Network admin portal
  2. Navigate to Settings > System configuration > API Key
  3. Create a new API key with appropriate permissions
  4. Copy the generated key (shown only once!)
  5. Store it securely

🛡️ Security Best Practices

Never Expose Keys

Never expose API keys in client-side code or repositories

Rotate Regularly

Rotate keys regularly for enhanced security

Environment Separation

Use different keys for dev/prod environments

Monitor Usage

Monitor key usage through audit logs

API Endpoints

Base URL: BASE_URL = https://scncumk77d.execute-api.ap-south-1.amazonaws.com/suite-network-uat/api/v1/d2s/external

📌 Common Query Parameters

Parameter Type Description Default
page integer Page number for pagination 1
pagesize integer Number of items per page 10
search string Search term (relevant fields) -
sortby string Field to sort by varies
orderby string Sort order: ASC or DESC ASC

Tariffs

💰 Tariff Management

Manage tariff plans and their associated rules

GET

GET BASE_URL/tariffs

Get Tariff List
Full URL: BASE_URL/tariffs

Retrieve a paginated list of tariff plans with their associated rules.

Query Parameters

Parameter Required Description
type No Filter by tariff type
isactive No Filter by active status

Example Request

curl -X GET "BASE_URL/tariffs?page=1&pagesize=10" \ -H "x-api-key: iris_your_key"

Try it out

Fill in the parameters below and click "Send Request" to test this endpoint live.
Query Parameters
type (optional)
Filter by tariff type
isactive (optional)
Filter by active status
page (optional)
Page number for pagination
pagesize (optional)
Number of items per page (1-100)

Example Response

{ "error": false, "message": "Tariff List Found Successfully", "data": [ { "id": 2, "name": "Standard Tariff", "type": "ENERGY_BASED", "isactive": true, "connection_fee": 5 } ], "data_count": 10 }
GET

GET BASE_URL/tariffs/:id

Get Single Tariff
Full URL: BASE_URL/tariffs/{id}

Retrieve detailed information about a specific tariff plan.

Path Parameters

Parameter Required Description
id Yes Tariff plan ID (integer)

Example Request

curl -X GET "BASE_URL/tariffs/2" \ -H "x-api-key: iris_your_key"

Try it out

Enter the tariff ID to retrieve detailed information.
Path Parameters
id *
The unique identifier of the tariff plan

Customers

👥 Customer Management

Access and manage customer information

GET

GET BASE_URL/customers

Get Customer List
Full URL: BASE_URL/customers

Retrieve a paginated list of customers.

Query Parameters

Parameter Required Description
search No Search by name, phone, or email
page No Page number (default: 1)
pagesize No Items per page (default: 10)

Example Request

curl -X GET "BASE_URL/customers?search=john&page=1&pagesize=10" \ -H "x-api-key: iris_your_key"

Try it out

Search and filter customers using the parameters below.
Query Parameters
search (optional)
Search by name, phone, or email
page (optional)
Page number (default: 1)
pagesize (optional)
Items per page (default: 10)

Example Response

{ "error": false, "message": "Customer List Found Successfully", "data": [ { "id": "user123", "name": "John Doe", "email": "john.doe@example.com", "phone": "+1234567890", "is_active": true } ], "data_count": 50 }
GET

GET BASE_URL/customers/:id

Get Single Customer
Full URL: BASE_URL/customers/{id}

Retrieve detailed information about a specific customer.

Path Parameters

Parameter Required Description
id Yes Customer ID (string, e.g., "user123")

Example Request

curl -X GET "BASE_URL/customers/user123" \ -H "x-api-key: iris_your_key"

Try it out

Enter the customer ID to retrieve detailed information.
Path Parameters
id *
The unique identifier of the customer

Stations

⚡ Charging Stations

Access station details, charge points, and connectors

GET

GET BASE_URL/stations

Get Station List
Full URL: BASE_URL/stations

Retrieve a paginated list of charging stations with their charge points and connectors.

Query Parameters

Parameter Required Description
city No Filter by city
state No Filter by state
always_open No Filter by always open status
search No Search by name, address, city, or state

Example Request

curl -X GET "BASE_URL/stations?city=Mumbai&page=1&pagesize=10" \ -H "x-api-key: iris_your_key"

Try it out

Filter and search for charging stations using the parameters below.
Query Parameters
city (optional)
Filter by city name
state (optional)
Filter by state/province
always_open (optional)
Filter by 24/7 availability
search (optional)
Search by name, address, city, or state
page (optional)
Page number for pagination
pagesize (optional)
Number of items per page

Example Response

{ "error": false, "message": "Station List Found Successfully", "data": [ { "id": 1, "name": "Mumbai Central Station", "latitude": 19.0760, "longitude": 72.8777, "city": "Mumbai", "state": "Maharashtra", "is_active": true } ], "data_count": 25 }
GET

GET BASE_URL/stations/:id

Get Single Station
Full URL: BASE_URL/stations/{id}

Retrieve detailed information about a specific station including all charge points and connectors.

Path Parameters

Parameter Required Description
id Yes Station ID (integer)

Example Request

curl -X GET "BASE_URL/stations/1" \ -H "x-api-key: iris_your_key"

Try it out

Enter the station ID to retrieve detailed information including charge points and connectors.
Path Parameters
id *
The unique identifier of the charging station

Sessions

🔌 Charging Sessions

Access historical and current charging sessions

GET

GET BASE_URL/sessions

Get Session List
Full URL: BASE_URL/sessions

Retrieve a paginated list of charging sessions.

Key Filters

Parameter Required Description
start_date No Start date filter (YYYY-MM-DD HH:MM:SS)
end_date No End date filter (YYYY-MM-DD HH:MM:SS)
status No Session status (STARTED, STOPPED, FAILED)
charge_station_id No Filter by station ID
user_id No Filter by customer ID

Example Request

curl -X GET "BASE_URL/sessions?start_date=2024-01-01&end_date=2024-12-31&status=STOPPED&page=1&pagesize=10" \ -H "x-api-key: iris_your_key"

Try it out

Filter charging sessions by date range, status, station, or customer.
Query Parameters
start_date (optional)
Start date filter (format: YYYY-MM-DD HH:MM:SS)
end_date (optional)
End date filter (format: YYYY-MM-DD HH:MM:SS)
status (optional)
Filter by session status
charge_station_id (optional)
Filter by specific station ID
user_id (optional)
Filter by customer ID
page (optional)
Page number for pagination
pagesize (optional)
Number of items per page
GET

GET BASE_URL/sessions/:id

Get Single Session
Full URL: BASE_URL/sessions/{id}

Retrieve detailed information about a specific charging session.

Path Parameters

Parameter Required Description
id Yes Session ID (integer)

Example Request

curl -X GET "BASE_URL/sessions/12345" \ -H "x-api-key: iris_your_key"

Try it out

Enter the session ID to retrieve detailed information about a specific charging session.
Path Parameters
id *
The unique identifier of the charging session

Charger Status

📍 Geospatial Charger Status

Find available chargers near a location

GET

GET BASE_URL/chargers/status

Get Charger Status within Radius
Full URL: BASE_URL/chargers/status

Retrieve a list of chargers within a specified radius from given coordinates.

Query Parameters

Parameter Required Description
lat ✅ Yes Latitude (-90 to 90)
lng ✅ Yes Longitude (-180 to 180)
radius ✅ Yes Radius distance (> 0)
radius_unit ❌ No km (default) or m

Example Request

curl -X GET "BASE_URL/chargers/status?lat=19.0760&lng=72.8777&radius=5&radius_unit=km" \ -H "x-api-key: iris_your_key"

Try it out

Find available chargers within a specified radius from given coordinates. Results are sorted by distance (nearest first).
Query Parameters
lat *
Latitude coordinate (-90 to 90)
lng *
Longitude coordinate (-180 to 180)
radius *
Search radius distance (must be greater than 0)
radius_unit (optional)
Unit for radius: "km" (default) or "m"
Notes:
  • ✅ Results sorted by distance (nearest first)
  • ✅ Only active, published stations included
  • ✅ Availability based on heartbeat interval

Request/Response Formats

Request Headers

Content-Type: application/json x-api-key: iris_your_key

Response Format

✅ Success Response

{ "error": false, "message": "Success message", "data": [...], "data_count": 100 }

❌ Error Response

{ "error": true, "message": "Error description", "code": 400 }

HTTP Status Codes

200
Success
400
Bad Request
401
Unauthorized
404
Not Found
429
Rate Limit
500
Server Error

Error Handling

Common Error Codes

Error Code Description Solution
MISSING_API_KEY API key not provided Include x-api-key header
INVALID_API_KEY Invalid or expired key Generate new API key
INVALID_KEY_FORMAT Incorrect format Use iris_<key> format
RATE_LIMIT_EXCEEDED Too many requests Wait and retry

Rate Limiting

100
requests per minute
20
requests per second (burst)

Rate Limit Response

{ "error": true, "message": "Rate limit exceeded", "code": 429, "retry_after": 60 }

Best Practices

🔐 Security

  • Store keys in environment variables
  • Never commit keys to version control
  • Use HTTPS always
  • Monitor key usage

⚡ Performance

  • Use pagination (10-50 items)
  • Cache frequently accessed data
  • Filter data server-side
  • Implement retry with backoff

📊 Data Management

  • Only request needed data
  • Use search/filter parameters
  • Cache static data
  • Implement incremental sync

Code Examples

Tip: Click the copy button on any code block to copy it to your clipboard.

JavaScript/Node.js

const axios = require('axios');
const BASE_URL = 'https://api.example.com/api/v1/external';
const API_KEY = 'iris_your_key';

async function getTariffs() {
  try {
    const response = await axios.get(`${BASE_URL}/tariffs`, {
      headers: { 'x-api-key': API_KEY },
      params: { page: 1, pagesize: 10 }
    });
    console.log('✅ Success:', response.data);
  } catch (error) {
    console.error('❌ Error:', error.response?.data || error.message);
  }
}

async function getCustomers(searchTerm) {
  try {
    const response = await axios.get(`${BASE_URL}/customers`, {
      headers: { 'x-api-key': API_KEY },
      params: { search: searchTerm, page: 1, pagesize: 10 }
    });
    return response.data;
  } catch (error) {
    console.error('❌ Error:', error.response?.data || error.message);
  }
}

Python

import requests

BASE_URL = 'https://api.example.com/api/v1/external'
API_KEY = 'iris_your_key'

headers = {'x-api-key': API_KEY}

def get_tariffs():
    """Get paginated tariff list"""
    response = requests.get(
        f'{BASE_URL}/tariffs',
        headers=headers,
        params={'page': 1, 'pagesize': 10}
    )
    if response.status_code == 200:
        return response.json()
    else:
        print(f"Error {response.status_code}: {response.text}")
        return None

def get_stations(city=None):
    """Get stations filtered by city"""
    params = {'page': 1, 'pagesize': 10}
    if city:
        params['city'] = city
    
    response = requests.get(
        f'{BASE_URL}/stations',
        headers=headers,
        params=params
    )
    return response.json()

cURL Examples

# Get tariff list
curl -X GET "https://api.example.com/api/v1/external/tariffs?page=1&pagesize=10" \
  -H "x-api-key: iris_your_key"

# Get customer list (search for John)
curl -X GET "https://api.example.com/api/v1/external/customers?search=john&page=1&pagesize=10" \
  -H "x-api-key: iris_your_key"

# Get station list in Mumbai
curl -X GET "https://api.example.com/api/v1/external/stations?city=Mumbai&page=1&pagesize=10" \
  -H "x-api-key: iris_your_key"

# Get charger status near Mumbai
curl -X GET "https://api.example.com/api/v1/external/chargers/status?lat=19.0760&lng=72.8777&radius=5" \
  -H "x-api-key: iris_your_key"