Giacom Integrations API (2.0.4.3)

This section highlights the main capabilities implemented by the Giacom API.

Enables provisioning and in-life service management of:

• Giacom Mobile
• Gamma Mobile

Enables provisioning and in-life service management of:

• BTW Broadband
  • FTTP
  • SOGEA
  • SOADSL

Clients interacting with the Mobile Provisioning Capability will mainly create Service Orders on the API. This entity is used to order, change and cease services
The Giacom API incudes the following service provisioning capabilities:

• Provision a new Service
  • Mobile
    • Provisioning a new Mobile Service
    • Porting a number
  • Broadband
    • Provisioning a new Broadband Service
      • Provisioning an FTTP Broadband Service
        • New FTTP Service with a new line
        • New FTTP Service on existing ONT
        • Migrate existing FTTP Service
        • New FTTP Service with working Line Takeover
      • Provisioning SOGEA and SOADSL Broadband Services
        • New SOGEA/SOADSL Service with a new line
        • Start of Stopped Line
        • Migrate existing SOGEA/SOADSL Service
        • New SOGEA/SOADSL Service with working Line Takeover
• Manage a live Service
  • Change plan / tariff / regrade
  • Configure features (AKA Bars, Services, others)
  • Mobile
    • SIM Swap
    • Convert between Voice&Data and Data only
    • Add a Bolt-on
    • Upgrade / Downgrade a Bolt-on
    • Remove a Bolt-on
    • Configure notifications
    • Manage Spend Limit
  • Broadband
    • Manage dynamic and static IPs
    • Manage the care level
• Cease a live service

See Service Order for more details on how to manage Service Orders:

• State machine
• Handle failed Service Orders
• Handle rejected Service Orders
• Amend an in-flight order
• Expedite an order
• Set a new Appointment
• Change contact details
• Cancel in flight orders

The Giacom API incudes the following support capabilities:

• Service Inventory
  • See ## Service Inventory / Instance
  • Provides an Inventory of live services, as well as ab historic repository of ceased services, constantly maintained in sync with the Vendor's state of the services
    • Allows Tenants to search and retrieve service instance details
      • See Read a live Service
      • See Find a service by identifying characteristic
    • Supports a refresh on demand feature enabling Tenants to retrieve freshly updated service details from the Vendor
      • See Force a network refresh
• Service Catalogue
  • See Service Catalogue
  • Provides a repository of Service Specifications used to define the data model and business rules for services, with the ability to manage service specifications differentiated by:
    • Service category
    • Vendor
    • Tenant
    • Deployment environment
• Address management
  • See Geographic Address
  • Address search, AKA lookup AKA matching
    • See Address validation/matching
    • Provides address lookup functionalities allowing to search addresses by partial address and/or Openreach ALK (Address Key Locators)
    • Produces a single match or a list of alternative matches, depending on the information provided to the search endpoint
    • Utilises BTW as the main provider for address searching
  • Address creation
    • See Create a silver/bronze address
    • Enables creating Silver / Bronze Openreach addresses when needed
    • Enables creating specific Vendor ALK from a valid Address with an Openreach ALK
• Appointment management
  • See Appointment
  • Appointment slot search
    • See Search appointment slots
    • Enables Tenants to search for available appointment slots for a particular service order context
  • Appointment slot booking
    • See Book an appointment
    • Enables Tenants to book an available appointment slots for a particular service order context

This section introduces the data model of the Mobile Provisioning API.

The data model is presented in two sections:

• API Data Model: Overview of the data model of the API. Used to get an overall perspective of the different entities and how the correlate and collaborate with each other
• Service Meta-Catalogue: Presentation of the structure of the components of the Service Specifications which define the services available for ordering in the platform

Services are defined through Service Specifications which define their characteristics, features and also their category.

Mobile Services define the following categories:

• Mobile
  • Mobile Voice Service: Defines a standalone Voice and Data mobile service
  • Mobile Data only Service: Defines a standalone Data only mobile service
  • Mobile Bolt On: Defines a Bolt-On for a mobile service
• Broadband
  • Broadband FTTP: Defines an FTTP broadband service
  • Broadband SOGEA: Defines a SOGEA broadband service
  • Broadband SOADSL: Defines an SOADSL broadband service

Each Service Specification in each category presents a list of offerings (service tariffs) which may be chosen to instantiate a service. The available tariffs for each Service Specification are defined in the specCharacteristic with the ID = VENDOR_OFFERING.

Vendor Offerings define:

• For Mobile Services: The tariff
• For Broadband Services: The distinctive service level, typically the speed

            {
                "id": "VENDOR_OFFERING",
                "name": "Vendor offering",
                "description": "The product or service that will be ordered with the vendor",
                "valueType": "string",
                "minCardinality": 1,
                "maxCardinality": 1,
                "isUnique": false,
                "configurable": true,
                "characteristicValueSpecification": [
                    {
                        "name": "AIO25GB - All In One 25GB V24Q2",
                        "description": "AIO25GB - All In One 25GB V24Q2",
                        "valueType": "string",
                        "isDefault": true,
                        "value": "62212"
                    },
                    {
                        "name": "AIO2GBP - All In One Pooled Data 2GB V24Q2",
                        "description": "AIO2GBP - All In One Pooled Data 2GB V24Q2",
                        "valueType": "string",
                        "isDefault": false,
                        "value": "62230"
                    },
                    {
                        "name": "AIO2GBPIC - All In One Pooled Data 2GB inc. International Caller V24Q2",
                        "description": "AIO2GBPIC - All In One Pooled Data 2GB inc. International Caller V24Q2",
                        "valueType": "string",
                        "isDefault": false,
                        "value": "62231"
                    }
                ]
            },

Bolt-ons are services which can be added to core services to enhance them. Currently only available for Mobile services

Bolt-ons are identified by the Bolt On suffix in their category = "xxx Bolt On". Bolt-ons include a serviceSpecRelationshiplist which defines the specific Services with which they are compatible. It is possible to have Bolt-Ons compatible with multiple Service specifications. Bolt-Ons also have anallowance type`, defined in an informational characteristic "ALLOWANCE_TYPE". The system may define multiple allowance types for Bolt-Ons. E.g. for the mobile case:

• Minute Bolt-on
• Text Bolt-On
• Data Bolt-On
• Roaming Data Bolt-On

The snippet below shows the relevant fields of a Bolt-On's Service Specifications which, in this case, define the Bolt-On to be compatible with the Mobile Services defined by the Service Specification with the ID = MOBILE_VOICE_SRV_GIACOM.
The relevant specification's characteristics are:

• category: "Mobile Bolt On"
• serviceSpecRelationship: defines a relationship between Service Specifications. Possible values for this relationship field are:
  • addon_for: The defining Service Specification is a Bolt-on for the target Service Specification
• ALLOWANCE_TYPE: This particular example defines Data Bolt-Ons
• VENDOR_OFFERING: This characteristic defines all the available Data Bolt-On

        "category": "Mobile Bolt On",
        "serviceSpecRelationship": [
            {
                "relationshipType": "addon_for",
                "id": "MOBILE_VOICE_SRV_GIACOM_O2"
            }
        ],
        "specCharacteristic": [
            {
                "id": "ALLOWANCE_TYPE",
                "name": "Bolt-on allowance type",
                "description": "Bolt-on allowance type",
                "valueType": "string",
                "minCardinality": 0,
                "maxCardinality": 0,
                "isUnique": false,
                "configurable": false,
                "characteristicValueSpecification": [
                    {
                        "isDefault": false,
                        "name": "Bolt-on allowance type",
                        "description": "Bolt-on allowance type",
                        "valueType": "string",
                        "value": "Data Bolt-On"
                    }
                ]
            },
            {
                "id": "VENDOR_OFFERING",
                "name": "Bolt-on tariff",
                "description": "Bolt-on tariff",
                "valueType": "string",
                "minCardinality": 1,
                "maxCardinality": 1,
                "isUnique": false,
                "configurable": true,
                "characteristicValueSpecification": [
                    {
                        "name": "WODDTU1 - 1GB Data Top-Up (WS)",
                        "description": "WODDTU1 - 1GB Data Top-Up (WS)",
                        "isDefault": true,
                        "valueType": "string",
                        "value": "WODDTU1 "
                    },
                    {
                        "name": "WODDTU5 - 5GB Data Top-Up (WS)",
                        "description": "WODDTU5 - 5GB Data Top-Up (WS)",
                        "isDefault": false,
                        "valueType": "string",
                        "value": "WODDTU5 "
                    },

The Meta-Catalogue defines a consistent, structured, and vendor-agnostic way to represent service specifications.
It enables ordering, activation, configuration, and lifecycle management of different access services (e.g., mobile and broadband) through a unified model.
The meta-catalogue decouples channel and vendor variability from core business logic by defining intent, service properties, feature enablement, and commercial / operational dependencies in a machine-processable format.
Its purpose is to:

• Provide a common, consistent and modular modelling approach for multiple access technologies
• Support different order journeys, vendor integrations, and service features
• Maximise reusability and interoperability across vendors and products

[Char] VENDOR_OFFERING ^string

The product or service that will be ordered with the vendor

• Mandatoriness: Mandatory
• Cardinality: Single value
• Uniqueness: Allows duplicates
• Configurability: Client defined

[Char] VENDOR_SUB_ACCOUNT ^string

A logical sub-division of the Vendor Account. May represent a sub-account of an account, an account of a tenant, or other vendor specific terminology

• Mandatoriness: Mandatory
• Cardinality: Single value
• Uniqueness: Allows duplicates
• Configurability: Client defined
• Supported values:
  • Vendor sub account ID: A logical sub-division of the Vendor Account. May represent a sub-account of an account, an account of a tenant, or other vendor specific terminology

[Char] JOURNEY_TYPE ^string

The type of order that is to be placed with the vendor. Changing this value may trigger a new journey

• Mandatoriness: Mandatory
• Cardinality: Single value
• Uniqueness: Allows duplicates
• Configurability: Client defined

[Char] MSISDN ^E.164

Subscriber number. Vendor provided value for new connections. Uses the E.164 international phone format

• Mandatoriness: Optional
• Cardinality: Single value
• Uniqueness: Unique in the Tenant space
• Configurability: Vendor defined
• Supported values:
  • Subscriber number: Subscriber number

Mobile Characteristics - SIM & Identity

[Char] ICCID ^iccid

SIM Serial Number (ICCID)

• Mandatoriness: Mandatory
• Cardinality: Single value
• Uniqueness: Unique in the Tenant space
• Configurability: Client defined
• Supported values:
  • SIM Serial: SIM Serial

[Char] PUK ^string

Personal Unlocking Key, used to unlock SIM card after entering an incorrect PIN code multiple times when using PIN code security to protect the SIM

• Mandatoriness: Optional
• Cardinality: Single value
• Uniqueness: Allows duplicates
• Configurability: Vendor defined
• Supported values:
  • PUK: PUK

[Char] PUK2 ^string

Secondary Personal Unlocking Key

• Mandatoriness: Optional
• Cardinality: Single value
• Uniqueness: Allows duplicates
• Configurability: Vendor defined
• Supported values:
  • PUK2: PUK2

[Char] SIM_TYPE ^string

Type of SIM card

• Mandatoriness: Mandatory
• Cardinality: Single value
• Uniqueness: Allows duplicates
• Configurability: Client chosen
• Supported values:
  • eSIM: Embedded digital SIM
  • Triple SIM: Physical triple SIM card

[Char] ESIM_CONTACT_NAME ^string

eSIM email delivery contact name

• Mandatoriness: Mandatory
• Cardinality: Single value
• Uniqueness: Allows duplicates
• Configurability: Client defined
• Supported values:
  • eSIM Contact name: eSIM Contact name

[Char] ESIM_DELIVERY_EMAIL ^email

Email address that the eSIM information will be delivered to

• Mandatoriness: Mandatory
• Cardinality: Single value
• Uniqueness: Allows duplicates
• Configurability: Client defined
• Supported values:
  • eSIM Delivery Email: eSIM Delivery Email

[Char] ESIM_QR_CODE ^base64

eSIM CODE value to be sent as a QR code. Returned by vendor as order progresses

• Mandatoriness: Optional
• Cardinality: Single value
• Uniqueness: Unique in the Tenant space
• Configurability: Vendor defined
• Supported values:
  • eSIM QR CODE: eSIM CODE value to be sent as a QR code

Mobile Characteristics - Network Switching & Number Portability

[Char] DONOR_NETWORK_MSISDN ^E.164

Subscriber number on the donor network. Client defined for ports and migrations. Uses the E.164 international phone format

• Mandatoriness: Mandatory
• Cardinality: Single value
• Uniqueness: Unique in the Tenant space
• Configurability: Client defined
• Supported values:
  • Subscriber number on the donor network: Subscriber number on the donor network. Client defined for ports and migrations. Uses the E.164 international phone format

[Char] NETWORK_SWITCH_DATE ^iso8601-date

Date when the service is expected to port using PAC or transfer using STAC

• Mandatoriness: Mandatory
• Cardinality: Single value
• Uniqueness: Allows duplicates
• Configurability: Client defined
• Supported values:
  • Network switch date for PAC or STAC: Date when the service is expected to port using PAC or transfer using STAC

[Char] PAC ^PAC/STAC

PAC used for porting the number to this network. This characteristic is deleted after porting

• Mandatoriness: Optional
• Cardinality: Single value
• Uniqueness: Unique in the Tenant space
• Configurability: Client defined
• Supported values:
  • PAC: PAC used for porting the number to this network. This characteristic is deleted after porting

[Char] PAC_EXPIRATION_DATE ^iso8601_date

Expiration date of the PAC code. May represent the expiration date of a PAC code used to port in or the expiration date of a PAC code requested to enable port out

• Mandatoriness: Optional
• Cardinality: Single value
• Uniqueness: Unique in the Tenant space
• Configurability: Vendor defined
• Supported values:
  • PAC Expiration date: Expiration date of the PAC code. May represent the expiration date of a PAC code used to port in or the expiration date of a PAC code requested to enable port out

[Char] PAC_STATUS ^string

Status of the PAC code. May represent the status of a PAC code used to port in or the status of a PAC code requested to enable port out

• Mandatoriness: Optional
• Cardinality: Single value
• Uniqueness: Unique in the Tenant space
• Configurability: Vendor defined
• Supported values:
  • Open: Open and available for switching
  • Closed: Code has been used for switching
  • Locked: Switch has been initiated
  • Expired: Code has expired and can no longer be used for switching
  • Cancelled: Code has been cancelled and can no longer be used for switching

[Char] STAC ^PAC/STAC

STAC used for transferring the number in or out. This characteristic is deleted after transferring

• Mandatoriness: Optional
• Cardinality: Single value
• Uniqueness: Unique in the Tenant space
• Configurability: Client defined
• Supported values:
  • STAC: STAC used for transferring the number in or out. This characteristic is deleted after transferring

[Char] STAC_EXPIRATION_DATE ^iso8601_date

Expiration date of the STAC code. May represent the expiration date of a STAC code used to transfer in or the expiration date of a STAC code requested to enable transfer out

• Mandatoriness: Optional
• Cardinality: Single value
• Uniqueness: Unique in the Tenant space
• Configurability: Vendor defined
• Supported values:
  • STAC Expiration date: Expiration date of the STAC code. May represent the expiration date of a STAC code used to transfer in or the expiration date of a STAC code requested to enable transfer out

[Char] STAC_STATUS ^string

Status of the STAC code. May represent the status of a STAC code used to transfer in or the status of a STAC code requested to enable transfer out

• Mandatoriness: Optional
• Cardinality: Single value
• Uniqueness: Unique in the Tenant space
• Configurability: Vendor defined
• Supported values:
  • Open: Open and available for switching
  • Closed: Code has been used for switching
  • Locked: Switch has been initiated
  • Expired: Code has expired and can no longer be used for switching
  • Cancelled: Code has been cancelled and can no longer be used for switching

Mobile Characteristics - Notifications

[Char] NOTIFICATIONS_DELIVERY_EMAIL ^email

Email addresses to be used for vendors to deliver notifications to

• Mandatoriness: Optional
• Cardinality: Single value
• Uniqueness: Allows duplicates
• Configurability: Client defined
• Supported values:
  • Notifications delivery Email: Email address to be used for vendors to deliver notifications to

[Char] NOTIFICATIONS_DELIVERY_MSISDN ^E.164

List of MSISDNs to be used for vendors to deliver notifications by SMS to

• Mandatoriness: Optional
• Cardinality: Single value
• Uniqueness: Allows duplicates
• Configurability: Client defined
• Supported values:
  • Notifications delivery MSISDN: List of MSISDNs to be used for vendors to deliver notifications by SMS to

[Char] JOURNEY_TYPE ^string

The type of order that is to be placed with the vendor. Changing this value may trigger a new journey

• Mandatoriness: Mandatory
• Cardinality: Single value
• Uniqueness: Allows duplicates
• Configurability: Client chosen
• Supported values:
  • New connection: New connection through a SIM activation. MSISDN will be provided by the network
  • Port in with PAC: Ports a number to the network using a PAC. Requires a PAC and the current MSISDN
  • Migrate in with PAC: Ports a number to the service provider, maintaining the network, using a PAC. Requires a PAC and the current MSISDN
  • Transfer in with STAC: Activates a new SIM. Manages termination of the current service using a STAC. Requires the STAC and the MSISDN of the service being terminated
  • Allow port out: Requests a new PAC enabling the customer to port out to a different network or migrating to another service provider
  • Allow transfer out: Requests a new STAC enabling the customer to transfer out to another service provider and ceasing the current service

[Char] GAMMA_EU_ROAMING_MAX_CHARGE ^string

EU Maximum charge per MB roamed (inclusive of VAT). This figure is used to calculate the amount of data needed to activate the monthly data cap

• Mandatoriness: Mandatory
• Cardinality: Single value
• Uniqueness: Allows duplicates
• Configurability: Client chosen
• Supported values:
  • EU_004_4: EU_004_4
  • EU_008_9: EU_008_9
  • EU_017_5: EU_017_5

[Char] GAMMA_ROW_ROAMING_MAX_CHARGE ^string

Non-EU Maximum charge per MB roamed (inclusive of VAT): This figure is used to calculate the amount of data needed to activate the monthly data cap

• Mandatoriness: Mandatory
• Cardinality: Single value
• Uniqueness: Allows duplicates
• Configurability: Client chosen
• Supported values:
  • ROW_300_0: ROW_300_0
  • ROW_500_0: ROW_500_0
  • ROW_550_0: ROW_550_0
  • ROW_600_0: ROW_600_0
  • ROW_650_0: ROW_650_0
  • ROW_700_0: ROW_700_0
  • ROW_750_0: ROW_750_0

Mobile Bolt-ons don't have any additional characteristics besides the ones defined in the Common Service Characteristics

Mobile Bolt-ons Giacom: Characteristics

[Char] BOLTON_CHARGE ^string

Bolt-on charge description as presented in billing

• Mandatoriness: Optional
• Cardinality: Single value
• Uniqueness: Allows duplicates
• Configurability: Vendor defined

[Char] CARE_LEVEL ^string

Service care level defines response times for faults

• Mandatoriness: Mandatory
• Cardinality: Single value
• Uniqueness: Allows duplicates
• Configurability: Client chosen
• Supported values:
  • Basic: Basic care - refer to product handbook for more information
  • Standard: Standard care - refer to product handbook for more information
  • Enhanced: Enhanced care - refer to product handbook for more information
  • Premium: Premium care - refer to product handbook for more information

[Char] NETWORK_ADDRESSES ^string

First and last IPs of the address range and IP allocated to the WAN interface

• Mandatoriness: Optional
• Cardinality: Multiple values
• Uniqueness: Allows duplicates
• Configurability: Vendor defined
• Supported values:
  • Network Address: Subnetwork's IP
  • IP Range First Address: First IP of the address range
  • IP Range Last Address: Last IP of the address range
  • Broadcast Address: Subnetwork's broadcast IP
  • Public Address: Single public address. Supports dynamic and single static address

[Char] STATIC_IP_COUNT ^string

Choice between dynamic and static allocation. Allows choosing the number of static IPs

• Mandatoriness: Mandatory
• Cardinality: Single value
• Uniqueness: Allows duplicates
• Configurability: Client chosen
• Supported values:
  • Dynamic IP: The service will be allocated a dynamic IP address that will be subject to change
  • Single static IP: The service will be allocated a single static IP address
  • Two static IPs: The service will be allocated two addressable IPs
  • Six static IPs: The service will be allocated six addressable IPs

[Char] TRAFFIC_WEIGHTING ^string

Elevated traffic weighting provides preferential network performance during periods of congestion

• Mandatoriness: Mandatory
• Cardinality: Single value
• Uniqueness: Allows duplicates
• Configurability: Client chosen
• Supported values:
  • Standard: Standard weighting
  • Elevated: Elevated (preferential) weighting

[Char] JOURNEY_TYPE ^string

The type of order that is to be placed with the vendor. Changing this value may trigger a new journey

• Mandatoriness: Mandatory
• Cardinality: Single value
• Uniqueness: Allows duplicates
• Configurability: Client chosen
• Supported values:
  • Provide new: Provide a new service at the site
  • Migrate: Migrate an existing service owned by the same end customer
  • Start of stopped line: Start a stopped line
  • Working line takeover: Take over a working service owned by a different end customer

[Char] ORDER_COPPER_CEASE_REQUIRED ^boolean

Request for the legacy copper line to be ceased as part of the installation

• Mandatoriness: Mandatory
• Cardinality: Single value
• Uniqueness: Allows duplicates
• Configurability: Client chosen
• Supported values:
  • Cease required: The copper line will be ceased
  • Cease not required: The copper line will not be ceased

[Char] ORDER_CUSTOMER_NOTES ^string

List of notes to be passed from the Tenant/Customer to the Vendor and installation teams

• Mandatoriness: Optional
• Cardinality: Multiple values
• Uniqueness: Allows duplicates
• Configurability: Client defined
• Supported values:
  • INSTALLATION_NOTES: Installation notes
  • PARKING_NOTES: Parking notes
  • HAZARD_NOTES: Hazard notes
  • FREE_TEXT_NOTES: Free text notes

[Char] ORDER_INSTALL_OPTION ^string

Managed installation requires an engineer appointment

• Mandatoriness: Mandatory
• Cardinality: Single value
• Uniqueness: Allows duplicates
• Configurability: Client chosen
• Supported values:
  • Self: Self install, no engineer will attend
  • Managed: Managed install, an engineer appointment is required

[Char] ORDER_ONT_TYPE ^string

ONT type information for order

• Mandatoriness: Mandatory
• Cardinality: Single value
• Uniqueness: Allows duplicates
• Configurability: Client chosen
• Supported values:
  • New ONT: Install a ONT at the site
  • Existing ONT: Provide service on an existing ONT at the site
  • Multiport: Request installation of a Multiport ONT
  • Restrict swap: Request current ONT is not swapped for a Multiport ONT

[Char] ORDER_RID ^string

Ofcom RID for the service provider contracting with the end customer

• Mandatoriness: Mandatory
• Cardinality: Single value
• Uniqueness: Allows duplicates
• Configurability: Client defined
• Supported values:
  • Reseller ID: Ofcom RID for the service provider contracting with the end customer

Broadband Intent Characteristics - Managed Install

[Char] ORDER_MNG_INST_COST_ECC_CHARGES ^string

Pre-approve excess construction charges (ECCs) to install the line

• Mandatoriness: Mandatory
• Cardinality: Single value
• Uniqueness: Allows duplicates
• Configurability: Client chosen
• Supported values:
  • No pre-approval: No pre-approval, contact us first
  • Band 1: Band 1 - refer to product handbook for more information
  • Band 2: Band 2 - refer to product handbook for more information
  • Band 3: Band 3 - refer to product handbook for more information
  • Band 4: Band 4 - refer to product handbook for more information
  • Band 5: Band 5 - refer to product handbook for more information

[Char] ORDER_MNG_INST_COST_TR_CHARGES ^string

Pre-approve chargeable engineering work (if required) beyond the Network Termination Equipment (NTE)

• Mandatoriness: Mandatory
• Cardinality: Single value
• Uniqueness: Allows duplicates
• Configurability: Client chosen
• Supported values:
  • Band 0 - No pre-approval: Band 0 - No pre-approval, contact us first
  • Band 1: Band 1 - refer to product handbook for more information
  • Band 2: Band 2 - refer to product handbook for more information
  • Band 3: Band 3 - refer to product handbook for more information
  • Band 4: Band 4 - refer to product handbook for more information

[Char] ORDER_MNG_INST_COST_UPPER_COST_BAND ^string

Pre-approve ECC upper limit for excess construction costs

• Mandatoriness: Mandatory
• Cardinality: Single value
• Uniqueness: Allows duplicates
• Configurability: Client chosen
• Supported values:
  • Band A - No pre-approval: Band A - No pre-approval, contact us first
  • Band B: Band B - refer to product handbook for more information
  • Band C: Band C - refer to product handbook for more information
  • Band D: Band D - refer to product handbook for more information
  • Band E: Band E - refer to product handbook for more information
  • Band F: Band F - refer to product handbook for more information
  • Band G: Band G - refer to product handbook for more information
  • Band H: Band H - refer to product handbook for more information
  • Band I: Band I - refer to product handbook for more information

[Char] ORDER_MNG_INST_CRITICAL ^string

Is this service regarded as critical network infrastructure

• Mandatoriness: Mandatory
• Cardinality: Single value
• Uniqueness: Allows duplicates
• Configurability: Client chosen
• Supported values:
  • Not critical: Not critical
  • CNI: Critical Network Infrastructure
  • 999: 999 services

[Char] ORDER_MNG_INST_EU_CONSENT ^string

Permission to install networking up to the exterior wall without end user present

• Mandatoriness: Mandatory
• Cardinality: Single value
• Uniqueness: Allows duplicates
• Configurability: Client chosen
• Supported values:
  • Access granted: Permission granted for installation without customer presence
  • Presence Required: Customer must be present during external equipment installation

[Char] ORDER_MNG_INST_PROCESS ^string

FTTP installation type as defined during the line qualification check

• Mandatoriness: Mandatory
• Cardinality: Single value
• Uniqueness: Allows duplicates
• Configurability: Client chosen
• Supported values:
  • 1 Stage: Remote activation (where ONT exists) or short engineering visit to install ONT
  • KCI2 Assure: External and internal engineering visits required, and possibility of additional installation work

[Char] ORDER_MNG_INST_SVR ^string

Defines required engineer activity during installation

• Mandatoriness: Mandatory
• Cardinality: Single value
• Uniqueness: Allows duplicates
• Configurability: Client chosen
• Supported values:
  • Standard: Standard Installation - refer to product handbook for more information
  • Premium: Premium Installation - refer to product handbook for more information
  • Advanced: Advanced Installation - refer to product handbook for more information
  • Shift ONT: Shift ONT - refer to product handbook for more information

[Char] ORDER_MNG_INST_TERMINATION ^string

Required network termination type. Advanced Install Only.

• Mandatoriness: Mandatory
• Cardinality: Single value
• Uniqueness: Allows duplicates
• Configurability: Client chosen
• Supported values:
  • NTE5C: Network Termination Equipment 5C
  • NTTP: Network Terminating Point
  • Plug in NTE: Plug in Network Termination Equipment

Broadband Intent Characteristics - Managed Install Site

[Char] ORDER_MNG_INST_SITE_ACCESS_INFO ^string

Free text description for the visiting engineer access notes

• Mandatoriness: Mandatory
• Cardinality: Single value
• Uniqueness: Allows duplicates
• Configurability: Client defined
• Supported values:
  • Site Access Information: Free text description for the visiting engineer access notes

[Char] ORDER_MNG_INST_SITE_ACCESS_W3W ^string

What Three Words location for site entrance

• Mandatoriness: Mandatory
• Cardinality: Single value
• Uniqueness: Allows duplicates
• Configurability: Client defined
• Supported values:
  • Site Access W3W: What three words location for site entrance

[Char] ORDER_MNG_INST_SITE_COMPANY_NAME ^string

Name of the company the installation is being undertaken for

• Mandatoriness: Mandatory
• Cardinality: Single value
• Uniqueness: Allows duplicates
• Configurability: Client defined
• Supported values:
  • Company name: Name of the company the installation is being undertaken for

[Char] ORDER_MNG_INST_SITE_EQUIP_W3W ^string

What Three Words location for siting of network termination point

• Mandatoriness: Mandatory
• Cardinality: Single value
• Uniqueness: Allows duplicates
• Configurability: Client defined
• Supported values:
  • Site Equipment W3W: What Three Words location for siting of network termination point

[Char] ORDER_MNG_INST_SITE_NTE_FLOOR ^string

Floor location for network termination point installation

• Mandatoriness: Mandatory
• Cardinality: Single value
• Uniqueness: Allows duplicates
• Configurability: Client defined
• Supported values:
  • NTE Location: Floor: Floor location for network termination point installation

[Char] ORDER_MNG_INST_SITE_NTE_POSITION ^string

Position within room for network termination point installation

• Mandatoriness: Mandatory
• Cardinality: Single value
• Uniqueness: Allows duplicates
• Configurability: Client defined
• Supported values:
  • NTE Location: Position: Position within room for network termination point installation

[Char] ORDER_MNG_INST_SITE_NTE_ROOM ^string

Specific room location for network termination point installation

• Mandatoriness: Mandatory
• Cardinality: Single value
• Uniqueness: Allows duplicates
• Configurability: Client defined
• Supported values:
  • NTE Location: Room: Specific room location for network termination point installation

[Char] ORDER_MNG_INST_SITE_X_MARKS_THE_SPOT ^string

Include this value if the preferred location for the installation of the network termination equipment been marked

• Mandatoriness: Mandatory
• Cardinality: Single value
• Uniqueness: Allows duplicates
• Configurability: Client chosen
• Supported values:
  • X Marks the Spot: Include this value if the preferred location for the installation of the network termination equipment has been marked
  • Spot not marked: Include this value if the preferred location for the installation of the network termination equipment has NOT been marked

Broadband Intent Characteristics - Order Site

[Char] ORDER_SITE_END_USER_TYPE ^string

Type of end user for which the installation is being undertaken

• Mandatoriness: Mandatory
• Cardinality: Single value
• Uniqueness: Allows duplicates
• Configurability: Client chosen
• Supported values:
  • Residential: Residential end user type
  • Business: Business end user type

[Char] ORDER_SITE_FLAGS ^string

Flags indicating special site installation conditions such as hot site or uninhabitable location

• Mandatoriness: Optional
• Cardinality: Multiple values
• Uniqueness: Allows duplicates
• Configurability: Client chosen
• Supported values:
  • Hotsite: Include this value if the NTE is to be installed at a hot site
  • Uninhabitable: Include this value if the NTE is to be installed at a location which is not standard premises such as an outdoor location

Broadband Intent Characteristics - Existing Line

[Char] ORDER_EXISTING_LINE_ACCESS_TECHNOLOGY ^string

Technology type of the existing line specified in order

• Mandatoriness: Mandatory
• Cardinality: Single value
• Uniqueness: Allows duplicates
• Configurability: Client chosen
• Supported values:
  • WLR: Working lines mapped from PSTN, PSTN Single Line; stopped lines, from PSTN, ISDN'
  • MPF: Working lines mapped from MPF, SLU MPF; stopped lines, from MPF
  • SOGEA: Working lines mapped from CBS, SOGEA WLR, SOGEA MPF, SOGEA; stopped lines, from CBS, SOGEA
  • SOADSL: Working lines and stopped lines mapped from SOTAP

[Char] ORDER_EXISTING_LINE_ID ^string

The ALID of the line specified in the order

• Mandatoriness: Mandatory
• Cardinality: Single value
• Uniqueness: Allows duplicates
• Configurability: Client defined
• Supported values:
  • Access Line ID: The ALID of the line specified in the order

[Char] ORDER_EXISTING_LINE_ONT_NUMBER ^string

The reference number of the ONT specified in the order

• Mandatoriness: Mandatory
• Cardinality: Single value
• Uniqueness: Allows duplicates
• Configurability: Client defined
• Supported values:
  • FTTP ONT Reference: The reference number of the ONT specified in the order

[Char] ORDER_EXISTING_LINE_ONT_PORT_NUMBER ^string

Port number of the FTTP port specified in order

• Mandatoriness: Mandatory
• Cardinality: Single value
• Uniqueness: Allows duplicates
• Configurability: Client defined
• Supported values:
  • FTTP Port Number: Port number of the FTTP port specified in order

[Char] ORDER_EXISTING_LINE_ONT_PORT_STATUS ^string

Status of the FTTP port specified in order

• Mandatoriness: Mandatory
• Cardinality: Single value
• Uniqueness: Allows duplicates
• Configurability: Vendor defined
• Supported values:
  • Spare: Specified port is not in use
  • Working: Specified port is in use

[Char] ORDER_EXISTING_LINE_STATUS ^string

Status of the existing line specified in order

• Mandatoriness: Mandatory
• Cardinality: Single value
• Uniqueness: Allows duplicates
• Configurability: Client chosen
• Supported values:
  • New: New line required
  • Stopped: Specified line is stopped
  • Working: Specified line is working

[Char] ORDER_MIN_DOWNLOAD_SPEED ^string

The minimum download speed guaranteed for the service during the line qualification check

• Mandatoriness: Mandatory
• Cardinality: Single value
• Uniqueness: Allows duplicates
• Configurability: Client defined
• Supported values:
  • Minimum Download Speed: The minimum download speed guaranteed for the service during the line qualification check

[Feat] SUSPENSIONS_FULL_SUSPEND

Bars all features

[Feat] SUSPENSIONS_SERVICE_PROVIDER_FULL_SUSPEND

Admin full service bar placed

[Feat] SUSPENSIONS_SERVICE_PROVIDER_CALLS_OUT_SUSPEND

Admin bar prevents outgoing calls placed

[Feat] SUSPENSIONS_SERVICE_PROVIDER_DATA_SUSPEND

Admin bar prevents using data placed

[Feat] SUSPENSIONS_SPEND_LIMIT_SUSPEND

Spend limit triggered, out of bundle usage disabled

[Feat] SUSPENSIONS_STOLEN_SUSPEND

Bars all features and in some cases device

[Feat] SUSPENSIONS_USAGE_CALLS_DATA_SUSPEND

Customer defined limit reached, calls and data disabled

[Feat] SUSPENSIONS_USAGE_DATA_SUSPEND

Customer defined limit reached, data disabled

[Feat] CALLS_CALLS_ADULT

Can make calls to adult numbers

[Feat] CALLS_CALLS_EU_USA_CAN_OUT

Can make calls to EU, USA & Canada from the UK

[Feat] CALLS_CALLS_IN

Can receive incoming calls

[Feat] CALLS_CALLS_INTERNATIONAL_AND_PREMIUM

Can make calls to international and premium numbers from UK

[Feat] CALLS_CALLS_INTERNATIONAL_OUT

Can make calls to international numbers from UK

[Feat] CALLS_CALLS_NGCS

Can make calls to Non Geographic Call Services

[Feat] CALLS_CALLS_OUT

Can make outgoing calls

[Feat] CALLS_CALLS_PREMIUM

Can make calls to premium numbers

[Feat] CALLS_CALLS_ROW_OUT

Can make calls to the rest of the world from the UK

[Feat] CALLS_CALLS_SMS_PREMIUM

Can use premium voice and SMS services.

[Feat] DATA_DATA

Data can be used

[Feat] DATA_DATA5G

5G data can be used (requires Data)

[Feat] SMS_MMS_IN

Can receive MMS

[Feat] SMS_MMS_IN_OUT

Can send and receive MMS

[Feat] SMS_MMS_OUT

Can send MMS

[Feat] SMS_PREMIUM_SMS

Can send to premium SMS

[Feat] SMS_SMS_ADULT

Can send to adult SMS services

[Feat] SMS_SMS_CHAT

Can send to chat SMS services

[Feat] SMS_SMS_IN

Can receive SMS

[Feat] SMS_SMS_IN_OUT

Can send and receive SMS

[Feat] SMS_SMS_OUT

Can send SMS

[Feat] ROAMING_ROAMING_CALLS

Can make and receive calls outside of the UK

[Feat] ROAMING_ROAMING_CALLS_IN

Can receive calls outside of the UK

[Feat] ROAMING_ROAMING_CALLS_OUT

Can make calls outside of the UK

[Feat] ROAMING_ROAMING_CALLS_ROW

Can use calls when outside of the UK and outside of the EU

[Feat] ROAMING_ROAMING_CALLS_SMS

Can use calls and sms when outside of the UK

[Feat] ROAMING_ROAMING_CALL_HOME

Can call numbers in the UK when outside of the UK

[Feat] ROAMING_ROAMING_DATA

Can use data outside of the UK

[Feat] ROAMING_ROAMING_DATA_ROW

Can use data when outside of the UK and outside of the EU

[Feat] ROAMING_ROAMING_FULL

Can use calls, sms and data outside of the UK

[Feat] ROAMING_WORLDWIDE_CAP

Worldwide cap reached, data disabled

[Feat] SERVICE_ADULT_CONTENT

Can access content-restricted sources

[Feat] SERVICE_CONF_CALLING

Conference calling is enabled

[Feat] SERVICE_MPAY

Can pay for services & subscriptions via mobile bill

[Feat] SERVICE_SPEND_LIMIT_ROAMING

Enables suspending the service if the roaming spend limit is reached. Sends notification emails at different spend levels

[Feat] SERVICE_VISUAL_VOICEMAIL

Visual Voicemail is enabled

[Feat] SERVICE_VOICEMAIL

Voicemail is enabled

[Feat] SERVICE_WIFI_CALLING

Wifi calling is enabled

[Feat] SERVICE_SPEND_LIMIT

Suspends the service if the spend limit is reached. Sends warning email at different spend levels

SERVICE_SPEND_LIMIT Feature Characteristics

• [Char] SPEND_LIMIT_CLEAR_DATE ^iso8601_date: Date when the spend limit will be removed

  • Mandatoriness: Optional
  • Cardinality: Single value
  • Uniqueness: Allows duplicates
  • Configurability: Client defined
  • Supported values:
    • Spend limit clear date: Date when the spend limit will be removed

• [Char] SPEND_LIMIT_CURRENT ^integer: Current spend limit. Used for triggering spend alerts at several percentage and suspending the service when reached. Set to 0 (zero) if disabled

  • Mandatoriness: Mandatory
  • Cardinality: Single value
  • Uniqueness: Allows duplicates
  • Configurability: Vendor defined
  • Supported values:
    • Currently set spend limit: Current spend limit. Used for triggering spend alerts at several percentage and suspending the service when reached. Set to 0 (zero) if disabled

• [Char] SPEND_LIMIT_EARLY_WARNING_PERCENT ^integer: Percentage of the spend limit at which the early warning is sent to the end customer by email. Accepts a value between 50% and 100%

  • Mandatoriness: Optional
  • Cardinality: Single value
  • Uniqueness: Allows duplicates
  • Configurability: Client defined
  • Supported values:
    • Spend limit early warning percent: Percentage of the spend limit at which the early warning is sent to the end customer by email. Accepts a value between 50% and 100%

• [Char] SPEND_LIMIT_NEXT ^integer: The spend limit to be applied after a specific date

  • Mandatoriness: Optional
  • Cardinality: Single value
  • Uniqueness: Allows duplicates
  • Configurability: Client defined
  • Supported values:
    • Next spend limit: The spend limit to be applied after a specific date

• [Char] SPEND_LIMIT_NEXT_EFFECTIVE_DATE ^iso8601_date: Date when the next spend limit becomes active as the current spend limit

  • Mandatoriness: Optional
  • Cardinality: Single value
  • Uniqueness: Allows duplicates
  • Configurability: Vendor defined
  • Supported values:
    • Next spend limit effective on date: Date when the next spend limit becomes active as the current spend limit

[Feat] SERVICE_SPEND_LIMIT_REACHED_NOTIFICATION

Whether to send a notification when the spend limit is reached

[Feat] SERVICE_SPEND_LIMIT_EARLY_NOTIFICATION

Whether to send a notification when the spend limit reaches the early percentage

[Feat] APN_INTERNET

Internet

[Feat] APN_IPHONE

iPhone

[Feat] APN_TETHERING

Tethering

[Feat] APN_WAP

Wap

This section describes the typical User Journey used to provision a service. The fundamental flow includes the folowing steps:

• Discover:
  • Discover the Service Specifications defining the Service which may be ordered through the system

    See Service Discovery

• Configure:
  • Configuring a Service to be ordered

    See Service configuration

• Order:
  • Placing the order to provision the Service

    See Provision a new Service

Describes how a Tenant may obtain the list of available services to order from Giacom API.
It uses the List or find Service Specification endpoint to get the list of Service Specifications.

For details on the structure see Service Meta-Catalogue Service Catalogue For details on the API, see Service Catalogue API

A Service Specification defines a set of characteristics and features that need to be configured to define the values to be sent to the Create Service Order endpoint to order the service.

Characteristics scope

Characteristics are used to define or inform values that define and control a service. Characteristics may appear in Service Specifications under 3 main groups:

• Service Characteristics: Used for service-level characteristics
• Intent Characteristics: Used for characteristics relevant only during ordering
• Feature Characteristics: Used for characteristics meaningful in the context of a specific feature

Characteristics configurability

Each Characteristics serves a distinct purpose and may have different visibility. Characteristic Specifications define the following relevant properties:

• configurable: Controls if Clients can define values for them.
  • False: These characteristics should not be included in orders. If they are, they will be ignored and the system will revert to the values in the Service Specification
  • True: These characteristics are meant to be defined by clients when placing Service Orders. The system is still able to update their values when refreshing service data from the Vendors
• minCardinality: Controls the minimum number of values the characteristic can be configured with by either the Client or the System, depending on the configurable property.

  There is a use case for this property to be configured with 0 (zero), defined below as information only characteristics. On these characteristics, neither the client or the system is able to change the hard-coded value on the ServiceSpecification

• *maxCardinality: Controls the maximum number of values a characteristic can be configured with. Allows for characteristics to hold multiple values.

Information only characteristics

• Definition:

  minCardinality: 0
  maxCardinality: 0
  configurable: False

• This type of characteristics is used to transmit read only data from the Catalogue to the client for information purposes only.
• These characteristics are identifiable by defining configurable as False and having minCardinality as 0, meaning the client can't define a value when ordering. They also have maxCardinality as 0, meaning they cannot be changed and are only set automatically by Inventory when instantiating a service.
• E.g. ALLOWANCE_TYPE defines minCardinality=0, maxCardinality=0 and configurable=False meaning it is informational only. In this case, the ServiceSpecification defines a single value with the allowance type of the bolt on. This means it is a characteristic that provides information that may be displayed to a user during the ordering process, or used by the client to build the discovery and configuration UI

Vendor controlled characteristics

• Definition:

  minCardinality: x >= 0
  maxCardinality: y >= 1
  configurable: False

• This type of characteristic is used to hold values defined by Vendors and which are not allowed to be set by Clients. This means:
  • Clients cannot set them on ServiceOrders
  • Inventory allows setting and patching them, since Activation components need to be allowed to write them

Mandatory characteristic for ordering

• Definition:

  minCardinality: 1
  maxCardinality: x >= 1
  configurable: True

• Mandatory characteristics define a minimum cardinality of 1, which means the client needs to choose a value for the characteristics when ordering the service
• The maximum cardinality defines the number of values that the client may choose for the characteristic. A number larger than 1 is used for characteristics which allow multiple values
• E.g. Tariff defines min=1 and max=1, meaning exactly 1 value, i.e. it is mandatory to choose one tariff

Optional characteristic for ordering

• Definition:

  minCardinality: 0
  maxCardinality: x >= 1
  configurable: True

• Optional characteristics define a minimum cardinality of 0, which means the client doesn't need to choose a value for the characteristics when ordering the service
• The maximum cardinality defines the number of values that the client may choose for the characteristic. A number larger than 1 is used for characteristics which allow multiple values
• E.g. PAC defines min=0 and max=1, meaning it is optional. If this value is defined, it triggers a portability provisioning operation

Characteristics relationship

Characteristics also define dependency relationships between them, meaning they should only be included in a Service definition in a Service Order Item if the required characteristic is defined.

• E.g. requires: PAC requires MSISDN. For a portability use case, it is mandatory to include the subscriber number for the PAC to be meaningful
• E.g. value_eq: ESIM_DELIVERY_EMAIL requires the value of the characteristic SIM_TYPE to be equal to e_sim to allow the system to deliver the eSIM via email to the end customer. This property only makes sense for eSIM and is only defined by the Vodafone service managed by Giacom

Characteristics isDefault value behaviour

ServiceSpecification have a list of CharacteristicSpecification. Each one can have one or more CharacteristicValueSpecification, defining the values they can assume. Value specifications can take a few forms:

• CharacteristicValueSpecification with a value property: The ServiceSpecification provides one or more pre-defined values which the characteristic can be configured with (obeying to the cardinality and configurable rules)
  • May be configured with isDefault = True, meaning, the client and system (depending on the configurable property) may omit defining the characteristic. In that case, the system shall automatically add the characteristic, considering its default value(s)
• CharacteristicValueSpecification with a regex property: The ServiceSpecification provides one or more value specifications defining a regex to be used to validate the value(s) with which the characteristic is configured (obeying to the cardinality and configurable rules)
  • Cannot be configured with isDefault = True since the value is unknown until it is configured by the client or the system

CharacteristicValueSpecification also set their isDefault property

Defining Features

Features are used to enable or disable specific functional aspects of mobile services.
Features are grouped into bundles. Mobile Services include feature bundles for the following aspects of a mobile service:

• Bars
• Network services
• APN

Each of the above feature bundles define a set of features that compose them.
When ordering a service, clients need to define the features property of the Service definition in the Service Order Item with the following considerations:

• Features defining bundles should not be included. Only individual features. The system will ignore bundle features and always revert to the specification for reference
• Features not included are still part of the provisioned service, configured with their default state

Features also define dependency relationships between them, meaning enabling a feature may affect other features:

• E.g. includes: The feature "BARS" is a bundle feature and has several includes relationships to define the features which are part of its bundle. A feature may only be part of one bundle
• E.g. excludes: ROAMING_ROAMING_CALLS excludes ROAMING_ROAMING_CALLS_IN and ROAMING_ROAMING_CALLS_OUT. If ROAMING_ROAMING_CALLS is enabled, ROAMING_ROAMING_CALLS_IN and ROAMING_ROAMING_CALLS_OUT cannot be enabled. If the rule is not observed, the system will fail the request

A new service is provisioned by invoking the Create Service Order endpoint and passing it a Service Order.
A Service Order is composed of Service Order Items. Each Service Order Item defines a Service Configuration which will be used to activate the service.

To provision a new Service, a client needs to create a Service Order with:

• A Service Order Item with the action = add
• Define the Service Configuration inside the Service Order Item by specifying:
  • The Service Specification ID and its version

For more detail, consult:

• Provisioning new Services
• Provisioning Mobile Services
• Provisioning Broadband Services

Orders can take an arbitrary time to complete, depending on their nature and the Vendor system. Once placed, Tenant clients receive the order object with relevant information for order follow up:

• id: Provides an identifier for the order
• state: Provides the current state of the order

Whenever a Service Order changes state, it produces a ServiceOrderStateChangeEvent event. This event is delivered via a Notification to the client's defined webhook(s) Clients can also poll the Service Order state using the Get by ID operation

Other Service Order Notifications

Service Orders may also raise additional events:

• ServiceOrderAttributeValueChangeEvent
  • When an internal attribute changes. E.g. the priority or the expectedCompletionDate
• ServiceOrderJeopardyEvent
  • When the Vendor adds a new Jeopardy alert to the order
  • This event might require information to be added to the order, by calling the amend order endpoint
• ServiceOrderMilestoneEvent
  • When the Vendor adds a new Milestone to the order

To ensure API security, we use OAuth 2.0 with the Client Credentials grant type for authentication. This method is designed for server-to-server interactions, where your application can securely access our API without user intervention. It is your responsibility to secure the end-user access to the application using the API.

What is OAuth 2.0?

OAuth 2.0 is an industry-standard protocol for authorization. It allows third-party applications to obtain limited access to an HTTP service on behalf of a resource owner. The Client Credentials grant type is a specific flow within OAuth 2.0 that is used for machine-to-machine communication.

Additional details available at:

• OAuth.net by Aaron Parecki
• OAuth.com by Okta

How Does It Work?

1. Client Registration: Before you can interact with our API, you need to be onboarded. You will be provided you with a Client ID and Client Secret.

2. Token Request: Your application will request an access token from our authorization server by providing the Client ID and Client Secret.

3. Access Token: The authorization server will validate your credentials and issue an access token. This token is a string that represents the authorization granted to your application.

4. Scopes: Your access token will contain one or more scopes. Giacom API validates scopes from Access Token against required scopes on API methods to control access.

5. API Requests: Your application will include the access token in the Authorization header of your API requests. This token will be used to authenticate your requests and grant access to the API resources.

Example Token Request

Here is an example of how to request an access token using the Client Credentials grant type:

POST /oauth2/token HTTP/1.1
Host: auth.integrations.giacom.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&scope=REQUESTED_SCOPE

The scope parameter is optional which should be used to limit scopes in the generated Access Token to minimum required list. If it is omitted, Access Token will contain all scopes available to your Client.

Example API Request

Once you have obtained an access token, you can use it to make authenticated requests to the API:

GET /api/resource HTTP/1.1
Host: integrations.giacom.com
Authorization: Bearer YOUR_ACCESS_TOKEN

Token Expiration and Refresh Tokens

Access tokens have a limited lifespan to enhance security. When an access token expires, your application will need to request a new one. Here’s how to handle token expiration and refresh tokens:

1. Token Expiry: Access tokens are valid for a specific duration, after which they expire. The expiration time is typically included in the token response.

2. Handling Expired Tokens: When your application receives a response indicating that the access token has expired, it should request a new token using the same Client Credentials grant type.

Security Considerations

• Keep Your Credentials Secure: Ensure that your Client ID and Client Secret are stored securely and not exposed in your client-side code.
• Only request Scopes you need: Ensure Access tokens follow principle of least priviledge by explicitely requesting only Scopes you need to perform specific API actions.
• Token Expiry: Access tokens have a limited lifespan. Be prepared to handle token expiration and request new tokens as needed.
• HTTPS: Always use HTTPS to encrypt your API requests and responses.

By following these guidelines, you can securely integrate with the Giacom Integrations API and take advantage of our services.

The Giacom API is a subset of the TMF Open APIs. Being a sub-set means:

• We implement a subset of the Open APIs defined by TMF
  
• We implement only the minimum viable subset of endpoints of each API Specification
• We implement only the minimum viable subset of schemas of each API Specification
• We may implement only a subset of the features of the TMF APIs

  e.g. we don't implement schema polymorphism at the time

The Giacom API also follows the TMF630 REST API Design Guidelines. This section clarifies our implementation of the TMF REST API Guidelines and provides a quick reference to API usage patterns. Below we describe the common patterns in the API usage.

|This section clarifies section "4.4. Query entities with attribute filtering" of the TMF630 guideline

Filter parameters

Filter parameters are passed to GET /{entity} endpoints through query parameters. The API supports multiple filter parameters. E.g.:

• It is possible to filter by any field present on schema of the returned object on each endpoint

# Find live services in a failure state
GET /service?state=active&hasStarted=true&isServiceEnabled=false

Note: Filter parameter values must be passed in their URL encoded form

Filter using VALUE IN

It is possible to filter and obtain the list of entities whose value of a specific field is in a list provided by the client.
To define multiple values, the Client needs to repeat the query parameter for the specific field. TMF630 defines the alternative of passing a list of values in a comma separated list but the approach implemented avoids complexity in value management when considering that values may themselves contain commas.

# Find live services in a failure OR stopped state
GET /service?state=failed&state=stopped

Matching multiple fields

When filtering by multiple fields the API will apply the following logic:

• AND: The API will apply an AND logic when multiple fields are passed in the query string. The entities returned in the request will match all the values of all fields
• OR: Is applied only to VALUE IN queries
• Equals: At the moment, only equals is supported for value matching. This means that the exact value must be passed in filters

# Find live services in a failure OR stopped state AND which have already started
GET /service?state=failed&state=stopped&hasStarted=true

Filtering by nested fields

It is possible to filter entities by values of nested fields. This allows e.g. searching services instantiated from a particular Service Specification.
The '.' notation is used to search by nested fields.
It is possible to combine nested fields with top level fields filtering

# Find the services instantiated from VF_Mobile_Connection and which are active
GET /service?serviceSpecification.id=VF_Mobile_Connection&state=active

Advanced filtering

To allow searching in complex structures, namely any type of lists, TMF defines the usage of JSONPath filters in Part 6 of the TMF630 REST API Design Guidelines.

• The JSONPath filter is sent on the "filter" field available on the endpoints supporting it
• The filter is applied as an AND to other query parameters

E.g. Find a mobile service by subscriber number 07800987654

GET /service?filter=$.serviceCharacteristic[?(@.id=="MSISDN")].value[?(@.value=="07800987654")]

Sample service representation for reference

{
    "id": "dd5244e1-13e3-45a5-b2f0-47b111a65142",
    "lastUpdate": "2025-02-12T16:06:44.318Z",
    "version": 1,
    "name": "Mobile Voice Giacom-O2",
    "description": "Mobile Voice Giacom-O2",
    "category": "Mobile Voice Service",
    "isBundle": false,
    "operatingStatus": "pending",
    "hasStarted": false,
    "isServiceEnabled": false,
    "serviceDate": "2025-02-12T16:46:58.852Z",
    "startDate": "2025-02-12T16:46:58.852Z",
    "endDate": "2026-02-12T16:46:58.852Z",
    "serviceSpecification": {
        "id": "MOBILE_VOICE_SRV_GIACOM_O2",
        "version": "1"
    },
    "serviceOrderItem": [
        {
            "serviceOrderId": "38056a58-f783-453a-bc80-18d25ba8f3dc",
            "itemAction": "add",
            "itemId": "1"
        }
    ],
    "externalIdentifier": [
        {
            "owner": "ACME Comms",
            "externalIdentifierType": "service_id",
            "id": "123"
        }
    ],
    "relatedParty": [
        {
            "role": "VENDOR_ACCOUNT",
            "partyOrPartyRole": {
                "id": "ACME Comms"
            }
        },
        {
            "role": "VENDOR",
            "partyOrPartyRole": {
                "id": "GIACOM"
            }
        },
        {
            "role": "NETWORK",
            "partyOrPartyRole": {
                "id": "O2"
            }
        }
    ],
    "serviceCharacteristic": [
        {
            "id": "BILL_LIMIT",
            "name": "Bill limit",
            "description": "Bill limit",
            "valueType": "int",
            "value": [
                {
                    "name": "Bill limit",
                    "description": "Bill limit value",
                    "valueType": "int",
                    "value": "100"
                }
            ]
        },
        {
            "id": "VENDOR_OFFERING",
            "name": "Tariff",
            "description": "Giacom mobile tariff. Corresponds to the Giacom Mobile product",
            "valueType": "string",
            "value": [
                {
                    "name": "AIO2GBPIC - All In One Pooled Data 2GB inc. International Caller V24Q2",
                    "description": "AIO2GBPIC - All In One Pooled Data 2GB inc. International Caller V24Q2",
                    "valueType": "string",
                    "value": "62231"
                }
            ]
        },
        {
            "id": "SIM_TYPE",
            "name": "SIM type",
            "description": "Type of SIM card",
            "valueType": "string",
            "value": [
                {
                    "name": "Triple SIM",
                    "description": "Triple SIM",
                    "valueType": "string",
                    "value": "triple"
                }
            ]
        },
        {
            "id": "ICCID",
            "name": "SIM Serial",
            "description": "SIM Serial",
            "valueType": "iccid",
            "value": [
                {
                    "name": "SIM Serial",
                    "description": "SIM Serial",
                    "valueType": "iccid",
                    "value": "8944201122334455667"
                }
            ]
        }
    ],
    "feature": [
        {
            "id": "SUSPENSIONS_FULL_SUSPEND",
            "name": "Full suspend",
            "description": "Bars all features",
            "isEnabled": false
        },
        {
            "id": "SUSPENSIONS_SERVICE_PROVIDER_FULL_SUSPEND",
            "name": "Service provider full suspend",
            "description": "Admin full service bar placed",
            "isEnabled": false
        },
        {
            "id": "CALLS_CALLS_PREMIUM",
            "name": "Calls premium",
            "description": "Can make calls to premium numbers",
            "isEnabled": true
        },
        {
            "id": "ROAMING_ROAMING_CALLS",
            "name": "Roaming calls",
            "description": "Can make and receive calls outside of the UK",
            "isEnabled": true
        },
        {
            "id": "ROAMING_ROAMING_CALLS_IN",
            "name": "Roaming calls in",
            "description": "Can receive calls outside of the UK",
            "isEnabled": false
        },
        {
            "id": "ROAMING_ROAMING_CALLS_OUT",
            "name": "Roaming calls out",
            "description": "Can make calls outside of the UK",
            "isEnabled": false
        },
        {
            "id": "SERVICE_CONF_CALLING",
            "name": "Conf calling",
            "description": "Conference calling is enabled",
            "isEnabled": true
        },
        {
            "id": "SMS_MMS_IN_OUT",
            "name": "MMS in out",
            "description": "Can send and receive MMS",
            "isEnabled": true
        },
        {
            "id": "SERVICE_WIFI_CALLING",
            "name": "Wifi calling",
            "description": "Wifi calling is enabled",
            "isEnabled": true
        },
        {
            "id": "APN_INTERNET",
            "name": "O2 Internet APN",
            "description": "5G service",
            "isEnabled": true
        },
        {
            "id": "APN_IPHONE_985",
            "name": "O2 iPhone APN 985",
            "description": "O2 iPhone APN 985",
            "isEnabled": true
        },
        {
            "id": "APN_IPHONE_986",
            "name": "O2 iPhone APN 986",
            "description": "O2 iPhone APN 986",
            "isEnabled": false
        }
    ]
}

This feature is defined in Part 1, section 4.3 of the TMF630 REST API Design Guidelines

Response shaping, i.e. controlling the subset of fields returned by an API is not yet available in any of the Giacom API endpoints

This feature is defined in Part 1, section 4.5 of the TMF630 REST API Design Guidelines

Results paging is not yet available in any of the Giacom API endpoints, apart from the special use cases defined in this section

All search endpoints return two headers with record counters:

• X-Total-Count: Total number of items matching criteria
• X-Result-Count: Actual number of items returned in the response body

Counting matching records

To just obtain a count of matching records without any data, a Client may pass 0 in the limit query parameter. Currently this is the only supported limit value and any other value will result in a 400 Bar Request response. If the Client defines a limit=0, the system will return:

• X-Total-Count: Total number of items matching criteria
• X-Result-Count: 0
• An empty list of entities

Special case: Large number of matching results

In cases where the number of results exceeds any internal limit the system may trim the results and return a partial result list. In this case, the system will return:

• X-Total-Count: Total number of items matching criteria
• X-Result-Count: Actual number of items returned in the response body, less than X-Total-Count
• A partial list of entities

This feature is defined in Part 1, section 4.7 of the TMF630 REST API Design Guidelines

Results sorting is not yet available in any of the Giacom API endpoints

This section details all HTTP Responses a client may receive when using the Giacom Integrations API.

Success response codes

Success messages are defined individually by each operation in the API. Possible HTTP response status codes are:

• 200 OK

  Used in: GET, PATCH
  Generic success status returned, typically by GET operations, indicating a successful execution and including the requested entity or search result. PATCH operations also use this error code

• 201 Created

  Used in: POST
  Only returned by POST operations, meaning the Entity has been successfully created. A unique ID is always included in the response as part of the entity's schema.
  Note: The created entity may still produce async updates as part of its lifecycle. E.g. ServiceOrder is created in an ACKNOWLEDGEDstate and is subsequently updated as the service order progresses

• 204 No Content

  Used in: DELETE
  Only returned by DELETE operations, meaning the Entity has been successfully deleted

Error response codes

Error responses are defined globally for the Giacom Integrations API and each operation type has a specific set of HTTP response status codes it can use. Possible HTTP response status codes are:

• 400 Bad Request

  Used in: All operation types
  Returned by: All operation types Used to signal client side errors. E.g.: Some error in parameter definition

• 401 Unauthorized

  Used in: All operation types
  Returned when the client doesn't have authorisation to access the requested resource

• 404 Not Found

  Used in: All operation types, except POST
  Returned when the resource requested does not exist, or is not accessible to the client

• 500 Internal Server Error

  Used in: All operation types
  Returned when there is an error processing the client's request which was not caused by the request or the client

Note: This list only defines response codes returned as part of this API. Other HTTP error response status codes may be received by a client application if the request is handled and failed directly by any network element.

Error response schema

Error responses include detail additional to the HTTP response code to improve the Client and Developer experience. All Error responses follow the components/schemas/Error schema.

Sample error response:

{
  "code": "ERR_000001",
  "reason": "ERR_000001: Request body validation error at field level",
  "message": "Error parsing field 'name'",
  "status": "Error"
}

The components/schemas/Error returns:

• code: Application level error code managed as a centralised enumeration
• reason: Description of the values returned in the code field

  i.e. an explanation of the reason for the error which can be shown to a client user

• message: Information or debug details generated at runtime when each error occurs

  E.g.: More details and corrective actions related to the error which can be shown to a client user

• status: Absolute status of the request. Currently only supporting:
  • Error: Means the request has completely failed

Error Codes list

Below we include the complete reference for possible values of code and reason:

In order to start receiving notifications from the Notifications Hub, follow these steps:

Register Listener with Notifications Hub

curl --location 'https://api.integrations.giacom.com/v1/topic/default/hub' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "Authorization: Bearer <your_access_token_here>" \

--data '{
  "callback": "https://yourportal.com/webhook"
}'

(Optional) Webhook endpoint authentication

If your webhook link is protected, you can optionally specify a Credentials object to pass an API key. Notifications service will send this key in Authorization: Basic <apikey> header.

curl --location 'https://api.integrations.giacom.com/v1/topic/default/hub' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "Authorization: Bearer <your_access_token_here>" \

--data '{
  "callback": "https://yourportal.com/webhook",
  "credentials": {
    "type": "apikey",
    "value": "<your_secret_api_key>"
  }
}'

The Notifications Hub will respond to confirm your listener was created:

201 Created

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "callback": "https://yourportal.com/webhook",
  "credentials": {
    "type": "apikey",
  }
}

Notification delivery

When an event happens, Notifications service will automatically notify your Webhook endpoint. This will be in a form of POST request with the following structure:

curl --location 'https://yourportal.com/webhook' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "Authorization: Basic <your_secret_api_key>" \

--data '{
  "eventId": "550e8400-e29b-41d4-a716-446655440000",
  "eventTime": "2015-11-16T16:42:25-04:00",
  "eventType": "ServiceOrderStateChangeEvent",
  "event": {
    "ServiceOrder": {
        "id": "c9d8c1f1-7523-476a-b89f-774bfd390f46",
        "version": 6,
        "... Remaining entity properties ..."
    }
  }
}

The event property is used to transport the full representation of the entity that raised the event. Each entity in this specification may define a listener endpoint, like the Client listener for entity ServiceOrderStateChangeEvent. These endpoints are meant to provide the full specification of each particular Event, including the schema of the entity inside the event property. They are meant to be implemented as internal logic of the client's callback.

Retries and idempotency

If the Listener is unavailable, or does not respond with a 202 ACCEPTED response code, Notifications Service will attempt at least 2 retries with 30 second backoff window. If the notification is not delivered after 3 retries, no further retries will be attempted.

In some cases, notification for the same event may be delivered more than once, or out of order. Notification consumers can use:

• Idempotency: The eventId Event property uniquely identifies each event and can be used to detect duplicate events
• Order: The version property which is part of all entities which produce events is incremented atomically with every change. It may be used for detecting out of order entity updates

Stop receiving notifications

If at any point you want to stop receiving event Notification, you can do so by deleting the Hub.

curl --location --request DELETE \
  --header "Authorization: Bearer your_access_token_here" \
  "https://api.integrations.giacom.com/v1/topic/default/hub/<listener_id>"

• Stakeholders register Callback Listeners in order to receive Notifications using the Create Hub endpoint.

  Any API Key required to deliver notifications to a client's callback is stored securely

• When receiving an event, Notifications Service notifies all subscribed Callback Listeners, within the context of the specific tenant
• Giacom guarantees at-least 3 delivery attempts with a 30s retry interval but does not try to guarantee strict event ordering
• There is currently no event filtering. All events are delivered to all callbacks in the context of a specific tenant.

Notifying Listeners

When receiving an Event, Notifications Service will notify all Callback Listeners subscribed to the specified Event type. The exact structure of the event will depend on the Event schema - make sure to check the API-specific listener schemas.

Authentication for managing Hubs

An Access token must be included in Authorization HTTP header for all requests. For all current use-cases there is only one scope required:

• integrations/notifications.read

Multi-tenancy

Notifications Hub is a multi-tenant service. All requests must specify the tenant context,which is retrieved from the access token.

Notifications Event Hub API is an internal API used by trusted systems to publish events.

You can check out following documentation to gain more understanding behind API concepts :

• Getting Started with Notifications Guide
• TMForum 630 REST API Guidelines Part 1

TBD