Skip to content

ISP Flow

This document outlines the workflow and endpoints required for managing Internet Service Provider (ISP) operations. Below are the steps involved, along with descriptions of each endpoint, parameters, and example responses.

Overview

The ISP Flow is a process that enables the creation of services and customers within the AEx system. This includes several key steps such as:

  1. Customer Creation: Registering new customers in AEx.
  2. Check Customer: Verifying if a customer already exists in AEx.
  3. Predefine-Premise Lookup: Looking up predefined premises linked to a customer's address.
  4. Product Availability: Checking if the desired products or services are available at the customer's location.
  5. Service Creation: Activating a service for a customer after verification.
  6. Retrieve Premise Details: Check premise details.
  7. Retrieve Service Details: check service details.

This flow includes processes such as creating accounts, Creating services, looking up premise.

NOTE: please contact your SDM for a TOKEN to be used for the below endpoints.


Step 1: Customer Sign-up

Endpoint: POST /customers

  • Description: This endpoint is used to register a new customer as an ISP.
    This includes collecting necessary customer details for account creation.

  • Request Parameters:

    • first_name (string, required): The customer's first name.
    • last_name (string, required): The customer's last name.
    • email (string, required): The customer's email address.
    • password (string, required): The customer's password.
    • mobile_number (string, required): The customer's mobile phone number.
    • home_number (string, optional): The customer's home phone number.

Example cURL Request:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
curl --location 'https://preprod.fno.dev.aex.systems/customers' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_TOKEN_HERE' \
--data-raw '{
  "customer": {
    "first_name": "String",
    "last_name": "String",
    "email": "String",
    "password": "string",
    "mobile_number": "String",
    "home_number": "String"
  }
}'

Example Request:

{
  "customer": {
    "first_name": "String",
    "last_name": "String",
    "email": "String",
    "username": "string",
    "password": "string",
    "mobile_number": "String",
    "home_number": "String"
  }
}

Example Responses:

  1. 201 Created: No response body.

  2. 400 Bad Request: If a customer already exists within AEx, the below error will occur.
    Continue to - Check Customer to return the correct customer Guid.

    {
        "code": 400,
        "errors": {
            "email": [
                "is already taken"
            ]
        },
        "full_errors": [
            "email is already taken"
        ]
    }
    
  3. 401 Unauthorized: You do not have access; please contact your SDM for a Token.

    1
    2
    3
    4
    5
    6
    {
        "code": 401,
        "errors": [
            "Not Authenticated"
        ]
    }
    


Step 2: Check Customer

Endpoint: GET /customers

  • Description: This endpoint checks if a customer exists in the ISP system by using either their ID or email address. It retrieves the necessary customer details based on the provided identifier.

  • Request Parameters:

    • q (string, required): The customer's email used for querying.
    • count (integer, optional): The number of results to return (default is 10).
    • page (integer, optional): The page number of results to return (default is 1).
  • Example cURL Request 1: Based on email

    1
    2
    3
    curl --location 'https://preprod.fno.dev.aex.systems/customers?q=testmail@test.co.za&count=10&page=1' \
    --header 'Authorization: Bearer YOUR_TOKEN_HERE' \
    --header 'Cookie: _Ditty_session=YOUR_SESSION_COOKIE'
    
  • Example cURL Request 2: Based on customer GUID

    1
    2
    3
    curl --location 'https://preprod.fno.dev.aex.systems/customers/FC65F24E-AADD-440E-AF96-9CBBDFA50349' \
    --header 'Authorization: Bearer YOUR_TOKEN_HERE' \
    --header 'Cookie: _Ditty_session=YOUR_SESSION_COOKIE'
    

Example Responses:

  1. 200 OK: Returns customer details.

    {
        "id": "FC65F24E-AADD-440E-AF96-9CBBDFA50349",
        "parent_id": "AEEF38C0-F1E9-4E83-AD4F-3E35AAB8DFCF",
        "portal_user_id": "AABDE29F-B2B2-456F-916E-699D0BD28CFC",
        "first_name": "string",
        "last_name": "string",
        "business_name": null,
        "email": "string",
        "username": "string",
        "mobile_number": "string",
        "home_number": "string",
        "work_number": null,
        "external_reference": null,
        "fno_opt_in": null,
        "isp_opt_in": null,
        "opt_in_ip_address": null,
        "vat_number": null,
        "identity_number": null,
        "registration_number": null,
        "billing_address": null,
        "billing_suburb": null,
        "billing_city": null,
        "billing_postal_code": null,
        "billing_province": null,
        "billing_country": null,
        "physical_address": null,
        "physical_suburb": null,
        "physical_city": null,
        "physical_postal_code": null,
        "physical_province": null,
        "physical_country": null,
        "service_provider_flag": false,
        "fax_number": null,
        "nationality": null,
        "identification_type_id": null,
        "created_at": "2024-10-17 13:42:49 +0200",
        "updated_at": "2024-10-17 13:42:49 +0200",
        "enabled": true,
        "alternative_number": null,
        "preferred_contact_method": null,
        "comments": null,
        "preferred_contact_time": null
    }
    
  2. 401 Unauthorized: You do not have access; please contact your SDM for a Token.

    1
    2
    3
    4
    5
    6
    {
        "code": 401,
        "errors": [
            "Not Authenticated"
        ]
    }
    

Step 3: Predefine Premise Lookup

Endpoint: GET /predefined-premises

  • Description: This endpoint retrieves a list of predefined premises based on a search query. It allows filtering by name and location and supports pagination.

  • Request Parameters:

    • q (string, required): The search query string for the premises (e.g., address).
    • count (integer, optional): The number of results to return per page (default is 10, maximum is 100).
    • page (integer, optional): The page number of results to return (default is 1).

Example cURL Request:

1
2
3
curl --location 'https://preprod.fno.dev.aex.systems/predefined-premises?count=100&page=1&q=38 (Cottage), Railway Street, Hectorton, Randfontein, ZA, 1765, Gauteng' \
   --header 'Authorization: Bearer YOUR_TOKEN_HERE' \
   --header 'Cookie: _Ditty_session=YOUR_SESSION_COOKIE'

Example Responses:

  1. 200 OK: Returns Predefine premise details.

    {
    "items": [
        {
            "id": 1616056,
            "guid": "66E9BB4D-E360-4F40-A30E-AF27F52392B6",
            "full_text": "38 , David Road (Cottage), Oaktree, Krugersdorp, ZA, 1739, Gauteng",
            "latitude": -26.038965,
            "longitude": 27.738254,
            "operator_id": "AEEF38C0-F1E9-4E83-AD4F-3E35AAB8DFCF",
            "premise_id": "783D71D3-B0A4-4C90-8392-C43294A976DC",
            "updated_at": "2023-07-05T11:02:23+02:00",
            "created_at": "2023-07-05T11:02:23+02:00",
            "deleted_at": null,
            "area_id": "9F961EB9-4D8D-4917-A9C5-56EA835E2C74"
        },
        {
            "id": 2554308,
            "guid": "6E865394-5B48-4403-8D80-741D1F7E43DD",
            "full_text": "12, Varing Street(Cottage), Homelake, Randfontein, ZA, 1759, Gauteng",
            "latitude": -26.1813322,
            "longitude": 27.6936082,
            "operator_id": "AEEF38C0-F1E9-4E83-AD4F-3E35AAB8DFCF",
            "premise_id": "3FB9D64F-1C58-4439-9277-64757FBCC6BD",
            "updated_at": "2024-06-04T12:39:12+02:00",
            "created_at": "2024-06-04T12:39:12+02:00",
            "deleted_at": null,
            "area_id": "5941F0BE-2A6E-4329-8338-547F161816C2"
        }
    }
    
  2. 401 Unauthorized: You do not have access; please contact your SDM for a Token.

    1
    2
    3
    4
    5
    6
    {
        "code": 401,
        "errors": [
            "Not Authenticated"
        ]
    }
    

Step 4: Product availability

Endpoint: GET /products/availability/{latitude}/{longitude}

  • Description: This endpoint retrieves a list of available products based on the specified latitude and longitude. It provides information about the products offered in that geographic area.

  • Request Parameters:

    • latitude (float, required): The latitude of the location to lookup products (e.g., -29.7872215658).
    • longitude (float, required): The longitude of the location to lookup products (e.g., 30.9834343322).

Example cURL Request:

1
2
3
curl --location 'https://preprod.fno.dev.aex.systems/products/availability/-29.7872215658/30.9834343322' \
--header 'Authorization: Bearer YOUR_TOKEN_HERE' \
--header 'Cookie: _Ditty_session=YOUR_SESSION_COOKIE'

Example Responses:

  1. 200 OK: Returns product details.

    {
        "items": [
            {
                "id": "C567389A-2D36-4C29-AD46-0EC3D7A7D0EA",
                "provider_id": "40B2AAA0-96A7-4856-BA35-90E6B0D1C4B6",
                "parent_id": "452C55AD-16F0-4248-A745-E270BB44590C",
                "name": "ips product 10/2 Mbps",
                "description": "ips product 10/2 Mbps",
                "speed_up": 2,
                "speed_down": 10,
                "min_contract": 1,
                "effective_date": "2023-09-04 00:00:00 +0200",
                "status": "Active",
                "type_name": "ISP",
                "provider": "MockIsp",
                "pricing": [
                    {
                        "id": "E6A396D4-8C0E-48E2-8008-48AC13F04CFA",
                        "price_type": "Monthly",
                        "currency_code": "ZAR",
                        "tax": 15.0,
                        "value": 477.3913,
                        "value_incl": 549.0
                    }
                ],
                "logo": "/Images/Logos/308FCA5F-3E46-468B-891C-97A986E45677.jpg"
            },
            {
                "id": "D728F54D-5769-4833-B168-12B1E86D3CAF",
                "provider_id": "40B2AAA0-96A7-4856-BA35-90E6B0D1C4B6",
                "name": "School Service",
                "speed_up": 10,
                "speed_down": 1000,
                "min_contract": 1,
                "effective_date": "2020-04-30 00:00:00 +0200",
                "status": "Active",
                "type_name": "ISP",
                "provider": "MockIsp",
                "pricing": []
            }
        ]
    }
    
  2. 401 Unauthorized: You do not have access; please contact your SDM for a Token.

    1
    2
    3
    4
    5
    6
    {
        "code": 401,
        "errors": [
            "Not Authenticated"
        ]
    }
    

Step 5: Service Creation

Endpoint: POST /services/full

  • Description: This endpoint creates a new service by providing customer details, premise information, and service product details.

  • Request Body:

    • customer: Object containing customer details.
      • id (string, required): Unique identifier for the customer (e.g., "4348AEF7-AD89-4309-AC29-DCB621C308CF").
      • first_name (string, required): Customer's first name (e.g., "Customer20241008").
      • last_name (string, required): Customer's last name (e.g., "Customer20241008").
      • email (string, required): Customer's email address (e.g., "Customer20241008@postmantest.co.za").
      • username (string, required): Customer's username (e.g., "Customer20241008@postmantest.co.za").
      • mobile_number (string, required): Customer's mobile number (e.g., "1234567895").
    • premise: Object containing premise details.
      • external_reference (string, required): Unique reference for the premise (e.g., "287C94C4-0196-4999-9348-15ACC0EE7A0A").
    • service: Object containing service product details.
      • product_id (string, required): Unique identifier for the service product (e.g., "50726131-B525-4732-A2D5-0B3736CDFB69").

Example cURL Request:

curl --location 'https://preprod.fno.dev.aex.systems/services/full' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_TOKEN_HERE' \
--header 'Cookie: _Ditty_session=YOUR_SESSION_COOKIE' \
--data-raw '{
    "customer": {
        "id": "4348AEF7-AD89-4309-AC29-DCB621C308CF",
        "first_name": "String",
        "last_name": "String",
        "email": "String",
        "username": "String",
        "mobile_number": "String"
    },
    "premise": {
        "external_reference": "287C94C4-0196-4999-9348-15ACC0EE7A0A" // guid from predefine-premise
    },
    "service": {
        "product_id": "50726131-B525-4732-A2D5-0B3736CDFB69" // guid from products
    }
}'

Example Request:

{
"customer": {
    "id": "4348AEF7-AD89-4309-AC29-DCB621C308CF",
    "first_name": "String",
    "last_name": "String",
    "email": "String",
    "username": "String",
    "mobile_number": "String"
        },
        "premise": {
            "external_reference": "287C94C4-0196-4999-9348-15ACC0EE7A0A" // guid from predefine-premise
        },
        "service": {
            "product_id": "50726131-B525-4732-A2D5-0B3736CDFB69" // guid from products
        }
    }

  1. 201 Created: Returns the details of the created service.

    {
        "customer": {
            "id": "4348AEF7-AD89-4309-AC29-DCB621C308CF"
        },
        "premise": {
            "external_reference": "287C94C4-0196-4999-9348-15ACC0EE7A0A"
        },
        "service": {
            "service_id": "50726131-B525-4732-A2D5-0B3736CDFB69"
        }
    }
    
  2. 401 Unauthorized: You do not have access; please contact your SDM for a Token.

    1
    2
    3
    4
    5
    6
    {
        "code": 401,
        "errors": [
            "Not Authenticated"
        ]
    }
    
    2. 400 Bad Request: Invalid request data; currently only returns Unauthorized on failure.

    1
    2
    3
    4
    5
    6
    {
        "code": 401,
        "errors": [
            "Not Authenticated"
        ]
    }
    

Step 6: Retrieve Premise Details

Endpoint: GET /premises/{premiseId}

  • Description: This endpoint retrieves the details of a specific premise using its unique premise ID.

  • Request Parameters:

    • premiseId (string, required): The unique ID of the premise to retrieve (e.g., 4BF2A897-A38C-4D24-82C6-F2184C8832E4).
  • Example cURL Request:

    1
    2
    3
    curl --location 'https://preprod.fno.dev.aex.systems/premises/4BF2A897-A38C-4D24-82C6-F2184C8832E4' \
    --header 'Authorization: Bearer YOUR_TOKEN_HERE' \
    --header 'Cookie: _Ditty_session=YOUR_SESSION_COOKIE'
    

Example Responses:

  1. 200 OK: Returns product details.

    {
        "id": "B002A6B4-6541-47A5-8438-BE8ACEAA6D82",
        "area_id": "548F9777-D0F9-45A3-A2A7-A352583456E6",
        "latitude": -29.7852390438,
        "longitude": 30.9828323552,
        "reference": null,
        "external_reference": "287C94C4-0196-4999-9348-15ACC0EE7A0A",
        "asset_reference": null,
        "mdu_block": null,
        "mdu_floor": null,
        "plot_number": null,
        "street_number": "9",
        "street_name": "Pompano Place",
        "intersection": null,
        "suburb": "Newlands",
        "city": "Durban",
        "country_code": "ZA",
        "postal_code": "4037",
        "province": "Kwazulu Natal",
        "mdu_name": null,
        "mdu_unit": null,
        "customer_id": "4348AEF7-AD89-4309-AC29-DCB621C308CF",
        "name": "AutoCreated_ 19653",
        "type_id": null,
        "created_at": "2024-10-08 13:19:29 +0200",
        "updated_at": "2024-10-08 13:19:29 +0200",
        "status": "Has Existing Service"
    }
    
  2. 401 Unauthorized: You do not have access; please contact your SDM for a Token.

    1
    2
    3
    4
    5
    6
    {
        "code": 401,
        "errors": [
            "Not Authenticated"
        ]
    }
    
  3. 404 Not Found: The specified premise ID does not exist.

    1
    2
    3
    4
    5
    6
    {
        "code": 404,
        "errors": [
            "not found"
        ]
    }
    

Step 7: Retrieve Service Details

Endpoint: GET /services/{serviceId}

  • Description: This endpoint retrieves the details of a specific service using its unique service ID.

  • Request Parameters:

    • serviceId (string, required): The unique ID of the service to retrieve (e.g., 34A39B28-8547-4853-9CAC-56F168EDE9D2).
  • Example cURL Request:

    1
    2
    3
    curl --location 'https://preprod.fno.dev.aex.systems/services/34A39B28-8547-4853-9CAC-56F168EDE9D2' \
    --header 'Authorization: Bearer YOUR_TOKEN_HERE' \
    --header 'Cookie: _Ditty_session=YOUR_SESSION_COOKIE'
    

Example Responses:

  1. 200 OK: Returns product details.

    {
        "id": "B002A6B4-6541-47A5-8438-BE8ACEAA6D82",
        "area_id": "548F9777-D0F9-45A3-A2A7-A352583456E6",
        "latitude": -29.7852390438,
        "longitude": 30.9828323552,
        "reference": null,
        "external_reference": "287C94C4-0196-4999-9348-15ACC0EE7A0A",
        "asset_reference": null,
        "mdu_block": null,
        "mdu_floor": null,
        "plot_number": null,
        "street_number": "9",
        "street_name": "Pompano Place",
        "intersection": null,
        "suburb": "Newlands",
        "city": "Durban",
        "country_code": "ZA",
        "postal_code": "4037",
        "province": "Kwazulu Natal",
        "mdu_name": null,
        "mdu_unit": null,
        "customer_id": "4348AEF7-AD89-4309-AC29-DCB621C308CF",
        "name": "AutoCreated_ 19653",
        "type_id": null,
        "created_at": "2024-10-08 13:19:29 +0200",
        "updated_at": "2024-10-08 13:19:29 +0200",
        "status": "Has Existing Service"
    }
    
  2. 401 Unauthorized: You do not have access; please contact your SDM for a Token.

    1
    2
    3
    4
    5
    6
    {
        "code": 401,
        "errors": [
            "Not Authenticated"
        ]
    }
    
  3. 404 Not Found: The specified premise ID does not exist.

    1
    2
    3
    4
    5
    6
    {
        "code": 404,
        "errors": [
            "not found"
        ]
    }
    

Check customer service

Endpoint: GET /customers/{customerId}/services

  • Description: This endpoint retrieves current service(s) that is linked to a customer.

  • Request Parameters:

    • customerId (string, required): The unique ID of the customerId to retrieve (e.g., 34A39B28-8547-4853-9CAC-56F168EDE9D2).
  • Example cURL Request:

    1
    2
    3
    curl --location 'https://preprod.fno.dev.aex.systems/customers/8DC17240-9312-4EE0-A313-CF519657E2D3/services' \
    --header 'Authorization: Bearer YOUR_TOKEN_HERE' \
    --header 'Cookie: _Ditty_session=YOUR_SESSION_COOKIE'
    

Example Responses:

  1. 200 OK: Returns service details.

    {
        "items":
        [
          {
           "id":"533EE0A6-7279-415B-9ED1-191BC406AB9D",
           "customer_id":"8DC17240-9312-4EE0-A313-CF519657E2D3",
           "product_id":"AD0B8EFA-20ED-41E2-BFCF-D48761CA82F8",
           "provider_id":"78029096-2916-4773-A281-4F8331A853DB",
           "premise_id":"FA8909FA-2C81-450E-AD9F-62A689623896",
           "preorder":false,"isp_reference":null,
           "reference_code":null,
           "port_number":"1",
           "pppoe_username":"533EE0A67279415B9ED1191BC406AB9D@bb.openfiberusa.com",
           "pppoe_password":"LKNY0DE1P",
           "pppoe_ip_address":null,
           "wifi_username":"RippleFiber_ID3Y",
           "wifi_password":"30e97e3c78",
           "provisioned":false,
           "provisioned_date":"2024-10-16 13:07:42 +0200",
           "on_network":false,
           "on_network_date":"2024-10-16 13:07:42 +0200",
           "completed":false,
           "completed_date":"2024-10-16 13:07:42 +0200",
           "cancelled":false,
           "cancelled_date":null,
           "expiry_date":null,
           "promo_code":null,
           "sales_agent":null,
           "sales_channel_id":null,
           "termination_cause_id":null,
           "deleted_at":null,
           "created_at":"2024-10-16 13:05:30 +0200",
           "auto_configured":null,
           "cancellation_reason":null,
           "status_id":2,
           "start_date":null,
           "config_info":"<config_info><enable_band_steering>true</enable_band_steering></config_info>",
           "suspended_date":null,
           "updated_at":"2024-10-16 13:05:30 +0200",
           "created_by_id":null,
           "dhcp_enabled":false,
           "rica_validated":null,
           "last_network_check":null,
           "level":null,
           "service_configuration_id":1,
           "ip_v4_public":null,
           "ip_v6_public":null,
           "pppoe_v6_address":null,
           "deleted_date":null
          }
         ],
     "total":1
    }
    
  2. 401 Unauthorized: You do not have access; please contact your SDM for a Token.

    1
    2
    3
    4
    5
    6
    {
        "code": 401,
        "errors": [
            "Not Authenticated"
        ]
    }
    
  3. 404 Not Found: The specified premise ID does not exist.

    1
    2
    3
    4
    5
    6
    {
        "code": 404,
        "errors": [
            "not found"
        ]
    }
    

Check customer service work order

Endpoint: GET /work-orders?service={serviceId}

  • Description: This endpoint retrieves current work-order(s) for the given service.

  • Request Parameters:

    • serviceId (string, required): The unique ID of the serviceId to retrieve (e.g., 34A39B28-8547-4853-9CAC-56F168EDE9D2).
  • Example cURL Request:

    1
    2
    3
    curl --location 'https://preprod.fno.dev.aex.systems/work-orders?service=533EE0A6-7279-415B-9ED1-191BC406AB9D' \
    --header 'Authorization: Bearer YOUR_TOKEN_HERE' \
    --header 'Cookie: _Ditty_session=YOUR_SESSION_COOKIE'
    

Example Responses:

  1. 200 OK: Returns work-order details.

    {
        "items":
        [
          {
           "guid": "796712E9-36BE-4510-B9BE-607B721AD551",
           "id": "796712E9-36BE-4510-B9BE-607B721AD551",
           "type_id": 1,
           "account_id": "533EE0A6-7279-415B-9ED1-191BC406AB9D",
           "reference": "20241016-399307266",
           "on_hold": false,
           "completed_date": null,
           "close_date": null,
           "schedule_date": null,
           "schedule_time": null,
           "scheduled_date_time": null,
           "external_reference": null,
           "device_specified": false,
           "category": null,
           "updated_at": "2024-10-16 13:05:30 +0200",
           "last_update_date": "2024-10-16 13:05:30 +0200",
           "created_at": "2024-10-16 13:05:30 +0200",
           "start_date": "2024-10-16 13:05:30 +0200",
           "status_id": "34A8DC44-7B32-40FF-8F95-FA415BB8D82A",
           "assigned_id": null,
           "assigned_user_id": null,
           "installer_id": null,
           "created_by_id": "97E84EDE-39AC-4324-817F-4ADD8623EFC4",
           "disable_auto_wo_creation": false,
           "summary": null,
           "description": null,
           "status": "New Order",
           "type": "Installation",
           "service_id": "533EE0A6-7279-415B-9ED1-191BC406AB9D",
           "installer": null,
           "last_comment": "Work Order created on service creation.",
           "assigned": null,
           "assigned_user": null,
           "created_by": "AEx System",
           "client_status": "Order in progress"
          }
         ],
     "page":1
     "count":1
     "total":1
    }
    
  2. 401 Unauthorized: You do not have access; please contact your SDM for a Token.

    1
    2
    3
    4
    5
    6
    {
        "code": 401,
        "errors": [
            "Not Authenticated"
        ]
    }
    
  3. 404 Not Found: The specified premise ID does not exist.

    1
    2
    3
    4
    5
    6
    {
        "code": 404,
        "errors": [
            "not found"
        ]
    }