Giacom Integrations API (0.2.3)

Download OpenAPI specification:

Welcome to the Giacom Integrations API! The list below describes the most relevant capabilities of the Giacom Integrations API and provides quick links to use cases and operations for each one

Mobile provisioning

Mobile provisioning incudes the following capabilities:

Ordering services

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
- Ordering new Services
  
  See Use-Case: Configuring a service
  See Use-Case: Ordering a service
  Ordering new Services is done by creating a Service Order which:
  - Is configured with the "add" action
  - References the intended Service Specification
  - Provides the set of values required to configure the service's order.
- Changing live services
  
  See Use-Case: Updating a service
  Changing live Services is done by creating a Service Order which:
  - Is configured with the "modify" action
  - References the intended Service Instance ID and Service Specification
  - Provides the set of values to be changed (and nothing else)
- Cancelling (ceasing) live services
  
  See Use-Case: Ceasing a service
  Cancelling (ceasing) live Services is done by creating a Service Order which:
  - Is configured with the "delete" action
  - References the intended Service Instance ID and Service Specification
  - Any other parameters are ignored
- Cancelling in flight orders
  
  It is possible to cancel Service Orders which have not yet completed, as long as these conditions are observed:
  - TBD
Managing resource stock

See Use-Case: Creating a stock unit The API allows managing the stock of pre-provisioned resources which may be used in service orders.
e.g. Phone numbers, SIM cards
The Resource entity is responsible for managing such resource instances. See:

- Data model

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

Overview
Service Specifications define what can be ordered and provisioned Clients order services by placing Service Orders and providing the Service Specification, values for the relevant Characteristics and the Features configuration The Service Orders system will create one Service instance for each ordered Service Specification and provision the service on the supplier accordingly Each Service instance maps to a specific service on the supplier Service instances may reference Resources for their operation. E.g. Subscriber Number Each Resource instance maps to a specific resource on the supplier. E.g. SIM by SIM serial
Services
A Service represents a Service from a supplier A Service Specification models a specific Service that can be provisioned on a provider A Service instance represents an instance of a specification which has been configured with specific values for each of the specification's characteristics, has had its features enabled/disabled and has been provisioned on the provider
Resources
A Resource represents a resource from a supplier A Resource Specification models a specific resource that can be provisioned on a provider A Resource instance represents an instance of a specification which has been configured with specific values for each of the specification's characteristics and has been provisioned on the provider Provisioning resources can be used to maintain a stock of Subscriber Numbers and SIMs For Giacom Mobile Services this process is automatic since Giacom manages the resources internally. Resources are automatically instantiated when a service is provisioned
Characteristics
Characteristics support the configuration of both Resources and Services. They allow defining billing limits, subscriber number, SIM details, porting details, among other characteristics Each entity specification defines the set of characteristics it needs configured to be provisioned and operated Characteristics define a set of values with which they can be configured
Features
Features support enabling Bars, Services and APNs on Services Each Mobile Service Specification defines the set of features it provides and groups them into bundle features Clients enable or disable each feature during service ordering to configure the service Since features in a specification are always explicitly represented in a service instance, while ordering, clients only need to specify features for which they want to change the default or current value Bundle features also don't need to be ordered, since they will be ignored. The system will always use the bundle features from the specification and never from an order

- Use cases

This section describes the most relevant use cases provided by the Mobile Provisioning API.

Discovery

This use case describes how a client system 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.

Discovery use case

Examples

The following are examples of queries a client might use:

List all services supplied by Giacom

# Using the filter parameter with a JSONPath that matches services with "GIACOM" as the relatedParty with the "supplier" role
GET /serviceSpecification?filter=$.relatedParty[?(@.role=="supplier" && @.partyOrPartyRole.id=="GIACOM")]

The JSONPath filter matches the following JSON within a Service Specification:

{
    "relatedParty": [
        {
            "role": "supplier",
            "partyOrPartyRole": {
                "id": "GIACOM"
            }
        }
    ]
}

List all services supplied by Giacom, but only within the "Mobile Voice Service" category

# Using the filter parameter with a JSONPath that matches services with "GIACOM" as the relatedParty with the "supplier" role combined with a direct query to the category "category" property
GET /serviceSpecification?category=Mobile Voice Service&filter=$.relatedParty[?(@.role=="supplier" && @.partyOrPartyRole.id=="GIACOM")]

Service Specification example

Below we present an example of a Service Specifications.
For details on the structure see the Service Catalogue section of the API reference.

Click to expand the json example

{
    "id": "MOBILE_VOICE_SRV_GIACOM_VF",
    "lastUpdate": "2025-02-12T16:06:44.318Z",
    "version": 1,
    "name": "Mobile Voice Giacom-VF",
    "description": "Mobile Voice Giacom-VF",
    "category": "Mobile Voice Service",
    "isBundle": false,
    "lifecycleStatus": "Launched",
    "relatedParty": [
        {
            "role": "supplier",
            "partyOrPartyRole": {
                "id": "GIACOM"
            }
        },
        {
            "role": "network",
            "partyOrPartyRole": {
                "id": "VF"
            }
        }
    ],
    "specCharacteristic": [
        {
            "id": "BILL_LIMIT",
            "name": "Bill limit",
            "description": "Bill limit",
            "valueType": "int",
            "minCardinality": 0,
            "maxCardinality": 1,
            "isUnique": false,
            "configurable": true,
            "characteristicValueSpecification": [
                {
                    "name": "Bill limit",
                    "description": "Bill limit value",
                    "isDefault": true,
                    "valueType": "int",
                    "valueFrom": 0,
                    "valueTo": 1000,
                    "regex": "^(0|[1-9]\\d{0,2}|1000)0$"
                }
            ]
        },
        {
            "id": "TARIFF",
            "name": "Tariff",
            "description": "Giacom mobile tariff. Corresponds to the Giacom Mobile product",
            "valueType": "string",
            "configurable": true,
            "minCardinality": 1,
            "maxCardinality": 1,
            "isUnique": true,
            "characteristicValueSpecification": [
                {
                    "name": "WS20GBBSE - O&O 20GB Special + WTS (ETS)",
                    "description": "WS20GBBSE - O&O 20GB Special + WTS (ETS)",
                    "valueType": "string",
                    "isDefault": true,
                    "value": "55629"
                },
                {
                    "name": "WS20GBICE - O&O 20GB Special + WTS/IC (ETS)",
                    "description": "WS20GBICE - O&O 20GB Special + WTS/IC (ETS)",
                    "valueType": "string",
                    "isDefault": false,
                    "value": "55630"
                },
                {
                    "name": "WS24GBRE - O&O 24GB Retention (ETS)",
                    "description": "WS24GBRE - O&O 24GB Retention (ETS)",
                    "valueType": "string",
                    "isDefault": false,
                    "value": "55638"
                }
            ]
        },
        {
            "id": "SUBSCRIBER_NUMBER",
            "name": "Subscriber number",
            "description": "Subscriber number. Not required for new provisionings since Giacom will attribute one from its pool",
            "valueType": "subscriber number",
            "minCardinality": 0,
            "maxCardinality": 1,
            "isUnique": true,
            "configurable": true,
            "characteristicValueSpecification": [
                {
                    "isDefault": true,
                    "name": "Subscriber number",
                    "description": "Subscriber number",
                    "valueType": "subscriber number",
                    "regex": "regex_to_match_sn"
                }
            ]
        },
        {
            "id": "PAC",
            "name": "PAC",
            "description": "PAC used for porting the number to this network. This characteristic is deleted after porting",
            "valueType": "PAC",
            "minCardinality": 0,
            "maxCardinality": 1,
            "isUnique": true,
            "configurable": true,
            "characteristicValueSpecification": [
                {
                    "isDefault": true,
                    "name": "PAC",
                    "description": "PAC used for porting the number to this network. This characteristic is deleted after porting",
                    "valueType": "PAC",
                    "regex": "regex_to_match_pac"
                }
            ],
            "charSpecRelationship": [
                {
                    "relationshipType": "requires",
                    "characteristicSpecificationId": "SUBSCRIBER_NUMBER"
                }
            ]
        },
        {
            "id": "PORT_DATE",
            "name": "Port date",
            "description": "Port date",
            "valueType": "date-time",
            "minCardinality": 1,
            "maxCardinality": 1,
            "isUnique": false,
            "configurable": true,
            "characteristicValueSpecification": [
                {
                    "isDefault": true,
                    "name": "Port date",
                    "description": "Port date",
                    "valueType": "date-time",
                    "regex": "regex_to_match_date-time"
                }
            ],
            "charSpecRelationship": [
                {
                    "relationshipType": "requires",
                    "characteristicSpecificationId": "PAC"
                }
            ]
        },
        {
            "id": "SIM_TYPE",
            "name": "SIM type",
            "description": "Type of SIM card",
            "valueType": "string",
            "minCardinality": 1,
            "maxCardinality": 1,
            "isUnique": false,
            "configurable": true,
            "characteristicValueSpecification": [
                {
                    "isDefault": true,
                    "name": "e-SIM",
                    "description": "e-SIM",
                    "valueType": "string",
                    "value": "e_sim"
                },
                {
                    "isDefault": false,
                    "name": "Triple SIM",
                    "description": "Triple SIM",
                    "valueType": "string",
                    "value": "triple"
                }
            ]
        },
        {
            "id": "SIM_SERIAL",
            "name": "SIM Serial",
            "description": "SIM Serial",
            "valueType": "iccid",
            "minCardinality": 1,
            "maxCardinality": 1,
            "isUnique": true,
            "configurable": true,
            "characteristicValueSpecification": [
                {
                    "isDefault": true,
                    "name": "SIM Serial",
                    "description": "SIM Serial",
                    "valueType": "iccid",
                    "regex": "^89\\d{17,20}$"
                }
            ]
        },
        {
            "id": "ESIM_QR_CODE",
            "name": "eSIM QR CODE",
            "description": "eSIM CODE value to be sent as a QR code",
            "valueType": "base64",
            "minCardinality": 0,
            "maxCardinality": 0,
            "isUnique": true,
            "configurable": false,
            "characteristicValueSpecification": [
                {
                    "isDefault": true,
                    "name": "eSIM QR CODE",
                    "description": "eSIM CODE value to be sent as a QR code",
                    "valueType": "base64",
                    "regex": "regex_to_match_base64"
                }
            ],
            "charSpecRelationship": [
                {
                    "relationshipType": "value_eq",
                    "characteristicSpecificationId": "SIM_TYPE",
                    "characteristicSpecificationValue": "e_sim"
                }
            ]
        },
        {
            "id": "ESIM_DELIVERY_EMAIL",
            "name": "eSIM Delivery Email",
            "description": "eSIM Delivery Email",
            "valueType": "email",
            "minCardinality": 1,
            "maxCardinality": 1,
            "isUnique": false,
            "configurable": true,
            "characteristicValueSpecification": [
                {
                    "isDefault": true,
                    "name": "eSIM Delivery Email",
                    "description": "eSIM Delivery Email",
                    "valueType": "email",
                    "regex": "regex_to_match_email"
                }
            ],
            "charSpecRelationship": [
                {
                    "relationshipType": "value_eq",
                    "characteristicSpecificationId": "SIM_TYPE",
                    "characteristicSpecificationValue": "e_sim"
                }
            ]
        },
        {
            "id": "ESIM_CONTACT_NAME",
            "name": "eSIM contact name",
            "description": "eSIM delivery contact name",
            "valueType": "string",
            "minCardinality": 1,
            "maxCardinality": 1,
            "isUnique": false,
            "configurable": true,
            "characteristicValueSpecification": [
                {
                    "isDefault": true,
                    "name": "eSIM Contact name",
                    "description": "eSIM Contact name",
                    "valueType": "string",
                    "regex": "regex_to_match_name"
                }
            ],
            "charSpecRelationship": [
                {
                    "relationshipType": "value_eq",
                    "characteristicSpecificationId": "SIM_TYPE",
                    "characteristicSpecificationValue": "e_sim"
                }
            ]
        }
    ],
    "featureSpecification": [
        {
            "id": "SERVICE_SUSPENSION",
            "name": "Service suspension feature",
            "description": "Service suspension control. Enable to suspend. When enabled, the service is suspended on the system and on the network",
            "isBundle": false,
            "isEnabled": false
        },
        {
            "id": "BARS",
            "name": "bars bundle",
            "description": "List of Bars available for this mobile service",
            "isBundle": true,
            "isEnabled": true,
            "featureSpecRelationship": [
                {
                    "relationshipType": "includes",
                    "featureId": "BAR_ADMIN"
                },
                {
                    "relationshipType": "includes",
                    "featureId": "BAR_PREMIUM"
                },
                {
                    "relationshipType": "includes",
                    "featureId": "BAR_ROAMING"
                },
                {
                    "relationshipType": "includes",
                    "featureId": "BAR_INWHENROAM"
                },
                {
                    "relationshipType": "includes",
                    "featureId": "BAR_OUTWHENROAM"
                }
            ]
        },
        {
            "id": "BAR_ADMIN",
            "name": "Admin bar",
            "description": "Admin bar",
            "isBundle": false,
            "isEnabled": false
        },
        {
            "id": "BAR_PREMIUM",
            "name": "Premium Calls",
            "description": "Premium Calls",
            "isBundle": false,
            "isEnabled": true
        },
        {
            "id": "BAR_ROAMING",
            "name": "International Roaming",
            "description": "International Roaming",
            "isBundle": false,
            "isEnabled": true,
            "featureSpecRelationship": [
                {
                    "relationshipType": "excludes",
                    "featureId": "BAR_INWHENROAM"
                },
                {
                    "relationshipType": "excludes",
                    "featureId": "BAR_OUTWHENROAM"
                }
            ]
        },
        {
            "id": "BAR_INWHENROAM",
            "name": "Incoming Roaming",
            "description": "Incoming Roaming",
            "isBundle": false,
            "isEnabled": false,
            "featureSpecRelationship": [
                {
                    "relationshipType": "excludes",
                    "featureId": "BAR_ROAMING"
                }
            ]
        },
        {
            "id": "BAR_OUTWHENROAM",
            "name": "Outgoing Roaming",
            "description": "Outgoing Roaming",
            "isBundle": false,
            "isEnabled": false,
            "featureSpecRelationship": [
                {
                    "relationshipType": "excludes",
                    "featureId": "BAR_ROAMING"
                }
            ]
        },
        {
            "id": "NETWORK_SERVICES",
            "name": "Network services bundle",
            "description": "List of network services available for this mobile service",
            "isBundle": true,
            "isEnabled": true,
            "featureSpecRelationship": [
                {
                    "relationshipType": "includes",
                    "featureId": "NET_CONF_CALL"
                },
                {
                    "relationshipType": "includes",
                    "featureId": "NET_SRV_MMS"
                },
                {
                    "relationshipType": "includes",
                    "featureId": "NET_SRV_WIFI_CALL"
                }
            ]
        },
        {
            "id": "NET_CONF_CALL",
            "name": "Conference call",
            "description": "Conference call",
            "isBundle": false,
            "isEnabled": false
        },
        {
            "id": "NET_SRV_MMS",
            "name": "MMS service",
            "description": "MMS service",
            "isBundle": false,
            "isEnabled": true
        },
        {
            "id": "NET_SRV_WIFI_CALL",
            "name": "WiFi calling service",
            "description": "WiFi calling service",
            "isBundle": false,
            "isEnabled": false
        },
        {
            "id": "APNS",
            "name": "APN bundle",
            "description": "List of APN available for this mobile service",
            "isBundle": true,
            "isEnabled": true,
            "featureSpecRelationship": [
                {
                    "relationshipType": "includes",
                    "featureId": "APN_INTERNET"
                },
                {
                    "relationshipType": "includes",
                    "featureId": "APN_TETHERING"
                }
            ]
        },
        {
            "id": "APN_INTERNET",
            "name": "VF Internet APN",
            "description": "5G service",
            "isBundle": false,
            "isEnabled": true
        },
        {
            "id": "APN_TETHERING",
            "name": "Tethering",
            "description": "Tethering",
            "isBundle": false,
            "isEnabled": false
        }
    ]
}

Service Specification life cycle status

Service Specification entities have a life cycle that enables developing, testing, publishing and returning specifications.
API Clients with read-only access to Service Specifications can only read specifications in the following states:

Launched: A Specification which is live and available for ordering
Retired: A Specification which is still visible but no longer available for ordering. Since some live Inventory items may still be using the Specification, it is returned for reference only

Note: To access Specifications in other states, the Client needs the integrations/service.write scope

Mobile Service types

Mobile Services are defined through Service Specifications which define their characteristics, features and also their category.
Mobile Services support 3 categories:

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

Voice and Data services

Each Service Specification in each category of standalone mobile services may present a list of service tariffs which may be chosen to instantiate a mobile service. The available tariffs for each category are defined in the specCharacteristic with the ID = TARIFF. E.g.

            {
                "id": "TARIFF",
                "name": "Tariff",
                "description": "Giacom mobile tariff. Corresponds to the Giacom Mobile product",
                "valueType": "string",
                "configurable": true,
                "minCardinality": 1,
                "maxCardinality": 1,
                "isUnique": 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

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

Minutes
Text
Data
Roaming data

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
BOLTON_TARIFF: 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": "BOLTON_TARIFF",
                "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 "
                    },

Service configuration

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. Mobile Services include characteristics related with the following aspects of a mobile service:

Billing (for managed services only)
- Billing limits
Mobile Service tariff (i.e. the supplier's product)
Subscriber number
- SN, SPID
Portability
- PAC, Port date
SIM
- Type, Serial, SPID
- Particular characteristics for delivering a Vodafone eSiM

Characteristics visibility and purpose

Each Characteristics serves a distinct purpose and may have different visibility:

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. E.g. to display to a user.
- 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
- These characteristics are identifiable by defining configurable as False and having minCardinality as 0, meaning the client can't define a value when ordering
- E.g. BOLTON_TYPE defines min=0, max=0 and configurable=False meaning it is informational only. In this case, the ServiceSpecification defines a single value with the type of 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
- E.g. ESIM_QR_CODE defines min=0, max=0 and configurable=False meaning it is informational only. In this case, the ServiceSpecification doesn't define any value. This means it is a characteristic that will be defined by the system during provisioning
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 SUBSCRIBER_NUMBER. 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

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: BAR_ROAMING excludes BAR_INWHENROAM and BAR_OUTWHENROAM. If BAR_ROAMING is enabled, BAR_INWHENROAM and BAR_OUTWHENROAM cannot be enabled. If the rule is not observed, the system will fail the request

Ordering mobile services

A new mobile 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 specific action that affects a specific service (new or existing).

Service Order use case

Provision a new number

To provision a new number and activate the mobile service, a client needs to create a Service Order with:

A Service Order Item with the action = add
Define the service inside the Service Order Item by specifying:
- The Service Specification ID and its version
- The Characteristics to define and their values. Required characteristics in most cases are:
  - BILL_LIMIT
  - TARIFF
  - SIM_TYPE
  - SIM_SERIAL
    
    When NOT a Vodafone eSim
- The state of each Feature (enabled or disabled)
Any external reference the client needs for reference or filtering purposes

These are not processed by the system

Service Order example

Expand Service Order request example

This is an example of a Service Order request

{
    "externalReference": [
        {
            "id": "5001",
            "externalReferenceType": "order_id",
            "name": "ACME Comms"
        }
    ],
    "relatedParty": [
        {
            "role": "distributor",
            "partyOrPartyRole": {
                "id": "ACME Comms"
            }
        }
    ],
    "serviceOrderItem": [
        {
            "id": "1",
            "action": "add",
            "service": {
                "serviceSpecification": {
                    "id": "MOBILE_VOICE_SRV_GIACOM_O2",
                    "version": "1"
                },
                "externalIdentifier": [
                    {
                        "owner": "ACME Comms",
                        "externalIdentifierType": "service_id",
                        "id": "123"
                    }
                ],
                "relatedParty": [
                    {
                        "role": "distributor",
                        "partyOrPartyRole": {
                            "id": "ACME Comms"
                        }
                    }
                ],
                "serviceCharacteristic": [
                    {
                        "id": "BILL_LIMIT",
                        "value": [
                            {
                                "value": "100"
                            }
                        ]
                    },
                    {
                        "id": "TARIFF",
                        "value": [
                            {
                                "value": "62231"
                            }
                        ]
                    },
                    {
                        "id": "SIM_TYPE",
                        "value": [
                            {
                                "value": "triple"
                            }
                        ]
                    },
                    {
                        "id": "SIM_SERIAL",
                        "value": [
                            {
                                "value": "8944201122334455667"
                            }
                        ]
                    }
                ],
                "feature": [
                    {
                        "id": "BAR_PREMIUM",
                        "isEnabled": true
                    },
                    {
                        "id": "BAR_ROAMING",
                        "isEnabled": true
                    },
                    {
                        "id": "NET_CONF_CALL",
                        "isEnabled": true
                    },
                    {
                        "id": "NET_SRV_MMS",
                        "isEnabled": true
                    },
                    {
                        "id": "NET_SRV_WIFI_CALL",
                        "isEnabled": true
                    },
                    {
                        "id": "APN_INTERNET",
                        "isEnabled": true
                    },
                    {
                        "id": "APN_IPHONE_985",
                        "isEnabled": true
                    }
                ]
            }
        }
    ]
}

Expand Service Order response example

This is an example of a Service Order response.

Note that the response has an order state, an order item state, but no service state, or other service attributes besides the ones specified in the order request. Service Orders don't reflect the service state, but actually what was requested for that service.
The Retrieve a Service by ID endpoint should be used to get the complete and updated service state.

{
    "id": "38056a58-f783-453a-bc80-18d25ba8f3dc",
    "lastUpdate": "2025-02-12T16:06:44.318Z",
    "version": 2,
    "startDate": "2025-02-12T16:06:44.318Z",
    "state": "acknowledged",
    "externalReference": [
        {
            "id": "5001",
            "externalReferenceType": "order_id",
            "name": "ACME Comms"
        }
    ],
    "relatedParty": [
        {
            "role": "distributor",
            "partyOrPartyRole": {
                "id": "ACME Comms"
            }
        }
    ],
    "serviceOrderItem": [
        {
            "id": "1",
            "state": "acknowledged",
            "action": "add",
            "service": {
                "id": "dd5244e1-13e3-45a5-b2f0-47b111a65142",
                "serviceSpecification": {
                    "id": "MOBILE_VOICE_SRV_GIACOM_O2",
                    "version": "1"
                },
                "externalIdentifier": [
                    {
                        "owner": "ACME Comms",
                        "externalIdentifierType": "service_id",
                        "id": "123"
                    }
                ],
                "relatedParty": [
                    {
                        "role": "distributor",
                        "partyOrPartyRole": {
                            "id": "ACME Comms"
                        }
                    }
                ],
                "serviceCharacteristic": [
                    {
                        "id": "BILL_LIMIT",
                        "name": "Bill limit",
                        "description": "Bill limit",
                        "valueType": "int",
                        "value": [
                            {
                                "name": "Bill limit",
                                "description": "Bill limit",
                                "valueType": "int",
                                "value": "100"
                            }
                        ]
                    },
                    {
                        "id": "TARIFF",
                        "name": "Tariff",
                        "description": "Giacom mobile tariff. Corresponds to the Giacom Mobile product",
                        "valueType": "string",
                        "value": [
                            {
                                "name": "Tariff",
                                "description": "Giacom mobile tariff. Corresponds to the Giacom Mobile product",
                                "valueType": "string",
                                "value": "62231"
                            }
                        ]
                    },
                    {
                        "id": "SIM_TYPE",
                        "name": "SIM type",
                        "description": "Type of SIM card",
                        "valueType": "string",
                        "value": [
                            {
                                "name": "SIM type",
                                "description": "Type of SIM card",
                                "valueType": "string",
                                "value": "triple"
                            }
                        ]
                    },
                    {
                        "id": "SIM_SERIAL",
                        "name": "SIM Serial",
                        "description": "SIM Serial",
                        "valueType": "iccid",
                        "value": [
                            {
                                "name": "SIM Serial",
                                "description": "SIM Serial",
                                "valueType": "iccid",
                                "value": "8944201122334455667"
                            }
                        ]
                    }
                ],
                "feature": [
                    {
                        "id": "BAR_PREMIUM",
                        "name": "Premium Calls",
                        "description": "Premium Calls",
                        "isEnabled": true
                    },
                    {
                        "id": "BAR_ROAMING",
                        "name": "International Roaming",
                        "description": "International Roaming",
                        "isEnabled": true
                    },
                    {
                        "id": "NET_CONF_CALL",
                        "name": "Conference call",
                        "description": "Conference call",
                        "isEnabled": true
                    },
                    {
                        "id": "NET_SRV_MMS",
                        "name": "MMS service",
                        "description": "MMS service",
                        "isEnabled": true
                    },
                    {
                        "id": "NET_SRV_WIFI_CALL",
                        "name": "WiFi calling service",
                        "description": "WiFi calling service",
                        "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
                    }
                ]
            }
        }
    ]
}

Porting a number

To port a number and activate the mobile service, a client needs to create a Service Order with:

A Service Order Item with the action = add
Define the service inside the Service Order Item by specifying:
- The Service Specification ID and its version
- The Characteristics to define and their values. Required characteristics are:
  - All characteristics used to provision a new service
  - SUBSCRIBER_NUMBER
  - PAC
  - PORT_DATE
- The state of each Feature (enabled or disabled)
Any external reference the client needs for reference or filtering purposes

These are not processed by the system

Service Order example

Expand Service Order request example

This is an example of a Service Order request

{
    "externalReference": [
        {
            "id": "1002",
            "externalReferenceType": "order_id",
            "name": "ACME Comms"
        }
    ],
    "relatedParty": [
        {
            "role": "distributor",
            "partyOrPartyRole": {
                "id": "ACME Comms"
            }
        }
    ],
    "serviceOrderItem": [
        {
            "id": "1",
            "action": "add",
            "service": {
                "serviceSpecification": {
                    "id": "MOBILE_VOICE_SRV_GIACOM_VF",
                    "version": "1"
                },
                "relatedParty": [
                    {
                        "role": "distributor",
                        "partyOrPartyRole": {
                            "id": "ACME Comms"
                        }
                    }
                ],
                "serviceCharacteristic": [
                    {
                        "id": "BILL_LIMIT",
                        "value": [
                            {
                                "value": "100"
                            }
                        ]
                    },
                    {
                        "id": "TARIFF",
                        "value": [
                            {
                                "value": "55638"
                            }
                        ]
                    },
                    {
                        "id": "SUBSCRIBER_NUMBER",
                        "value": [
                            {
                                "value": "07400123456"
                            }
                        ]
                    },
                    {
                        "id": "PAC",
                        "value": [
                            {
                                "value": "VUK123456"
                            }
                        ]
                    },
                    {
                        "id": "PORT_DATE",
                        "value": [
                            {
                                "value": "2025-02-12T16:06:44.318Z"
                            }
                        ]
                    },
                    {
                        "id": "SIM_TYPE",
                        "value": [
                            {
                                "value": "e_sim"
                            }
                        ]
                    },
                    {
                        "id": "SIM_SERIAL",
                        "value": [
                            {
                                "value": "8944112233445566778"
                            }
                        ]
                    },
                    {
                        "id": "ESIM_DELIVERY_EMAIL",
                        "value": [
                            {
                                "value": "[email protected]"
                            }
                        ]
                    },
                    {
                        "id": "ESIM_CONTACT_NAME",
                        "value": [
                            {
                                "value": "someone"
                            }
                        ]
                    }
                ],
                "feature": [
                    {
                        "id": "BAR_PREMIUM",
                        "isEnabled": true
                    },
                    {
                        "id": "BAR_ROAMING",
                        "isEnabled": true
                    },
                    {
                        "id": "NET_CONF_CALL",
                        "isEnabled": true
                    },
                    {
                        "id": "NET_SRV_MMS",
                        "isEnabled": true
                    },
                    {
                        "id": "NET_SRV_WIFI_CALL",
                        "isEnabled": true
                    },
                    {
                        "id": "APN_INTERNET",
                        "isEnabled": true
                    },
                    {
                        "id": "APN_TETHERING",
                        "isEnabled": true
                    }
                ]
            }
        }
    ]
}

Order a Bolt-on

To add a Bolt-on to a live service, a client needs to create a Service Order with:

A Service Order Item with the action = add
Define the service inside a Service Order Item by specifying:
- The serviceRelationship defining the target live Mobile Service by ID from the Service Inventory and the relationship type addon_for
- The Service Specification ID and version of a Bolt-On
- The Characteristics to define and their values. Required characteristics are:
  - BOLTON_TARIFF
- Bolt-ons don't define Features
Any external reference the client needs for reference or filtering purposes

These are not processed by the system

Bolt-on Order request example

Expand Service Order request example

This is an example of a Bolt-on Service Order request

{
    "externalReference": [
        {
            "id": "1007",
            "externalReferenceType": "order_id",
            "name": "ACME Comms"
        }
    ],
    "relatedParty": [
        {
            "role": "distributor",
            "partyOrPartyRole": {
                "id": "ACME Comms"
            }
        }
    ],
    "serviceOrderItem": [
        {
            "id": "1",
            "action": "add",
            "service": {
                "serviceSpecification": {
                    "id": "GIACOM_O2_DATA_BOLT_ON",
                    "version": "1"
                },
                "externalIdentifier": [
                    {
                        "owner": "ACME Comms",
                        "externalIdentifierType": "service-id",
                        "id": "123"
                    }
                ],
                "relatedParty": [
                    {
                        "role": "distributor",
                        "partyOrPartyRole": {
                            "id": "ACME Comms"
                        }
                    }
                ],
                "serviceRelationship": [
                    {
                        "relationshipType": "addon_for",
                        "service": {
                            "id": "dd5244e1-13e3-45a5-b2f0-47b111a65142"
                        }
                    }
                ],
                "serviceCharacteristic": [
                    {
                        "id": "BOLTON_TARIFF",
                        "value": [
                            {
                                "value": "WODDTU1"
                            }
                        ]
                    }
                ],
                "feature": []
            }
        }
    ]
}

Cancel a Bolt-on

To cancel a Bolt-on of a live service, a client needs to create a Service Order with:

A Service Order Item with the action = delete
Define the Bolt-on service inside the Service Order Item by specifying:
- Its Service Instance ID
Any external reference the client needs for reference or filtering purposes

These are not processed by the system

Bolt-on cease order request example

Expand Bolt-on cease order request example

This is an example of a Cease Bolt-on Service Order request

{
    "externalReference": [
        {
            "id": "1017",
            "externalReferenceType": "order_id",
            "name": "ACME Comms"
        }
    ],
    "relatedParty": [
        {
            "role": "distributor",
            "partyOrPartyRole": {
                "id": "ACME Comms"
            }
        }
    ],
    "serviceOrderItem": [
        {
            "id": "1",
            "action": "delete",
            "service": {
                "id": "7"
            }
        }
    ]
}

Upgrading / Downgrading a Bolt-on

Bolt-on services are identified by two particular properties:

category: with the value "Mobile Bolt On"
ALLOWANCE_TYPE: This characteristic identifies the allowance type of the Bolt-on ServiceSpecifications. Some possible values are:
- Data Bolt-On
- Text Bolt-On
- Minute Bolt-On
- Roaming Data Bolt-On
- Iphone Bolt-On

Bolt-on rules for O2 and Vodafone through Giacom

For O2 and Vodafone through Giacom:

A mobile service can only have one active Bolt-on of each allowance type at any moment
A live Bolt-on cannot be modified. It can only be replaced by another Bolt-on instance or cancelled
To upgrade or downgrade a Bolt-on of a particular allowance type, e.g. Roaming Data, the client does NOT need to cease the current Bolt-on and order a new one. It is enough to just order the new one and system will automatically replace the existing one
Any change operations on a Bolt-on service will be rejected by the system. The only operations allowed on Bolt-on services are add and delete

Upgrading / Downgrading a Bolt-on of a particular allowance type

For O2 and Vodafone through Giacom:
- Send a normal order to add a Bolt-On of the same allowance type. The system will automatically cease the existing one
For other networks or providers in the future:
- Dependent on the support and behaviour.
  
  Not available at the moment

Change Bars

To change the bars on an active mobile service, a client needs to create a Service Order with:

A Service Order Item with the action = modify
Define the service inside the Service Order Item by specifying:
- The Service Instance ID
- The state of each Feature (enabled or disabled) part of the BARS feature bundle which needs to be changed
Any external reference the client needs for reference or filtering purposes

These are not processed by the system apart from removing duplicate entries
Any relatedParty the client wants for reference or filtering purposes

These are not processed by the system apart from validating they do not conflict with definitions int the ServiceSpecification

Change Bars Service Order example

Expand Change Bars Service Order request example

This is an example of a Service Order to change Bars request

{
    "externalReference": [
        {
            "id": "5003",
            "externalReferenceType": "order_id",
            "name": "ACME Comms"
        }
    ],
    "relatedParty": [
        {
            "role": "distributor",
            "partyOrPartyRole": {
                "id": "ACME Comms"
            }
        }
    ],
    "serviceOrderItem": [
        {
            "id": "1",
            "action": "modify",
            "service": {
                "id": "dd5244e1-13e3-45a5-b2f0-47b111a65142",
                "feature": [
                    {
                        "id": "BAR_ROAMING",
                        "isEnabled": false
                    },
                    {
                        "id": "BAR_INWHENROAM",
                        "isEnabled": true
                    },
                    {
                        "id": "BAR_OUTWHENROAM",
                        "isEnabled": true
                    }
                ]
            }
        }
    ]
}

Change Network Services

To change the Network Services on an active mobile service, a client needs to create a Service Order with:

A Service Order Item with the action = modify
Define the service inside the Service Order Item by specifying:
- The Service Instance ID
- The state of each Feature (enabled or disabled) part of the NETWORK_SERVICES feature bundle which needs to be changed
Any external reference the client needs for reference or filtering purposes

These are not processed by the system apart from removing duplicate entries
Any relatedParty the client wants for reference or filtering purposes

These are not processed by the system apart from validating they do not conflict with definitions int the ServiceSpecification

Change Network Services Service Order example

Expand Change Network Services Service Order request example

This is an example of a Service Order to change Network Services request

{
    "externalReference": [
        {
            "id": "5004",
            "externalReferenceType": "order_id",
            "name": "ACME Comms"
        }
    ],
    "relatedParty": [
        {
            "role": "distributor",
            "partyOrPartyRole": {
                "id": "ACME Comms"
            }
        }
    ],
    "serviceOrderItem": [
        {
            "id": "1",
            "action": "modify",
            "service": {
                "id": "dd5244e1-13e3-45a5-b2f0-47b111a65142",
                "feature": [
                    {
                        "id": "NET_CONF_CALL",
                        "isEnabled": false
                    },
                    {
                        "id": "NET_SRV_WIFI_CALL",
                        "isEnabled": false
                    }
                ]
            }
        }
    ]
}

Change APN

To change the APN on an active mobile service, a client needs to create a Service Order with:

A Service Order Item with the action = modify
Define the service inside the Service Order Item by specifying:
- The Service Instance ID
- The state of each Feature (enabled or disabled) part of the APNS feature bundle which needs to be changed
Any external reference the client needs for reference or filtering purposes

These are not processed by the system apart from removing duplicate entries
Any relatedParty the client wants for reference or filtering purposes

These are not processed by the system apart from validating they do not conflict with definitions int the ServiceSpecification

Change APN Service Order example

Expand Change APN Service Order request example

This is an example of a Service Order to change APN request

{
    "externalReference": [
        {
            "id": "5002",
            "externalReferenceType": "order_id",
            "name": "ACME Comms"
        }
    ],
    "relatedParty": [
        {
            "role": "distributor",
            "partyOrPartyRole": {
                "id": "ACME Comms"
            }
        }
    ],
    "serviceOrderItem": [
        {
            "id": "1",
            "action": "modify",
            "service": {
                "id": "dd5244e1-13e3-45a5-b2f0-47b111a65142",
                "feature": [
                    {
                        "id": "APN_IPHONE_985",
                        "isEnabled": false
                    },
                    {
                        "id": "APN_IPHONE_986",
                        "isEnabled": true
                    }
                ]
            }
        }
    ]
}

Cease a live service

To cease an active mobile service, a client needs to create a Service Order with:

A Service Order Item with the action = delete
Define the service inside the Service Order Item by specifying:
- Its Service Instance ID
- The endDate at which the service should be disconnected
Any external reference the client needs for reference or filtering purposes

These are not processed by the system

Service Order example

Expand Service Order request example

This is an example of a Service Order request

{
    "externalReference": [
        {
            "id": "5010",
            "externalReferenceType": "order_id",
            "name": "ACME Comms"
        }
    ],
    "relatedParty": [
        {
            "role": "distributor",
            "partyOrPartyRole": {
                "id": "ACME Comms"
            }
        }
    ],
    "serviceOrderItem": [
        {
            "id": "1",
            "action": "delete",
            "service": {
                "id": "dd5244e1-13e3-45a5-b2f0-47b111a65142",
                "endDate": "2025-09-01T00:00:00.000Z"
            }
        }
    ]
}

SIM Swap

To perform a SIM Swap on an active mobile service, a client needs to create a Service Order with:

A Service Order Item with the action = modify
Define the service inside the Service Order Item by specifying:
- The Service Instance ID
- The Service Specification ID and its version
- The Characteristics to define and their values. The required characteristics can be found below. The characteristics to define vary with the network and particular case:
  - SIM_SERIAL
  - SIM_TYPE
  - ESIM_QR_CODE
  - ESIM_DELIVERY_EMAIL
Any external reference the client needs for reference or filtering purposes

These are not processed by the system

Service Order example

Expand Service Order request example

This is an example of a Service Order request

{
    "externalReference": [
        {
            "id": "5005",
            "externalReferenceType": "order_id",
            "name": "ACME Comms"
        }
    ],
    "relatedParty": [
        {
            "role": "distributor",
            "partyOrPartyRole": {
                "id": "ACME Comms"
            }
        }
    ],
    "serviceOrderItem": [
        {
            "id": "1",
            "action": "modify",
            "service": {
                "id": "dd5244e1-13e3-45a5-b2f0-47b111a65142",
                "serviceCharacteristic": [
                    {
                        "id": "SIM_TYPE",
                        "value": [
                            {
                                "value": "triple"
                            }
                        ]
                    },
                    {
                        "id": "SIM_SERIAL",
                        "value": [
                            {
                                "value": "8944201122334455669"
                            }
                        ]
                    }
                ]
            }
        }
    ]
}

Giacom O2

For all cases of O2 through Giacom, the only required characteristics are:

SIM_SERIAL

Always required: Identifies the new SIM
SIM_TYPE

Since the serial will always be sent in any case, it is necessary to define the sim type only when changing it

Giacom Vodafone triple to triple

SIM_SERIAL

Identifies the new SIM
SIM_TYPE

Optional. Since a new SIM SERIAL is being requested, the system knows that it needs to perform a SIM Swap. Since there is no need to change the SIM_TYPE, the system will maintain the value if not present in the request and ignore the value if sent since it does not define a change

Giacom Vodafone triple to eSim

SIM_TYPE

Required to change the type
ESIM_DELIVERY_EMAIL

Required to define for Vodafone eSims
ESIM_CONTACT_NAME

Required to define for Vodafone eSims

Note: Vodafone Service Specifications define the SIM_SERIAL to be mandatory on the Service Instance unless on an eSim. Vodafone does not pre-dispatch eSims and generates them when requested only. This means the client can't have a SIM_Serial to make this request. It will be added by the system when completing the operation

Giacom Vodafone eSim to triple

SIM_SERIAL

Identifies the new SIM
SIM_TYPE

Required to change the type Note: ESIM_DELIVERY_EMAIL and ESIM_CONTACT_NAME can't be defined in the Service Inventory on Vodafone services using eSim. Since we are changing from eSim to triple, the client can omit this or pass a blank value. The system will remove the characteristic anyway since leaving it on the Instance would not keep it compliant with its specification. The system will also remove the QR_Code characteristic for the same reason

Giacom Vodafone eSim to eSim

SIM_SERIAL: Not included. See "Giacom Vodafone triple to eSim" above
SIM_TYPE

Mandatory. Since it is not possible to send a SIM_SERIAL in this case, SIM_TYPE needs to be sent to trigger the SIM Swap
ESIM_DELIVERY_EMAIL

Optional. The client can send a value to replace the current one or leave blank to reuse
ESIM_CONTACT_NAME

Optional. The client can send a value to replace the current one or leave blank to reuse

Convert from Voice to Data only and vice-versa

A mobile service can be converted from Voice and Data to Data only service and vice-versa by changing the Service Specification of the Service Instance to another spec with the correct category.
To confirm that a Mobile Service can be converted between Voice and Data, the client needs to check that the configuration of its Service Specifications has a serviceSpecRelationship which defines a convertible_to relationship with another spec. One should have a category of "Mobile Voice Service"" and the other "Mobile Data only Service".
To change the category of an active mobile service, a client needs to create a Service Order with:

A Service Order Item with the action = modify
Define the service inside the Service Order Item by specifying:
- The Service Instance ID
- The *new* Service Specification ID and its version
- The Characteristics to define and their values. Required characteristics are:
  - TARIFF: This is required to change the tariff
  - Any characteristic on the new spec and not in the current spec
  - Any characteristic whose value needs to change for the conversion
    
    The system will import and convert any informative or read-only characteristics from one specification to another
Any external reference the client needs for reference or filtering purposes

These are not processed by the system

Service category change example

Expand Service Order request example

This is an example of a Service Order request

{
    "externalReference": [
        {
            "id": "5009",
            "externalReferenceType": "order_id",
            "name": "ACME Comms"
        }
    ],
    "relatedParty": [
        {
            "role": "distributor",
            "partyOrPartyRole": {
                "id": "ACME Comms"
            }
        }
    ],
    "serviceOrderItem": [
        {
            "id": "1",
            "action": "modify",
            "service": {
                "id": "dd5244e1-13e3-45a5-b2f0-47b111a65142",
                "serviceSpecification": {
                    "id": "MOBILE_DATA_SRV_GIACOM_O2",
                    "version": "1"
                },
                "serviceCharacteristic": [
                    {
                        "id": "BILL_LIMIT",
                        "value": [
                            {
                                "value": "100"
                            }
                        ]
                    },
                    {
                        "id": "TARIFF",
                        "value": [
                            {
                                "value": "62225"
                            }
                        ]
                    },
                    {
                        "id": "SIM_TYPE",
                        "value": [
                            {
                                "value": "triple"
                            }
                        ]
                    },
                    {
                        "id": "SIM_SERIAL",
                        "value": [
                            {
                                "value": "8944201122334455669"
                            }
                        ]
                    },
                    {
                        "id": "SUBSCRIBER_NUMBER",
                        "value": [
                            {
                                "value": "07800987654"
                            }
                        ]
                    }
                ],
                "feature": [
                    {
                        "id": "SERVICE_SUSPENSION",
                        "isEnabled": false
                    },
                    {
                        "id": "BAR_ADMIN",
                        "isEnabled": false
                    },
                    {
                        "id": "BAR_PREMIUM",
                        "isEnabled": true
                    },
                    {
                        "id": "BAR_ROAMING",
                        "isEnabled": false
                    },
                    {
                        "id": "BAR_INWHENROAM",
                        "isEnabled": true
                    },
                    {
                        "id": "BAR_OUTWHENROAM",
                        "isEnabled": true
                    },
                    {
                        "id": "NET_CONF_CALL",
                        "isEnabled": false
                    },
                    {
                        "id": "NET_SRV_MMS",
                        "isEnabled": true
                    },
                    {
                        "id": "NET_SRV_WIFI_CALL",
                        "isEnabled": false
                    },
                    {
                        "id": "APN_INTERNET",
                        "isEnabled": true
                    },
                    {
                        "id": "APN_IPHONE_985",
                        "isEnabled": false
                    },
                    {
                        "id": "APN_IPHONE_986",
                        "isEnabled": true
                    }
                ]
            }
        }
    ]
}

Managing billing limits

This section covers use cases around managing bill limits for Giacom mobile services.

Billing limits are controlled by the service characteristic BILL_LIMIT.

Define the bill limit during provisioning

During provisioning the client may define a specific bill limit value by specifying the limit in the service order request:

{
    ...
    "serviceOrderItem": [
        {
            "id": "1",
            "action": "add",
            "service": {
                "serviceSpecification": {...},
                ...
                "serviceCharacteristic": [
                    {
                        "id": "BILL_LIMIT",
                        "value": [
                            {
                                "value": "100"
                            }
                        ]
                    },
                    ....
                ],
                "feature": [...]
            }
        }
    ]
}

Define no bill limit during provisioning

To provision a service without defining a bill limit, submit the service order without the BILL_LIMIT characteristic. The system will not consider bill limit and will configure the service as not defining any bill limit.

Note: It is possible to achieve the same result by including the characteristic and defining its value as 0 (zero)

Set or change the bill limit of a live service

A client may set or change the bill limit of a live service by placing a Service Order with the action modify and defining the new value.

{
    ...
    "serviceOrderItem": [
        {
            "id": "1",
            "action": "modify",
            "service": {
                "id": "dd5244e1-13e3-45a5-b2f0-47b111a65142",
                "serviceCharacteristic": [
                    {
                        "id": "BILL_LIMIT",
                        "value": [
                            {
                                "value": "100"
                            }
                        ]
                    }
                ]
            }
        }
    ]
}

Note: It is possible to combine this change with others on the same service order request

Clear the bill limit of a live service

Since it is not possible to explicitly delete a characteristic from a service using a service order, to clear the bill limit of a live service the client needs to send a request to change the BILL_LIMIT characteristic to 0 (zero).

{
    ...
    "serviceOrderItem": [
        {
            "id": "1",
            "action": "modify",
            "service": {
                "id": "dd5244e1-13e3-45a5-b2f0-47b111a65142",
                "serviceCharacteristic": [
                    {
                        "id": "BILL_LIMIT",
                        "value": [
                            {
                                "value": "0"
                            }
                        ]
                    }
                ]
            }
        }
    ]
}

Note: It is possible to combine this change with others on the same service order request

Reading a live service

To read the status of an active mobile service, a client needs to call the List or find Service objects or the Retrieve a Service by ID endpoints

Service Instance example

Expand Service Instance response example

This is an example of a GET Service Instance response

{
    "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,
    "state": "inactive",
    "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": "distributor",
            "partyOrPartyRole": {
                "id": "ACME Comms"
            }
        },
        {
            "role": "supplier",
            "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": "TARIFF",
            "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": "SIM_SERIAL",
            "name": "SIM Serial",
            "description": "SIM Serial",
            "valueType": "iccid",
            "value": [
                {
                    "name": "SIM Serial",
                    "description": "SIM Serial",
                    "valueType": "iccid",
                    "value": "8944201122334455667"
                }
            ]
        }
    ],
    "feature": [
        {
            "id": "SERVICE_SUSPENSION",
            "name": "Service suspension feature",
            "description": "Service suspension control. Enable to suspend. When enabled, the service is suspended on the system and on the network",
            "isEnabled": false
        },
        {
            "id": "BAR_ADMIN",
            "name": "Admin bar",
            "description": "Admin bar. When enabled, the service is suspended on the network",
            "isEnabled": false
        },
        {
            "id": "BAR_PREMIUM",
            "name": "Premium Calls",
            "description": "Premium Calls",
            "isEnabled": true
        },
        {
            "id": "BAR_ROAMING",
            "name": "International Roaming",
            "description": "International Roaming",
            "isEnabled": true
        },
        {
            "id": "BAR_INWHENROAM",
            "name": "Incoming Roaming",
            "description": "Incoming Roaming",
            "isEnabled": false
        },
        {
            "id": "BAR_OUTWHENROAM",
            "name": "Outgoing Roaming",
            "description": "Outgoing Roaming except to UK",
            "isEnabled": false
        },
        {
            "id": "NET_CONF_CALL",
            "name": "Conference call",
            "description": "Conference call",
            "isEnabled": true
        },
        {
            "id": "NET_SRV_MMS",
            "name": "MMS service",
            "description": "MMS service",
            "isEnabled": true
        },
        {
            "id": "NET_SRV_WIFI_CALL",
            "name": "WiFi calling service",
            "description": "WiFi calling service",
            "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
        }
    ]
}

Find a service by CLI (Subscriber Number)

Finding a service by subscriber number requires searching services by the value of its characteristics.
The API provides this mechanism in the advanced filtering section which uses JSONPath expressions
To search for services by their subscriber number:

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

Find a service by SIM Serial number

To search for services by the serial number of the SIM:

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

Force a network refresh

It is possible to force a network refresh to obtain a Service Instance freshly updated from the supplier's system.
To force the refresh, set the network_refresh = true header in the Retrieve a Service by ID endpoint.

Getting Started with Notifications

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>"

Authentication

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:

How Does It Work?

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.
Token Request: Your application will request an access token from our authorization server by providing the Client ID and Client Secret.
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.
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.
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:

Token Expiry: Access tokens are valid for a specific duration, after which they expire. The expiration time is typically included in the token response.
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.

API Basics

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.

Searching and filtering (TMF Section 4.2)

|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=="SUBSCRIBER_NUMBER")].value[?(@.value=="07800987654")]

Sample service representation for reference

This is an example of a Service Instance response

{
    "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,
    "state": "inactive",
    "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": "distributor",
            "partyOrPartyRole": {
                "id": "ACME Comms"
            }
        },
        {
            "role": "supplier",
            "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": "TARIFF",
            "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": "SIM_SERIAL",
            "name": "SIM Serial",
            "description": "SIM Serial",
            "valueType": "iccid",
            "value": [
                {
                    "name": "SIM Serial",
                    "description": "SIM Serial",
                    "valueType": "iccid",
                    "value": "8944201122334455667"
                }
            ]
        }
    ],
    "feature": [
        {
            "id": "SERVICE_SUSPENSION",
            "name": "Service suspension feature",
            "description": "Service suspension control. Enable to suspend. When enabled, the service is suspended on the system and on the network",
            "isEnabled": false
        },
        {
            "id": "BAR_ADMIN",
            "name": "Admin bar",
            "description": "Admin bar. When enabled, the service is suspended on the network",
            "isEnabled": false
        },
        {
            "id": "BAR_PREMIUM",
            "name": "Premium Calls",
            "description": "Premium Calls",
            "isEnabled": true
        },
        {
            "id": "BAR_ROAMING",
            "name": "International Roaming",
            "description": "International Roaming",
            "isEnabled": true
        },
        {
            "id": "BAR_INWHENROAM",
            "name": "Incoming Roaming",
            "description": "Incoming Roaming",
            "isEnabled": false
        },
        {
            "id": "BAR_OUTWHENROAM",
            "name": "Outgoing Roaming",
            "description": "Outgoing Roaming except to UK",
            "isEnabled": false
        },
        {
            "id": "NET_CONF_CALL",
            "name": "Conference call",
            "description": "Conference call",
            "isEnabled": true
        },
        {
            "id": "NET_SRV_MMS",
            "name": "MMS service",
            "description": "MMS service",
            "isEnabled": true
        },
        {
            "id": "NET_SRV_WIFI_CALL",
            "name": "WiFi calling service",
            "description": "WiFi calling service",
            "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
        }
    ]
}

Response shaping

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

Results paging

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

Results sorting

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

HTTP Responses

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:

`code`	`reason`
`ERR_000001`	ERR_000001: Request body validation error at field level

Giacom API Reference

Events Subscription

General concepts

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 :

Creates a Hub

Sets the callback endpoint for a client to receive event Notifications from services in the Giacom API.

The registration of a listener is done by creating a Notifications HUB resource unique to the listener (equivalent of a subscription). Only API destinations are supported.

The resource requires a Credentials object when the API destination is secured by a static API key. In that case, the API key will be securely stored and the Notifications service will include it in the Authorization header when delivering the notification.

Authorizations:

OAuth2OAuth2_UAT

Request Body schema: application/json
required

Data containing the callback endpoint to deliver the information

callback required	string The callback being registered.
	object

Responses

Request samples

Payload

Content type

application/json

{"callback": "string",
"credentials": {"type": "apikey",
"value": "123secret"
}
}

Response samples

Content type

application/json

{"id": "string",
"callback": "string",
"credentials": {"type": "apikey"
}
}

Retrieves a Hub by ID

This operation retrieves a Hub entity by ID

Authorizations:

OAuth2OAuth2_UAT

path Parameters

required

string

Identifier of the Resource

Responses

Response samples

Content type

application/json

{"id": "string",
"callback": "string",
"credentials": {"type": "apikey"
}
}

Deletes a Hub

This operation deletes a Hub entity.

Authorizations:

OAuth2OAuth2_UAT

path Parameters

required

string

Identifier of the Resource

Responses

Response samples

Content type

application/json

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

Resource Catalogue

Resource Specifications define the finer grained orderable entities in the API and provide a link between Services that Clients can order and what is provisioned on suppliers by the API.
E.g. Resource Specifications may define a SIM card or a particular mobile Bar

List or find ResourceSpecification objects

List or find ServiceSpecification objects.

Search Resource Specifications

TODO full list of fields allowed in the search query parameters.

Search examples

# E.g. list all resource specifications with "category" == "Mobile SIM" and with "VODAFONE" as the "network" on the "relatedParty" property
GET /resourceSpecification?category=Mobile SIM&filter=$.relatedParty[?(@.role=="network" && @.partyOrPartyRole.id=="O2")]

Authorizations:

OAuth2OAuth2_UAT

query Parameters

id	string <SCREAMING_SNAKE_CASE> Identifier of the entity. Performs full case-sensitive match
	integer or versionQualifiersEnum (string) The version to obtain. Returns the most recent version when this field is omitted. Supports passing a concrete version or specific qualifiers

Responses

Response samples

Content type

application/json

[{"id": "VF_triple_sim",
"lastUpdate": "2025-02-12T16:06:44.318Z",
"version": 1,
"name": "VF triple sim",
"description": "VF triple sim",
"category": "Mobile SIM",
"relatedParty": [{"role": "network",
"partyOrPartyRole": {"id": "VODAFONE"
}
}
],
"resourceSpecCharacteristic": [{"id": "SIM_TYPE",
"name": "SIM type",
"description": "SIM type",
"valueType": "string",
"minCardinality": 1,
"maxCardinality": 1,
"isUnique": false,
"configurable": false,
"characteristicValueSpecification": [{"isDefault": true,
"name": "Triple",
"description": "Triple SIM",
"valueType": "string",
"value": "triple"
}
]
},
{"id": "SIM_SERIAL",
"name": "SIM serial",
"description": "SIM serial",
"valueType": "iccid",
"minCardinality": 1,
"maxCardinality": 1,
"isUnique": true,
"configurable": true,
"characteristicValueSpecification": [{"isDefault": true,
"name": "SIM Serial",
"description": "SIM Serial",
"valueType": "iccid",
"regex": "^89\\d{17,20}$"
}
]
},
{"id": "SIM_SPID",
"name": "SPID",
"description": "SPID",
"valueType": "SPID",
"minCardinality": 1,
"maxCardinality": 1,
"isUnique": false,
"configurable": true,
"characteristicValueSpecification": [{"isDefault": true,
"name": "SPID",
"description": "SPID",
"valueType": "SPID",
"regex": "regex_to_match_SPID"
}
]
}
],
"resourceSpecRelationship": [{"relationshipType": "requires",
"id": "Mobile_Subscriber_number"
}
]
},
{"id": "VF_e_sim",
"lastUpdate": "2025-02-12T16:06:44.318Z",
"version": 1,
"name": "VF e-sim",
"description": "VF e-sim",
"category": "Mobile SIM",
"relatedParty": [{"role": "network",
"partyOrPartyRole": {"id": "VODAFONE"
}
}
],
"resourceSpecCharacteristic": [{"id": "SIM_TYPE",
"name": "SIM type",
"description": "SIM type",
"valueType": "string",
"minCardinality": 1,
"maxCardinality": 1,
"isUnique": false,
"configurable": false,
"characteristicValueSpecification": [{"isDefault": true,
"name": "e-SIM",
"description": "e-SIM",
"valueType": "string",
"value": "e_sim"
}
]
},
{"id": "SIM_SERIAL",
"name": "SIM serial",
"description": "SIM serial",
"valueType": "iccid",
"minCardinality": 1,
"maxCardinality": 1,
"isUnique": true,
"configurable": true,
"characteristicValueSpecification": [{"isDefault": true,
"name": "SIM Serial",
"description": "SIM Serial",
"valueType": "iccid",
"regex": "^89\\d{17,20}$"
}
]
},
{"id": "SIM_SPID",
"name": "SPID",
"description": "SPID",
"valueType": "SPID",
"minCardinality": 1,
"maxCardinality": 1,
"isUnique": false,
"configurable": true,
"characteristicValueSpecification": [{"isDefault": true,
"name": "SPID",
"description": "SPID",
"valueType": "SPID",
"regex": "regex_to_match_SPID"
}
]
},
{"id": "ESIM_QR_CODE",
"name": "eSIM QR CODE",
"description": "eSIM CODE value to be sent as a QR code",
"valueType": "base64",
"minCardinality": 0,
"maxCardinality": 1,
"isUnique": true,
"configurable": false,
"characteristicValueSpecification": [{"isDefault": true,
"name": "eSIM QR CODE",
"description": "eSIM CODE value to be sent as a QR code",
"valueType": "base64",
"regex": "regex_to_match_base64"
}
]
},
{"id": "ESIM_DELIVERY_EMAIL",
"name": "eSIM delivery email",
"description": "eSIM delivery email",
"valueType": "email",
"minCardinality": 1,
"maxCardinality": 1,
"isUnique": false,
"configurable": true,
"characteristicValueSpecification": [{"isDefault": true,
"name": "eSIM delivery email",
"description": "eSIM delivery email",
"valueType": "email",
"regex": "regex_to_match_email"
}
]
},
{"id": "ESIM_CONTACT_NAME",
"name": "eSIM Contact name",
"description": "eSIM Contact name",
"valueType": "string",
"minCardinality": 1,
"maxCardinality": 1,
"isUnique": false,
"configurable": false,
"characteristicValueSpecification": [{"isDefault": true,
"name": "eSIM Contact name",
"description": "eSIM Contact name",
"valueType": "string",
"regex": "regex_to_match_name"
}
]
}
],
"resourceSpecRelationship": [{"relationshipType": "requires",
"id": "Mobile_Subscriber_number"
}
]
}
]

Retrieves a ResourceSpecification by ID

This operation retrieves a ResourceSpecification entity. Attribute selection enabled for all first level attributes.

Authorizations:

OAuth2OAuth2_UAT

path Parameters

required

string <SCREAMING_SNAKE_CASE>

Identifier of the entity

query Parameters

version

integer <int64> >= 1

The version to obtain. Returns the most recent version when this field is omitted

Responses

Response samples

Content type

application/json

Example

CreateResSpec_O2_e_sim_Res

{"id": "O2_e_sim",
"lastUpdate": "2025-02-12T16:06:44.318Z",
"version": 1,
"name": "O2 e-sim",
"description": "O2 e-sim",
"category": "Mobile SIM",
"relatedParty": [{"role": "network",
"partyOrPartyRole": {"id": "O2"
}
}
],
"resourceSpecCharacteristic": [{"id": "SIM_TYPE",
"name": "SIM type",
"description": "SIM type",
"valueType": "string",
"minCardinality": 1,
"maxCardinality": 1,
"isUnique": false,
"configurable": false,
"characteristicValueSpecification": [{"isDefault": true,
"name": "e-SIM",
"description": "e-SIM",
"valueType": "string",
"value": "e_sim"
}
]
},
{"id": "SIM_SERIAL",
"name": "SIM serial",
"description": "SIM serial",
"valueType": "iccid",
"minCardinality": 1,
"maxCardinality": 1,
"isUnique": true,
"configurable": true,
"characteristicValueSpecification": [{"isDefault": true,
"name": "SIM Serial",
"description": "SIM Serial",
"valueType": "iccid",
"regex": "^89\\d{17,20}$"
}
]
},
{"id": "SIM_SPID",
"name": "SPID",
"description": "SPID",
"valueType": "SPID",
"minCardinality": 1,
"maxCardinality": 1,
"isUnique": false,
"configurable": true,
"characteristicValueSpecification": [{"isDefault": true,
"name": "SPID",
"description": "SPID",
"valueType": "SPID",
"regex": "regex_to_match_SPID"
}
]
}
],
"resourceSpecRelationship": [{"relationshipType": "requires",
"id": "Mobile_Subscriber_number"
}
]
}

Resource Instance

resource.md

List or find Resource objects

Authorizations:

OAuth2OAuth2_UAT

query Parameters

limit	integer Requested number of resources to be provided in response
filter	string Example: filter=attachment[?(@size==300)] Filter a collection using JSONPath

Responses

Response samples

Content type

application/json

[{"id": "string",
"endOperatingDate": "2019-08-24T14:15:22Z",
"administrativeState": "locked",
"operationalState": "enable",
"resourceStatus": "alarm",
"relatedParty": [{"role": "string",
"partyOrPartyRole": {"id": "string"
}
}
],
"resourceRelationship": [{"id": "string",
"relationshipType": "requires"
}
],
"resourceCharacteristic": [{"id": "string",
"valueType": "string",
"name": "string",
"description": "string",
"value": [{"name": "string",
"description": "string",
"valueType": "string",
"value": "string"
}
]
}
],
"resourceSpecification": {"id": "string",
"version": "string"
},
"startOperatingDate": "2019-08-24T14:15:22Z",
"externalIdentifier": [{"owner": "MagentoCommerce",
"externalIdentifierType": "ProductOrder",
"id": "string"
}
],
"category": "string",
"version": 1,
"lastUpdate": "2019-08-24T14:15:22Z"
}
]

Creates a Resource

This operation creates a Resource entity.

Authorizations:

OAuth2OAuth2_UAT

Request Body schema: application/json
required

The Resource to be created

administrativeState	string (ResourceAdministrativeStateType) Enum: "locked" "unlocked" "shutdown" ResourceAdministrativeStateType enumerations; values defined by ITU X.731: 'locked': The resource is administratively prohibited from performing services for its users; 'shutdown': Use of the resource is administratively permitted to existing instances of use only. While the system remains in the shutting down state the manager may at any time cause the managed object to revert to the unlocked state; 'unlocked': The resource is administratively permitted to perform services for its users. This is independent of its inherent operability.
operationalState	string (ResourceOperationalStateType) Enum: "enable" "disable" ResourceOperationalStateType enumerations; values defined by ITU X.731: 'disable': The resource is totally inoperable and unable to provide service to the user(s); 'enable': The resource is partially or fully operable and available for use.
resourceStatus	string (ResourceStatusType) Enum: "alarm" "available" "installed" "not exists" "pendingRemoval" "planned" "reserved" "standby" "suspended" "unknown" ResourceStatusType enumerations
	Array of objects (RelatedPartyRefOrPartyRoleRef)
	Array of objects (ResourceRelationship)
	Array of objects (Characteristic_FVO)
	object (ResourceSpecificationRef) Base schema for addressable entities
	Array of objects (ExternalIdentifier_FVO) An identification of this resource that is owned by or originates in a software system different from the current system. The structure identifies the system itself, the nature of the resource within the system and the unique ID of the resource within the system. It is anticipated that multiple external IDs can be held for a single resource, e.g. if the resource passed through multiple systems on the way to the current system.
category	string Category of the concrete resource, as copied from the Resource Specification. e.g Mobile SIM or Mobile Subscriber Number. The value of this field is defined by the value in the `category` field of the ResourceSpecification used to instantiate each Resource

Responses

Request samples

Payload

Content type

application/json

Example

CreateRes_SN_Req

{"administrativeState": "locked",
"operationalState": "disable",
"resourceStatus": "planned",
"relatedParty": [{"role": "distributor",
"partyOrPartyRole": {"id": "ACME Comms"
}
},
{"role": "supplier",
"partyOrPartyRole": {"id": "GIACOM"
}
},
{"role": "network",
"partyOrPartyRole": {"id": "VODAFONE"
}
}
],
"resourceSpecification": {"id": "Mobile_Subscriber_number"
},
"resourceCharacteristic": [{"id": "SUBSCRIBER_NUMBER",
"value": [{"value": "07571234567"
}
]
},
{"id": "SN_SPID",
"value": [{"value": "GS901234"
}
]
}
]
}

Response samples

Content type

application/json

Example

CreateRes_SN_Res

{"id": "1",
"lastUpdate": "2025-02-12T17:20:27.720Z",
"version": 1,
"startOperatingDate": "2025-02-12T17:20:27.720Z",
"endOperatingDate": "2026-02-12T17:20:27.720Z",
"administrativeState": "locked",
"operationalState": "disable",
"resourceStatus": "planned",
"relatedParty": [{"role": "distributor",
"partyOrPartyRole": {"id": "ACME Comms"
}
},
{"role": "supplier",
"partyOrPartyRole": {"id": "GIACOM"
}
},
{"role": "network",
"partyOrPartyRole": {"id": "VODAFONE"
}
}
],
"resourceSpecification": {"id": "Mobile_Subscriber_number"
},
"resourceCharacteristic": [{"id": "SUBSCRIBER_NUMBER",
"name": "phone number in subscriber number format",
"description": "phone number in subscriber number format",
"valueType": "subscriber number",
"value": [{"name": "phone number in subscriber number format",
"description": "phone number in subscriber number format",
"valueType": "subscriber number",
"value": "07571234567"
}
]
},
{"id": "SN_SPID",
"name": "SPID",
"description": "SPID",
"valueType": "SPID",
"value": [{"name": "SPID",
"description": "SPID",
"valueType": "SPID",
"value": "GS901234"
}
]
}
]
}

Retrieves a Resource by ID

This operation retrieves a Resource entity. Attribute selection enabled for all first level attributes.

Authorizations:

OAuth2OAuth2_UAT

path Parameters

required

string

Identifier of the Resource

Responses

Response samples

Content type

application/json

{"id": "string",
"endOperatingDate": "2019-08-24T14:15:22Z",
"administrativeState": "locked",
"operationalState": "enable",
"resourceStatus": "alarm",
"relatedParty": [{"role": "string",
"partyOrPartyRole": {"id": "string"
}
}
],
"resourceRelationship": [{"id": "string",
"relationshipType": "requires"
}
],
"resourceCharacteristic": [{"id": "string",
"valueType": "string",
"name": "string",
"description": "string",
"value": [{"name": "string",
"description": "string",
"valueType": "string",
"value": "string"
}
]
}
],
"resourceSpecification": {"id": "string",
"version": "string"
},
"startOperatingDate": "2019-08-24T14:15:22Z",
"externalIdentifier": [{"owner": "MagentoCommerce",
"externalIdentifierType": "ProductOrder",
"id": "string"
}
],
"category": "string",
"version": 1,
"lastUpdate": "2019-08-24T14:15:22Z"
}

Updates partially a Resource

This operation updates partially a Resource entity.

Authorizations:

OAuth2OAuth2_UAT

path Parameters

required

string

Identifier of the Resource

Request Body schema:
application/json
required

The Resource to be patched

endOperatingDate	string <date-time> A date time( DateTime). The date till the resource is operating
administrativeState	string (ResourceAdministrativeStateType) Enum: "locked" "unlocked" "shutdown" ResourceAdministrativeStateType enumerations; values defined by ITU X.731: 'locked': The resource is administratively prohibited from performing services for its users; 'shutdown': Use of the resource is administratively permitted to existing instances of use only. While the system remains in the shutting down state the manager may at any time cause the managed object to revert to the unlocked state; 'unlocked': The resource is administratively permitted to perform services for its users. This is independent of its inherent operability.
operationalState	string (ResourceOperationalStateType) Enum: "enable" "disable" ResourceOperationalStateType enumerations; values defined by ITU X.731: 'disable': The resource is totally inoperable and unable to provide service to the user(s); 'enable': The resource is partially or fully operable and available for use.
resourceStatus	string (ResourceStatusType) Enum: "alarm" "available" "installed" "not exists" "pendingRemoval" "planned" "reserved" "standby" "suspended" "unknown" ResourceStatusType enumerations
	Array of objects (RelatedPartyRefOrPartyRoleRef)
	Array of objects (ResourceRelationship)
	Array of objects (Characteristic_MVO)
	object (ResourceSpecificationRef) Base schema for addressable entities
startOperatingDate	string <date-time> A date time( DateTime). The date from which the resource is operating
	Array of objects (ExternalIdentifier_MVO) An identification of this resource that is owned by or originates in a software system different from the current system. The structure identifies the system itself, the nature of the resource within the system and the unique ID of the resource within the system. It is anticipated that multiple external IDs can be held for a single resource, e.g. if the resource passed through multiple systems on the way to the current system.
category	string Category of the concrete resource, as copied from the Resource Specification. e.g Mobile SIM or Mobile Subscriber Number. The value of this field is defined by the value in the `category` field of the ResourceSpecification used to instantiate each Resource

Responses

Request samples

Payload

Content type

application/json

{"endOperatingDate": "2019-08-24T14:15:22Z",
"administrativeState": "locked",
"operationalState": "enable",
"resourceStatus": "alarm",
"relatedParty": [{"role": "string",
"partyOrPartyRole": {"id": "string"
}
}
],
"resourceRelationship": [{"id": "string",
"relationshipType": "requires"
}
],
"resourceCharacteristic": [{"id": "string",
"value": [{"value": "string"
}
]
}
],
"resourceSpecification": {"id": "string",
"version": "string"
},
"startOperatingDate": "2019-08-24T14:15:22Z",
"externalIdentifier": [{"owner": "MagentoCommerce",
"externalIdentifierType": "ProductOrder",
"id": "string"
}
],
"category": "string"
}

Response samples

Content type

application/json

{"id": "string",
"endOperatingDate": "2019-08-24T14:15:22Z",
"administrativeState": "locked",
"operationalState": "enable",
"resourceStatus": "alarm",
"relatedParty": [{"role": "string",
"partyOrPartyRole": {"id": "string"
}
}
],
"resourceRelationship": [{"id": "string",
"relationshipType": "requires"
}
],
"resourceCharacteristic": [{"id": "string",
"valueType": "string",
"name": "string",
"description": "string",
"value": [{"name": "string",
"description": "string",
"valueType": "string",
"value": "string"
}
]
}
],
"resourceSpecification": {"id": "string",
"version": "string"
},
"startOperatingDate": "2019-08-24T14:15:22Z",
"externalIdentifier": [{"owner": "MagentoCommerce",
"externalIdentifierType": "ProductOrder",
"id": "string"
}
],
"category": "string",
"version": 1,
"lastUpdate": "2019-08-24T14:15:22Z"
}

Deletes a Resource

This operation deletes a Resource entity.

Authorizations:

OAuth2OAuth2_UAT

path Parameters

required

string

Identifier of the Resource

Responses

Response samples

Content type

application/json

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

Service Catalogue

The Service Catalogue allows managing and providing the catalogue of services available in the system.
The service catalogue is provided as a list of Service Specifications

When interpreting a ServiceSpecification it is important to understand the relation between characteristics and the relation between features.

Characteristics may specify relationships between themselves to control when certain characteristics are available for configuring a service based on other characteristics, such as only when another characteristic has been included and configured, or configured with a particular value
Features may specify relationships between themselves to create feature bundles and to implement mutual exclusion rules between features

Service Specification life cycle status

Launched: A Specification which is live and available for ordering
Retired: A Specification which is still visible but no longer available for ordering. Since some live Inventory items may still be using the Specification, it is returned for reference only

Note: To access Specifications in other states, the Client needs the integrations/service.write scope

List or find ServiceSpecification objects

List or find ResourceSpecification objects.

Search Service Specifications

Only allows access to specs on the tenant defined on the access token.
The integrations/service.write scope is required to read specs in states other than Launched and Retired
Can search by top level properties (exact match) using query parameters:
- id
- name
- category
- lifecycleStatus
- version
  
  Note: this field supports * to obtain all versions of each matched ServiceSpecification
Can search nested fields using JSONPATH:
- relatedParty

# E.g. list all service specifications with "category" == "Mobile Voice Service" supplied by Giacom
GET /serviceSpecification?category=Mobile Voice Service&filter=$.relatedParty[?(@.role=="supplier" && @.partyOrPartyRole.id=="GIACOM")]

Authorizations:

OAuth2OAuth2_UAT

query Parameters

limit	integer Requested number of resources to be provided in response. At the moment only `0` is supported as a valid limit to provide the total number of entities matching the criteria
id	string <SCREAMING_SNAKE_CASE> Identifier of the entity. Performs full case-sensitive match
name	string Name of the entity. If defined, a full case-sensitive equals match is applied
category	string (ServiceCategoryEnum) Enum: "Mobile Voice Service" "Mobile Data only Service" "Mobile Bolt On" Category of the entity. Supports IN queries by defining this parameter multiple times in the query with the different values
lifecycleStatus	string (CatalogueLifeCycleStatusEnum) Enum: "In study" "In design" "In test" "Launched" "Active" "Retired" "Obsolete" "Rejected" Status of the entity. Supports IN queries by defining this parameter multiple times in the query with the different values
	integer or versionQualifiersEnum (string) The version to obtain. Returns the most recent version when this field is omitted. Supports passing a concrete version or specific qualifiers
filter	string Example: filter=$.relatedParty[?(@.role=="supplier" && @.partyOrPartyRole.id=="GIACOM")] Filter using JSONPath. Supports searching `relatedParty`

Responses

Response samples

Content type

application/json

[{"id": "MOBILE_VOICE_SRV_GIACOM_VF",
"lastUpdate": "2025-02-12T16:06:44.318Z",
"version": 1,
"name": "Mobile Voice Giacom-VF",
"description": "Mobile Voice Giacom-VF",
"category": "Mobile Voice Service",
"isBundle": false,
"lifecycleStatus": "Launched",
"relatedParty": [{"role": "supplier",
"partyOrPartyRole": {"id": "GIACOM"
}
},
{"role": "network",
"partyOrPartyRole": {"id": "VF"
}
}
],
"specCharacteristic": [{"id": "BILL_LIMIT",
"name": "Bill limit",
"description": "Bill limit",
"valueType": "int",
"minCardinality": 0,
"maxCardinality": 1,
"isUnique": false,
"configurable": true,
"characteristicValueSpecification": [{"name": "Bill limit",
"description": "Bill limit value",
"isDefault": true,
"valueType": "int",
"valueFrom": 0,
"valueTo": 1000,
"regex": "^(0|[1-9]\\d{0,2}|1000)0$"
}
]
},
{"id": "TARIFF",
"name": "Tariff",
"description": "Giacom mobile tariff. Corresponds to the Giacom Mobile product",
"valueType": "string",
"configurable": true,
"minCardinality": 1,
"maxCardinality": 1,
"isUnique": true,
"characteristicValueSpecification": [{"name": "WS20GBBSE - O&O 20GB Special + WTS (ETS)",
"description": "WS20GBBSE - O&O 20GB Special + WTS (ETS)",
"valueType": "string",
"isDefault": true,
"value": "55629"
},
{"name": "WS20GBICE - O&O 20GB Special + WTS/IC (ETS)",
"description": "WS20GBICE - O&O 20GB Special + WTS/IC (ETS)",
"valueType": "string",
"isDefault": false,
"value": "55630"
},
{"name": "WS24GBRE - O&O 24GB Retention (ETS)",
"description": "WS24GBRE - O&O 24GB Retention (ETS)",
"valueType": "string",
"isDefault": false,
"value": "55638"
}
]
},
{"id": "SUBSCRIBER_NUMBER",
"name": "Subscriber number",
"description": "Subscriber number. Not required for new provisionings since Giacom will attribute one from its pool",
"valueType": "subscriber number",
"minCardinality": 0,
"maxCardinality": 1,
"isUnique": true,
"configurable": true,
"characteristicValueSpecification": [{"isDefault": true,
"name": "Subscriber number",
"description": "Subscriber number",
"valueType": "subscriber number",
"regex": "regex_to_match_sn"
}
]
},
{"id": "PAC",
"name": "PAC",
"description": "PAC used for porting the number to this network. This characteristic is deleted after porting",
"valueType": "PAC",
"minCardinality": 0,
"maxCardinality": 1,
"isUnique": true,
"configurable": true,
"characteristicValueSpecification": [{"isDefault": true,
"name": "PAC",
"description": "PAC used for porting the number to this network. This characteristic is deleted after porting",
"valueType": "PAC",
"regex": "regex_to_match_pac"
}
],
"charSpecRelationship": [{"relationshipType": "requires",
"characteristicSpecificationId": "SUBSCRIBER_NUMBER"
}
]
},
{"id": "PORT_DATE",
"name": "Port date",
"description": "Port date",
"valueType": "date-time",
"minCardinality": 1,
"maxCardinality": 1,
"isUnique": false,
"configurable": true,
"characteristicValueSpecification": [{"isDefault": true,
"name": "Port date",
"description": "Port date",
"valueType": "date-time",
"regex": "regex_to_match_date-time"
}
],
"charSpecRelationship": [{"relationshipType": "requires",
"characteristicSpecificationId": "PAC"
}
]
},
{"id": "SIM_TYPE",
"name": "SIM type",
"description": "Type of SIM card",
"valueType": "string",
"minCardinality": 1,
"maxCardinality": 1,
"isUnique": false,
"configurable": true,
"characteristicValueSpecification": [{"isDefault": true,
"name": "e-SIM",
"description": "e-SIM",
"valueType": "string",
"value": "e_sim"
},
{"isDefault": false,
"name": "Triple SIM",
"description": "Triple SIM",
"valueType": "string",
"value": "triple"
}
]
},
{"id": "SIM_SERIAL",
"name": "SIM Serial",
"description": "SIM Serial",
"valueType": "iccid",
"minCardinality": 1,
"maxCardinality": 1,
"isUnique": true,
"configurable": true,
"characteristicValueSpecification": [{"isDefault": true,
"name": "SIM Serial",
"description": "SIM Serial",
"valueType": "iccid",
"regex": "^89\\d{17,20}$"
}
]
},
{"id": "ESIM_QR_CODE",
"name": "eSIM QR CODE",
"description": "eSIM CODE value to be sent as a QR code",
"valueType": "base64",
"minCardinality": 0,
"maxCardinality": 0,
"isUnique": true,
"configurable": false,
"characteristicValueSpecification": [{"isDefault": true,
"name": "eSIM QR CODE",
"description": "eSIM CODE value to be sent as a QR code",
"valueType": "base64",
"regex": "regex_to_match_base64"
}
],
"charSpecRelationship": [{"relationshipType": "value_eq",
"characteristicSpecificationId": "SIM_TYPE",
"characteristicSpecificationValue": "e_sim"
}
]
},
{"id": "ESIM_DELIVERY_EMAIL",
"name": "eSIM Delivery Email",
"description": "eSIM Delivery Email",
"valueType": "email",
"minCardinality": 1,
"maxCardinality": 1,
"isUnique": false,
"configurable": true,
"characteristicValueSpecification": [{"isDefault": true,
"name": "eSIM Delivery Email",
"description": "eSIM Delivery Email",
"valueType": "email",
"regex": "regex_to_match_email"
}
],
"charSpecRelationship": [{"relationshipType": "value_eq",
"characteristicSpecificationId": "SIM_TYPE",
"characteristicSpecificationValue": "e_sim"
}
]
},
{"id": "ESIM_CONTACT_NAME",
"name": "eSIM contact name",
"description": "eSIM delivery contact name",
"valueType": "string",
"minCardinality": 1,
"maxCardinality": 1,
"isUnique": false,
"configurable": true,
"characteristicValueSpecification": [{"isDefault": true,
"name": "eSIM Contact name",
"description": "eSIM Contact name",
"valueType": "string",
"regex": "regex_to_match_name"
}
],
"charSpecRelationship": [{"relationshipType": "value_eq",
"characteristicSpecificationId": "SIM_TYPE",
"characteristicSpecificationValue": "e_sim"
}
]
}
],
"featureSpecification": [{"id": "SERVICE_SUSPENSION",
"name": "Service suspension feature",
"description": "Service suspension control. Enable to suspend. When enabled, the service is suspended on the system and on the network",
"isBundle": false,
"isEnabled": false
},
{"id": "BARS",
"name": "bars bundle",
"description": "List of Bars available for this mobile service",
"isBundle": true,
"isEnabled": true,
"featureSpecRelationship": [{"relationshipType": "includes",
"featureId": "BAR_ADMIN"
},
{"relationshipType": "includes",
"featureId": "BAR_PREMIUM"
},
{"relationshipType": "includes",
"featureId": "BAR_ROAMING"
},
{"relationshipType": "includes",
"featureId": "BAR_INWHENROAM"
},
{"relationshipType": "includes",
"featureId": "BAR_OUTWHENROAM"
}
]
},
{"id": "BAR_ADMIN",
"name": "Admin bar",
"description": "Admin bar",
"isBundle": false,
"isEnabled": false
},
{"id": "BAR_PREMIUM",
"name": "Premium Calls",
"description": "Premium Calls",
"isBundle": false,
"isEnabled": true
},
{"id": "BAR_ROAMING",
"name": "International Roaming",
"description": "International Roaming",
"isBundle": false,
"isEnabled": true,
"featureSpecRelationship": [{"relationshipType": "excludes",
"featureId": "BAR_INWHENROAM"
},
{"relationshipType": "excludes",
"featureId": "BAR_OUTWHENROAM"
}
]
},
{"id": "BAR_INWHENROAM",
"name": "Incoming Roaming",
"description": "Incoming Roaming",
"isBundle": false,
"isEnabled": false,
"featureSpecRelationship": [{"relationshipType": "excludes",
"featureId": "BAR_ROAMING"
}
]
},
{"id": "BAR_OUTWHENROAM",
"name": "Outgoing Roaming",
"description": "Outgoing Roaming",
"isBundle": false,
"isEnabled": false,
"featureSpecRelationship": [{"relationshipType": "excludes",
"featureId": "BAR_ROAMING"
}
]
},
{"id": "NETWORK_SERVICES",
"name": "Network services bundle",
"description": "List of network services available for this mobile service",
"isBundle": true,
"isEnabled": true,
"featureSpecRelationship": [{"relationshipType": "includes",
"featureId": "NET_CONF_CALL"
},
{"relationshipType": "includes",
"featureId": "NET_SRV_MMS"
},
{"relationshipType": "includes",
"featureId": "NET_SRV_WIFI_CALL"
}
]
},
{"id": "NET_CONF_CALL",
"name": "Conference call",
"description": "Conference call",
"isBundle": false,
"isEnabled": false
},
{"id": "NET_SRV_MMS",
"name": "MMS service",
"description": "MMS service",
"isBundle": false,
"isEnabled": true
},
{"id": "NET_SRV_WIFI_CALL",
"name": "WiFi calling service",
"description": "WiFi calling service",
"isBundle": false,
"isEnabled": false
},
{"id": "APNS",
"name": "APN bundle",
"description": "List of APN available for this mobile service",
"isBundle": true,
"isEnabled": true,
"featureSpecRelationship": [{"relationshipType": "includes",
"featureId": "APN_INTERNET"
},
{"relationshipType": "includes",
"featureId": "APN_TETHERING"
}
]
},
{"id": "APN_INTERNET",
"name": "VF Internet APN",
"description": "5G service",
"isBundle": false,
"isEnabled": true
},
{"id": "APN_TETHERING",
"name": "Tethering",
"description": "Tethering",
"isBundle": false,
"isEnabled": false
}
]
},
{"id": "MOBILE_VOICE_SRV_GIACOM_O2",
"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,
"lifecycleStatus": "Launched",
"relatedParty": [{"role": "supplier",
"partyOrPartyRole": {"id": "GIACOM"
}
},
{"role": "network",
"partyOrPartyRole": {"id": "O2"
}
}
],
"specCharacteristic": [{"id": "BILL_LIMIT",
"name": "Bill limit",
"description": "Bill limit",
"valueType": "int",
"minCardinality": 0,
"maxCardinality": 1,
"isUnique": false,
"configurable": true,
"characteristicValueSpecification": [{"name": "Bill limit",
"description": "Bill limit value",
"isDefault": true,
"valueType": "int",
"valueFrom": 0,
"valueTo": 1000,
"regex": "^(0|[1-9]\\d{0,2}|1000)0$"
}
]
},
{"id": "TARIFF",
"name": "Tariff",
"description": "Giacom mobile tariff. Corresponds to the Giacom Mobile product",
"valueType": "string",
"configurable": true,
"minCardinality": 1,
"maxCardinality": 1,
"isUnique": 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"
}
]
},
{"id": "SUBSCRIBER_NUMBER",
"name": "Subscriber number",
"description": "Subscriber number. Not required for new provisionings since Giacom will attribute one from its pool",
"valueType": "subscriber number",
"minCardinality": 0,
"maxCardinality": 1,
"isUnique": true,
"configurable": true,
"characteristicValueSpecification": [{"isDefault": true,
"name": "Subscriber number",
"description": "Subscriber number",
"valueType": "subscriber number",
"regex": "regex_to_match_sn"
}
]
},
{"id": "PAC",
"name": "PAC",
"description": "PAC used for porting the number to this network. This characteristic is deleted after porting",
"valueType": "PAC",
"minCardinality": 0,
"maxCardinality": 1,
"isUnique": true,
"configurable": true,
"characteristicValueSpecification": [{"isDefault": true,
"name": "PAC",
"description": "PAC used for porting the number to this network. This characteristic is deleted after porting",
"valueType": "PAC",
"regex": "regex_to_match_pac"
}
],
"charSpecRelationship": [{"relationshipType": "requires",
"characteristicSpecificationId": "SUBSCRIBER_NUMBER"
}
]
},
{"id": "PORT_DATE",
"name": "Port date",
"description": "Port date",
"valueType": "date-time",
"minCardinality": 1,
"maxCardinality": 1,
"isUnique": false,
"configurable": true,
"characteristicValueSpecification": [{"isDefault": true,
"name": "Port date",
"description": "Port date",
"valueType": "date-time",
"regex": "regex_to_match_date-time"
}
],
"charSpecRelationship": [{"relationshipType": "requires",
"characteristicSpecificationId": "PAC"
}
]
},
{"id": "SIM_TYPE",
"name": "SIM type",
"description": "Type of SIM card",
"valueType": "string",
"minCardinality": 1,
"maxCardinality": 1,
"isUnique": false,
"configurable": true,
"characteristicValueSpecification": [{"isDefault": true,
"name": "e-SIM",
"description": "e-SIM",
"valueType": "string",
"value": "e_sim"
},
{"isDefault": false,
"name": "Triple SIM",
"description": "Triple SIM",
"valueType": "string",
"value": "triple"
}
]
},
{"id": "SIM_SERIAL",
"name": "SIM Serial",
"description": "SIM Serial",
"valueType": "iccid",
"minCardinality": 1,
"maxCardinality": 1,
"isUnique": true,
"configurable": true,
"characteristicValueSpecification": [{"isDefault": true,
"name": "SIM Serial",
"description": "SIM Serial",
"valueType": "iccid",
"regex": "^89\\d{17,20}$"
}
]
}
],
"featureSpecification": [{"id": "SERVICE_SUSPENSION",
"name": "Service suspension feature",
"description": "Service suspension control. Enable to suspend. When enabled, the service is suspended on the system and on the network",
"isBundle": false,
"isEnabled": false
},
{"id": "BARS",
"name": "bars bundle",
"description": "List of Bars available for this mobile service",
"isBundle": true,
"isEnabled": true,
"featureSpecRelationship": [{"relationshipType": "includes",
"featureId": "BAR_ADMIN"
},
{"relationshipType": "includes",
"featureId": "BAR_PREMIUM"
},
{"relationshipType": "includes",
"featureId": "BAR_ROAMING"
},
{"relationshipType": "includes",
"featureId": "BAR_INWHENROAM"
},
{"relationshipType": "includes",
"featureId": "BAR_OUTWHENROAM"
}
]
},
{"id": "BAR_ADMIN",
"name": "Admin bar",
"description": "Admin bar",
"isBundle": false,
"isEnabled": false
},
{"id": "BAR_PREMIUM",
"name": "Premium Calls",
"description": "Premium Calls",
"isBundle": false,
"isEnabled": true
},
{"id": "BAR_ROAMING",
"name": "International Roaming",
"description": "International Roaming",
"isBundle": false,
"isEnabled": true,
"featureSpecRelationship": [{"relationshipType": "excludes",
"featureId": "BAR_INWHENROAM"
},
{"relationshipType": "excludes",
"featureId": "BAR_OUTWHENROAM"
}
]
},
{"id": "BAR_INWHENROAM",
"name": "Incoming Roaming",
"description": "Incoming Roaming",
"isBundle": false,
"isEnabled": false,
"featureSpecRelationship": [{"relationshipType": "excludes",
"featureId": "BAR_ROAMING"
}
]
},
{"id": "BAR_OUTWHENROAM",
"name": "Outgoing Roaming",
"description": "Outgoing Roaming except to UK",
"isBundle": false,
"isEnabled": false,
"featureSpecRelationship": [{"relationshipType": "excludes",
"featureId": "BAR_ROAMING"
}
]
},
{"id": "NETWORK_SERVICES",
"name": "Network services bundle",
"description": "List of network services available for this mobile service",
"isBundle": true,
"isEnabled": true,
"featureSpecRelationship": [{"relationshipType": "includes",
"featureId": "NET_CONF_CALL"
},
{"relationshipType": "includes",
"featureId": "NET_SRV_MMS"
},
{"relationshipType": "includes",
"featureId": "NET_SRV_WIFI_CALL"
}
]
},
{"id": "NET_CONF_CALL",
"name": "Conference call",
"description": "Conference call",
"isBundle": false,
"isEnabled": false
},
{"id": "NET_SRV_MMS",
"name": "MMS service",
"description": "MMS service",
"isBundle": false,
"isEnabled": true
},
{"id": "NET_SRV_WIFI_CALL",
"name": "WiFi calling service",
"description": "WiFi calling service",
"isBundle": false,
"isEnabled": false
},
{"id": "APNS",
"name": "APN bundle",
"description": "List of APN available for this mobile service",
"isBundle": true,
"isEnabled": true,
"featureSpecRelationship": [{"relationshipType": "includes",
"featureId": "APN_INTERNET"
},
{"relationshipType": "includes",
"featureId": "APN_IPHONE_985"
},
{"relationshipType": "includes",
"featureId": "APN_IPHONE_986"
}
]
},
{"id": "APN_INTERNET",
"name": "O2 Internet APN",
"description": "5G service",
"isBundle": false,
"isEnabled": true
},
{"id": "APN_IPHONE_985",
"name": "O2 iPhone APN 985",
"description": "O2 iPhone APN 985",
"isBundle": false,
"isEnabled": false
},
{"id": "APN_IPHONE_986",
"name": "O2 iPhone APN 986",
"description": "O2 iPhone APN 986",
"isBundle": false,
"isEnabled": false
}
]
}
]

Retrieves a ServiceSpecification by ID

This operation retrieves a ServiceSpecification entity by ID.

Only allow access to specs on the tenant from the access token
The integrations/service.write scope is required to read specs in states not Launched or Retired
The system must return only one version, considering:
- If the client specified a versionin the query parameter, try to return that version
- If the version is omitted, return the most current version, considering:
  - if the request has the integrations/service.write, return the highest version overall
  - Otherwise, return the highest version in the 'Launched' state. If there is none, return the highest version in the Retired state

Authorizations:

OAuth2OAuth2_UAT

path Parameters

required

string <SCREAMING_SNAKE_CASE>

Identifier of the entity

query Parameters

version

integer <int64> >= 1

The version to obtain. Returns the most recent version when this field is omitted

Responses

Response samples

Content type

application/json

Example

Direct O2

{"id": "MOBILE_VOICE_SRV_ACME_O2",
"lastUpdate": "2025-02-12T16:06:44.318Z",
"version": 1,
"name": "Mobile Voice ACME-O2",
"description": "Mobile Voice ACME-O2",
"category": "Mobile Voice Service",
"isBundle": false,
"lifecycleStatus": "Launched",
"relatedParty": [{"role": "supplier",
"partyOrPartyRole": {"id": "O2"
}
},
{"role": "network",
"partyOrPartyRole": {"id": "O2"
}
}
],
"specCharacteristic": [{"id": "TARIFF",
"name": "Tariff",
"description": "Direct mobile tariff. Corresponds to the network tariff",
"valueType": "string",
"configurable": true,
"minCardinality": 1,
"maxCardinality": 1,
"isUnique": true,
"characteristicValueSpecification": [{"name": "O2- NET Tariff - V2IP1",
"description": "O2- NET Tariff - V2IP1",
"valueType": "string",
"isDefault": true,
"value": "4G8GB"
},
{"name": "O2- NET Tariff - V3H1G",
"description": "O2- NET Tariff - V3H1G",
"valueType": "string",
"isDefault": false,
"value": "V2WMT"
},
{"name": "O2- NET Tariff - V3HH5",
"description": "O2- NET Tariff - V3HH5",
"valueType": "string",
"isDefault": false,
"value": "V2I3T"
}
]
},
{"id": "SUBSCRIBER_NUMBER",
"name": "Subscriber number",
"description": "Subscriber number from a partner managed pool. Required for direct provisioning",
"valueType": "subscriber number",
"minCardinality": 1,
"maxCardinality": 1,
"isUnique": true,
"configurable": true,
"characteristicValueSpecification": [{"isDefault": true,
"name": "Subscriber number",
"description": "Subscriber number",
"valueType": "subscriber number",
"regex": "regex_to_match_sn"
}
]
},
{"id": "SPID",
"name": "SPID",
"description": "SPID",
"valueType": "SPID",
"minCardinality": 1,
"maxCardinality": 1,
"isUnique": false,
"configurable": true,
"characteristicValueSpecification": [{"name": "SPID",
"description": "SPID",
"isDefault": true,
"valueType": "SPID",
"regex": "regex_to_match_SPID"
}
]
},
{"id": "PAC",
"name": "PAC",
"description": "PAC used for porting the number to this network. This characteristic is deleted after porting",
"valueType": "PAC",
"minCardinality": 0,
"maxCardinality": 1,
"isUnique": true,
"configurable": true,
"characteristicValueSpecification": [{"isDefault": true,
"name": "PAC",
"description": "PAC used for porting the number to this network. This characteristic is deleted after porting",
"valueType": "PAC",
"regex": "regex_to_match_pac"
}
],
"charSpecRelationship": [{"relationshipType": "requires",
"characteristicSpecificationId": "SUBSCRIBER_NUMBER"
}
]
},
{"id": "PORT_DATE",
"name": "Port date",
"description": "Port date",
"valueType": "date-time",
"minCardinality": 1,
"maxCardinality": 1,
"isUnique": false,
"configurable": true,
"characteristicValueSpecification": [{"isDefault": true,
"name": "Port date",
"description": "Port date",
"valueType": "date-time",
"regex": "regex_to_match_date-time"
}
],
"charSpecRelationship": [{"relationshipType": "requires",
"characteristicSpecificationId": "PAC"
}
]
},
{"id": "SIM_TYPE",
"name": "SIM type",
"description": "Type of SIM card",
"valueType": "string",
"minCardinality": 1,
"maxCardinality": 1,
"isUnique": false,
"configurable": true,
"characteristicValueSpecification": [{"isDefault": true,
"name": "e-SIM",
"description": "e-SIM",
"valueType": "string",
"value": "e_sim"
},
{"isDefault": false,
"name": "Triple SIM",
"description": "Triple SIM",
"valueType": "string",
"value": "triple"
}
]
},
{"id": "SIM_SERIAL",
"name": "SIM Serial",
"description": "SIM Serial",
"valueType": "iccid",
"minCardinality": 1,
"maxCardinality": 1,
"isUnique": true,
"configurable": true,
"characteristicValueSpecification": [{"isDefault": true,
"name": "SIM Serial",
"description": "SIM Serial",
"valueType": "iccid",
"regex": "^89\\d{17,20}$"
}
]
}
],
"featureSpecification": [{"id": "SERVICE_SUSPENSION",
"name": "Service suspension feature",
"description": "Service suspension control. Enable to suspend. When enabled, the service is suspended on the system and on the network",
"isBundle": false,
"isEnabled": false
},
{"id": "BARS",
"name": "bars bundle",
"description": "List of Bars available for this mobile service",
"isBundle": true,
"isEnabled": true,
"featureSpecRelationship": [{"relationshipType": "includes",
"featureId": "BAR_ADMIN"
},
{"relationshipType": "includes",
"featureId": "BAR_PREMIUM"
},
{"relationshipType": "includes",
"featureId": "BAR_ROAMING"
},
{"relationshipType": "includes",
"featureId": "BAR_INWHENROAM"
},
{"relationshipType": "includes",
"featureId": "BAR_OUTWHENROAM"
}
]
},
{"id": "BAR_ADMIN",
"name": "Admin bar",
"description": "Admin bar",
"isBundle": false,
"isEnabled": false
},
{"id": "BAR_PREMIUM",
"name": "Premium Calls",
"description": "Premium Calls",
"isBundle": false,
"isEnabled": true
},
{"id": "BAR_ROAMING",
"name": "International Roaming",
"description": "International Roaming",
"isBundle": false,
"isEnabled": true,
"featureSpecRelationship": [{"relationshipType": "excludes",
"featureId": "BAR_INWHENROAM"
},
{"relationshipType": "excludes",
"featureId": "BAR_OUTWHENROAM"
}
]
},
{"id": "BAR_INWHENROAM",
"name": "Incoming Roaming",
"description": "Incoming Roaming",
"isBundle": false,
"isEnabled": false,
"featureSpecRelationship": [{"relationshipType": "excludes",
"featureId": "BAR_ROAMING"
}
]
},
{"id": "BAR_OUTWHENROAM",
"name": "Outgoing Roaming",
"description": "Outgoing Roaming except to UK",
"isBundle": false,
"isEnabled": false,
"featureSpecRelationship": [{"relationshipType": "excludes",
"featureId": "BAR_ROAMING"
}
]
},
{"id": "NETWORK_SERVICES",
"name": "Network services bundle",
"description": "List of network services available for this mobile service",
"isBundle": true,
"isEnabled": true,
"featureSpecRelationship": [{"relationshipType": "includes",
"featureId": "NET_CONF_CALL"
},
{"relationshipType": "includes",
"featureId": "NET_SRV_MMS"
},
{"relationshipType": "includes",
"featureId": "NET_SRV_WIFI_CALL"
}
]
},
{"id": "NET_CONF_CALL",
"name": "Conference call",
"description": "Conference call",
"isBundle": false,
"isEnabled": false
},
{"id": "NET_SRV_MMS",
"name": "MMS service",
"description": "MMS service",
"isBundle": false,
"isEnabled": true
},
{"id": "NET_SRV_WIFI_CALL",
"name": "WiFi calling service",
"description": "WiFi calling service",
"isBundle": false,
"isEnabled": false
},
{"id": "APNS",
"name": "APN bundle",
"description": "List of APN available for this mobile service",
"isBundle": true,
"isEnabled": true,
"featureSpecRelationship": [{"relationshipType": "includes",
"featureId": "APN_INTERNET"
},
{"relationshipType": "includes",
"featureId": "APN_IPHONE_985"
},
{"relationshipType": "includes",
"featureId": "APN_IPHONE_986"
}
]
},
{"id": "APN_INTERNET",
"name": "O2 Internet APN",
"description": "5G service",
"isBundle": false,
"isEnabled": true
},
{"id": "APN_IPHONE_985",
"name": "O2 iPhone APN 985",
"description": "O2 iPhone APN 985",
"isBundle": false,
"isEnabled": false
},
{"id": "APN_IPHONE_986",
"name": "O2 iPhone APN 986",
"description": "O2 iPhone APN 986",
"isBundle": false,
"isEnabled": false
}
]
}

Service Instance

The Service entity represents an instance of a service. It is a read-only entity for Client applications, with write access provided only for internal system components

Expand documentation

Service state machine

Service status is governed by the properties described below:

hasStarted: Boolean state set to true when the service first becomes operational. Never set back to false
isServiceEnabled: Boolean state indicating if the service is enabled or not. May be used as a global state indicator.
True means the service is operating in a normal or degraded form
False means the service is not operating at all, including being stopped or suspended
operatingStatus: Reflects the state of the Service. Primary source for detailed service state indication, representing the service's operating status
state: Reflects the state of any ongoing activations on the network. Secondary service state property representing the service's lifecycle state

Service state machine (operatingStatus)

The state machine diagram for the Service operatingStatus property is represented in the diagram below.
This state machine represents the operational state of the service and does not change during normal in-life service management operations.

State machine for operatingStatus field

Service activation state machine (state)

The state machine diagram for the Service state property is represented in the diagram below.
This state machine represents the state of network reconfigurations on the service and as such varies during normal in-life service management operations.

State machine for state field

List or find Service objects

Only allows access to instances on the tenant defined on the access token.
Can search by top level properties (exact match) using query parameters:
- id
- serviceSpecification.id
- serviceSpecification.version
- category
- name
- isServiceEnabled
- hasStarted
- state
- operatingStatus
Can search nested fields using JSONPATH:
- relatedParty
- externalIdentifier
- serviceCharacteristic
- serviceRelationship

# E.g. list all serviceInstances with "category" == "Mobile Voice Service" supplied by Giacom
GET /service?category=Mobile Voice Service&filter=$.relatedParty[?(@.role=="supplier" && @.partyOrPartyRole.id=="GIACOM")]

Authorizations:

OAuth2OAuth2_UAT

query Parameters

limit	integer Requested number of resources to be provided in response. At the moment only `0` is supported as a valid limit to provide the total number of entities matching the criteria
id	string <uuid> Identifier of the entity
serviceSpecification.id	string <SCREAMING_SNAKE_CASE> Filter by service specification ID
serviceSpecification.version	integer <int64> Filter by service specification version
category	string (ServiceCategoryEnum) Enum: "Mobile Voice Service" "Mobile Data only Service" "Mobile Bolt On" Category of the entity. Supports IN queries by defining this parameter multiple times in the query with the different values
name	string Name of the entity. If defined, a full case-sensitive equals match is applied
isServiceEnabled	boolean If the services to search for are enabled or not
hasStarted	boolean If the services to search for have ever started or not
state	string (ServiceStateType) Enum: "feasibilityChecked" "designed" "reserved" "inactive" "active" "terminated" "suspended" States of the entity. Supports IN queries by defining this parameter multiple times in the query with the different values
operatingStatus	string (ServiceOperatingStatusType) Enum: "pending" "configured" "starting" "running" "degraded" "failed" "limited" "stopping" "stopped" "unknown" Operating status of the entity. Supports IN queries by defining this parameter multiple times in the query with the different values
filter	string Example: filter=$.relatedParty[?(@.role=="supplier" && @.partyOrPartyRole.id=="GIACOM")] Filter using JSONPath. Supports searching `relatedParty`, `externalIdentifier`, `serviceCharacteristic` and `serviceRelationship`

Responses

Response samples

Content type

application/json

[{"id": "string",
"isServiceEnabled": true,
"hasStarted": true,
"startDate": "2019-08-24T14:15:22Z",
"endDate": "2019-08-24T14:15:22Z",
"serviceOrderItem": [{"serviceOrderId": "string",
"itemAction": "add",
"itemId": "string"
}
],
"isBundle": true,
"feature": [{"isEnabled": true,
"id": "string",
"name": "string",
"description": "string"
}
],
"externalIdentifier": [{"owner": "MagentoCommerce",
"externalIdentifierType": "ProductOrder",
"id": "string"
}
],
"serviceCharacteristic": [{"id": "string",
"valueType": "string",
"name": "string",
"description": "string",
"value": [{"name": "string",
"description": "string",
"valueType": "string",
"value": "string"
}
]
}
],
"serviceRelationship": [{"relationshipType": "addon_for",
"service": {"id": "string"
}
}
],
"relatedParty": [{"role": "string",
"partyOrPartyRole": {"id": "string"
}
}
],
"state": "feasibilityChecked",
"operatingStatus": "pending",
"serviceSpecification": {"id": "string",
"version": "string"
},
"serviceDate": "2019-08-24T14:15:22Z",
"category": "Mobile Voice Service",
"name": "string",
"description": "string",
"version": 1,
"lastUpdate": "2019-08-24T14:15:22Z"
}
]

Retrieves a Service by ID

This operation retrieves a Service entity. Attribute selection enabled for all first level attributes.

Only allow access to instances on the tenant from the access token
The system always returns the last version of the ServiceInstance, since it doesn't store multiple versions. PATCH operations change the records and don't store historic versions

Authorizations:

OAuth2OAuth2_UAT

path Parameters

required

string

Identifier of the Resource

header Parameters

network_refresh

boolean

Set to true to trigger a network refresh of the service and obtain service instance freshly synchronised from the supplier's system

Responses

Response samples

Content type

application/json

Example

New service Giacom O2 Data

{"id": "6b9d14d4-cca9-416e-9af5-452b77e63a7b",
"lastUpdate": "2025-02-12T16:06:44.318Z",
"version": 1,
"name": "Mobile Voice Giacom-O2 DATA",
"description": "Mobile Voice Giacom-O2 DATA",
"category": "Mobile Data only Service",
"isBundle": false,
"operatingStatus": "pending",
"state": "inactive",
"isServiceEnabled": false,
"hasStarted": 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_DATA_SRV_GIACOM_O2",
"version": "1"
},
"serviceOrderItem": [{"serviceOrderId": "c159aa0f-83f8-4387-b04a-84822728e153",
"itemAction": "add",
"itemId": "1"
}
],
"externalIdentifier": [{"owner": "ACME Comms",
"externalIdentifierType": "ID",
"id": "1233"
}
],
"relatedParty": [{"role": "distributor",
"partyOrPartyRole": {"id": "ACME Comms"
}
},
{"role": "supplier",
"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": "TARIFF",
"name": "Tariff",
"description": "Giacom mobile tariff. Corresponds to the Giacom Mobile product",
"valueType": "string",
"value": [{"name": "AIOMB100 - All In One Mobile Broadband 100GB V24Q2",
"description": "AIOMB100 - All In One Mobile Broadband 100GB V24Q2",
"valueType": "string",
"value": "62228"
}
]
},
{"id": "SUBSCRIBER_NUMBER",
"name": "Subscriber number",
"description": "Subscriber number. Not required for new provisionings since Giacom will attribute one from its pool",
"valueType": "subscriber number",
"value": [{"name": "Subscriber number",
"description": "Subscriber number",
"valueType": "subscriber number",
"value": "07800987654"
}
]
},
{"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": "SIM_SERIAL",
"name": "SIM Serial",
"description": "SIM Serial",
"valueType": "iccid",
"value": [{"name": "SIM Serial",
"description": "SIM Serial",
"valueType": "iccid",
"value": "8944201122334455667"
}
]
}
],
"feature": [{"id": "BAR_ADMIN",
"name": "Admin bar",
"description": "Admin bar. When enabled, the service is suspended on the network",
"isEnabled": false
},
{"id": "BAR_PREMIUM",
"name": "Premium Calls",
"description": "Premium Calls",
"isEnabled": true
},
{"id": "BAR_ROAMING",
"name": "International Roaming",
"description": "International Roaming",
"isEnabled": true
},
{"id": "BAR_INWHENROAM",
"name": "Incoming Roaming",
"description": "Incoming Roaming",
"isEnabled": false
},
{"id": "BAR_OUTWHENROAM",
"name": "Outgoing Roaming",
"description": "Outgoing Roaming except to UK",
"isEnabled": false
},
{"id": "NET_CONF_CALL",
"name": "Conference call",
"description": "Conference call",
"isEnabled": true
},
{"id": "NET_SRV_MMS",
"name": "MMS service",
"description": "MMS service",
"isEnabled": true
},
{"id": "NET_SRV_WIFI_CALL",
"name": "WiFi calling service",
"description": "WiFi calling service",
"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
}
]
}

Service Order

The Service Order entity represents an order to create or update an instance of a service. It can be used to:

Create a new service
Perform in live service management
Cease a service

Expand documentation

ServiceOrder state machine

Service Order status is governed by its state property.

State machine for Service Order state

When an order is placed, the system tries to request the activation of the service.

If the order creation is rejected or fails, the Service Order is NOT created and the system responds with 400 Bad Request or a 500 Server error, depending on the fault
If the order is created but the activation request is rejected or fails, the system responds to the request with a 201 Accepted with the order in the rejected state and with an errorMessage field
If the activation request is successfully accepted, the system responds to the request with 201 Accepted with the order in the acknowledged state (or another, depending on the state machine) and, if applicable, with the created service's ID

After a successful response, all communications become asynchronous, triggered by Service Order status changed events
Clients which don't handle asynchronous notification may poll the GET Service Order by ID to assess the order's state

Handling `rejected` serviceOrders

If a serviceOrder is created but is not accepted and becomes rejected, the client still gets a 201 response with a serviceOrder object which reflects the rejection. It has:

Order ID
State rejected
An errorMessage field with details about the rejection

# Snippet of a rejected order indicating a downstream error
{
    "id": "72",
    "state": "rejected",
    "errorMessage": {
        "code": "ERR_000006",
        "reason": "ERR_000006: Rejected operation",
        "message": "Operation rejected with error {error from downstream service}",
        "status": "Error"
    }
    ...
}

Handling `failed` serviceOrders

If a serviceOrder starts but fails before it is complete, the order will transition to the failed state and will include an errorMessage field with details about the failure, similarly to when it is rejected

Client listener for entity ServiceOrderStateChangeEvent

Example of a client listener for receiving the notification ServiceOrderStateChangeEvent

Request Body schema: application/json
required

ServiceOrder stateChange Event payload

eventId	string The identifier of the notification.
eventTime	string <date-time> Time of the event occurrence.
eventType	string The type of the notification.
	object (EntityRef) Base schema for addressable entities
	object (EntityRef) Base schema for addressable entities
timeOccurred	string <date-time> The time the event occurred.
	object The event linked to the involved resource object

Responses

Request samples

Payload

Content type

application/json

{"eventId": "string",
"eventTime": "2019-08-24T14:15:22Z",
"eventType": "string",
"reportingSystem": {"id": "string"
},
"source": {"id": "string"
},
"timeOccurred": "2019-08-24T14:15:22Z",
"event": {"ServiceOrder": {"id": "string",
"cancellationDate": "2019-08-24T14:15:22Z",
"cancellationReason": "string",
"completionDate": "2019-08-24T14:15:22Z",
"externalReference": [{"externalReferenceType": "string",
"name": "string",
"id": "string"
}
],
"serviceOrderItem": [{"appointment": {"creationDate": "2019-08-24T14:15:22Z",
"externalId": "string",
"status": "initialized",
"validFor": {"endDateTime": "2019-08-24T14:15:22Z",
"startDateTime": "2019-08-24T14:15:22Z"
}
},
"serviceOrderItem": [{ }
],
"service": {"startDate": "2019-08-24T14:15:22Z",
"endDate": "2019-08-24T14:15:22Z",
"feature": [{"isEnabled": true,
"id": "string",
"name": "string",
"description": "string"
}
],
"externalIdentifier": [{"owner": "MagentoCommerce",
"externalIdentifierType": "ProductOrder",
"id": "string"
}
],
"serviceCharacteristic": [{"id": "string",
"valueType": "string",
"name": "string",
"description": "string",
"value": [{"name": null,
"description": null,
"valueType": null,
"value": null
}
]
}
],
"serviceRelationship": [{"relationshipType": "addon_for",
"service": {"id": "string"
}
}
],
"intent": {"characteristic": [{"id": "string",
"valueType": "string",
"name": "string",
"description": "string",
"value": [{ }
]
}
]
},
"relatedParty": [{"role": "string",
"partyOrPartyRole": {"id": "string"
}
}
],
"serviceSpecification": {"id": "string",
"version": "string"
},
"id": "string",
"category": "Mobile Voice Service",
"name": "string",
"description": "string"
},
"id": "string",
"action": "add",
"state": "acknowledged"
}
],
"priority": "string",
"relatedParty": [{"role": "string",
"partyOrPartyRole": {"id": "string"
}
}
],
"startDate": "2019-08-24T14:15:22Z",
"errorMessage": {"code": "ERR_000001",
"reason": "ERR_000001: Request body validation error at field level",
"message": "string",
"status": "Error"
},
"state": "acknowledged",
"version": 1,
"lastUpdate": "2019-08-24T14:15:22Z"
}
}
}

Response samples

Content type

application/json

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

List or find ServiceOrder objects

Authorizations:

OAuth2OAuth2_UAT

query Parameters

limit

integer

Requested number of resources to be provided in response

Responses

Response samples

Content type

application/json

[{"id": "string",
"cancellationDate": "2019-08-24T14:15:22Z",
"cancellationReason": "string",
"completionDate": "2019-08-24T14:15:22Z",
"externalReference": [{"externalReferenceType": "string",
"name": "string",
"id": "string"
}
],
"serviceOrderItem": [{"appointment": {"creationDate": "2019-08-24T14:15:22Z",
"externalId": "string",
"status": "initialized",
"validFor": {"endDateTime": "2019-08-24T14:15:22Z",
"startDateTime": "2019-08-24T14:15:22Z"
}
},
"serviceOrderItem": [{ }
],
"service": {"startDate": "2019-08-24T14:15:22Z",
"endDate": "2019-08-24T14:15:22Z",
"feature": [{"isEnabled": true,
"id": "string",
"name": "string",
"description": "string"
}
],
"externalIdentifier": [{"owner": "MagentoCommerce",
"externalIdentifierType": "ProductOrder",
"id": "string"
}
],
"serviceCharacteristic": [{"id": "string",
"valueType": "string",
"name": "string",
"description": "string",
"value": [{"name": "string",
"description": "string",
"valueType": "string",
"value": "string"
}
]
}
],
"serviceRelationship": [{"relationshipType": "addon_for",
"service": {"id": "string"
}
}
],
"intent": {"characteristic": [{"id": "string",
"valueType": "string",
"name": "string",
"description": "string",
"value": [{"name": null,
"description": null,
"valueType": null,
"value": null
}
]
}
]
},
"relatedParty": [{"role": "string",
"partyOrPartyRole": {"id": "string"
}
}
],
"serviceSpecification": {"id": "string",
"version": "string"
},
"id": "string",
"category": "Mobile Voice Service",
"name": "string",
"description": "string"
},
"id": "string",
"action": "add",
"state": "acknowledged"
}
],
"priority": "string",
"relatedParty": [{"role": "string",
"partyOrPartyRole": {"id": "string"
}
}
],
"startDate": "2019-08-24T14:15:22Z",
"errorMessage": {"code": "ERR_000001",
"reason": "ERR_000001: Request body validation error at field level",
"message": "string",
"status": "Error"
},
"state": "acknowledged",
"version": 1,
"lastUpdate": "2019-08-24T14:15:22Z"
}
]

Creates a ServiceOrder

This object defines one service order. It may be used to provision new services or managing existing services.

Authorizations:

OAuth2OAuth2_UAT

Request Body schema: application/json
required

The ServiceOrder to be created

	Array of objects (ExternalReference_FVO)
required	Array of objects (ServiceOrderItem_FVO) A list of service order items to be processed by this order
priority	string Can be used by consumers to prioritize orders in a Service Order Management system
	Array of objects (RelatedPartyRefOrPartyRoleRef) A list of parties which are involved in this order and the role they are playing

Responses

Request samples

Payload

Content type

application/json

Example

Port a number

{"externalReference": [{"id": "1002",
"externalReferenceType": "order_id",
"name": "ACME Comms"
}
],
"relatedParty": [{"role": "distributor",
"partyOrPartyRole": {"id": "ACME Comms"
}
}
],
"serviceOrderItem": [{"id": "1",
"action": "add",
"service": {"serviceSpecification": {"id": "MOBILE_VOICE_SRV_GIACOM_VF",
"version": "1"
},
"relatedParty": [{"role": "distributor",
"partyOrPartyRole": {"id": "ACME Comms"
}
}
],
"serviceCharacteristic": [{"id": "BILL_LIMIT",
"value": [{"value": "100"
}
]
},
{"id": "TARIFF",
"value": [{"value": "55638"
}
]
},
{"id": "SUBSCRIBER_NUMBER",
"value": [{"value": "07400123456"
}
]
},
{"id": "PAC",
"value": [{"value": "VUK123456"
}
]
},
{"id": "PORT_DATE",
"value": [{"value": "2025-02-12T16:06:44.318Z"
}
]
},
{"id": "SIM_TYPE",
"value": [{"value": "e_sim"
}
]
},
{"id": "SIM_SERIAL",
"value": [{"value": "8944112233445566778"
}
]
},
{"id": "ESIM_DELIVERY_EMAIL",
"value": [{"value": "[email protected]"
}
]
},
{"id": "ESIM_CONTACT_NAME",
"value": [{"value": "someone"
}
]
}
],
"feature": [{"id": "BAR_PREMIUM",
"isEnabled": true
},
{"id": "BAR_ROAMING",
"isEnabled": true
},
{"id": "NET_CONF_CALL",
"isEnabled": true
},
{"id": "NET_SRV_MMS",
"isEnabled": true
},
{"id": "NET_SRV_WIFI_CALL",
"isEnabled": true
},
{"id": "APN_INTERNET",
"isEnabled": true
},
{"id": "APN_TETHERING",
"isEnabled": true
}
]
}
}
]
}

Response samples

Content type

application/json

Example

Port a number

{"id": "2",
"lastUpdate": "2025-02-12T16:06:44.318Z",
"version": 1,
"startDate": "2025-02-12T16:06:44.318Z",
"state": "acknowledged",
"externalReference": [{"id": "1002",
"externalReferenceType": "order_id",
"name": "ACME Comms"
}
],
"relatedParty": [{"role": "distributor",
"partyOrPartyRole": {"id": "ACME Comms"
}
}
],
"serviceOrderItem": [{"id": "1",
"state": "acknowledged",
"action": "add",
"service": {"id": "2",
"serviceSpecification": {"id": "MOBILE_VOICE_SRV_GIACOM_VF",
"version": "1"
},
"relatedParty": [{"role": "distributor",
"partyOrPartyRole": {"id": "ACME Comms"
}
}
],
"serviceCharacteristic": [{"id": "BILL_LIMIT",
"name": "Bill limit",
"description": "Bill limit",
"valueType": "int",
"value": [{"name": "Bill limit",
"description": "Bill limit",
"valueType": "int",
"value": "100"
}
]
},
{"id": "TARIFF",
"name": "Tariff",
"description": "Giacom mobile tariff. Corresponds to the Giacom Mobile product",
"valueType": "string",
"value": [{"name": "Tariff",
"description": "Giacom mobile tariff. Corresponds to the Giacom Mobile product",
"valueType": "string",
"value": "55638"
}
]
},
{"id": "SUBSCRIBER_NUMBER",
"name": "Subscriber number",
"description": "Subscriber number. Not required for new provisionings since Giacom will attribute one from its pool",
"valueType": "subscriber number",
"value": [{"name": "Subscriber number",
"description": "Subscriber number. Not required for new provisionings since Giacom will attribute one from its pool",
"valueType": "subscriber number",
"value": "07400123456"
}
]
},
{"id": "PAC",
"name": "PAC",
"description": "PAC used for porting the number to this network. This characteristic is deleted after porting",
"valueType": "PAC",
"value": [{"name": "PAC",
"description": "PAC used for porting the number to this network. This characteristic is deleted after porting",
"valueType": "PAC",
"value": "VUK123456"
}
]
},
{"id": "PORT_DATE",
"name": "Port date",
"description": "Port date",
"valueType": "date-time",
"value": [{"name": "Port date",
"description": "Port date",
"valueType": "date-time",
"value": "2025-02-12T16:06:44.318Z"
}
]
},
{"id": "SIM_TYPE",
"name": "SIM type",
"description": "Type of SIM card",
"valueType": "string",
"value": [{"name": "SIM type",
"description": "Type of SIM card",
"valueType": "string",
"value": "e_sim"
}
]
},
{"id": "SIM_SERIAL",
"name": "SIM Serial",
"description": "SIM Serial",
"valueType": "iccid",
"value": [{"name": "SIM Serial",
"description": "SIM Serial",
"valueType": "iccid",
"value": "8944112233445566778"
}
]
},
{"id": "ESIM_DELIVERY_EMAIL",
"name": "eSIM Delivery Email",
"description": "eSIM Delivery Email",
"valueType": "email",
"value": [{"name": "eSIM Delivery Email",
"description": "eSIM Delivery Email",
"valueType": "email",
"value": "[email protected]"
}
]
},
{"id": "ESIM_CONTACT_NAME",
"name": "eSIM contact name",
"description": "eSIM delivery contact name",
"valueType": "string",
"value": [{"name": "eSIM contact name",
"description": "eSIM delivery contact name",
"valueType": "string",
"value": "someone"
}
]
}
],
"feature": [{"id": "BAR_PREMIUM",
"isEnabled": true
},
{"id": "BAR_ROAMING",
"isEnabled": true
},
{"id": "NET_CONF_CALL",
"isEnabled": true
},
{"id": "NET_SRV_MMS",
"isEnabled": true
},
{"id": "NET_SRV_WIFI_CALL",
"isEnabled": true
},
{"id": "APN_INTERNET",
"isEnabled": true
},
{"id": "APN_TETHERING",
"isEnabled": true
}
]
}
}
]
}

Retrieves a ServiceOrder by ID

This operation retrieves a ServiceOrder entity. Attribute selection enabled for all first level attributes.

Authorizations:

OAuth2OAuth2_UAT

path Parameters

required

string

Identifier of the Resource

Responses

Response samples

Content type

application/json

Example

Port a number

{"id": "2",
"lastUpdate": "2025-02-12T16:06:44.318Z",
"version": 1,
"startDate": "2025-02-12T16:06:44.318Z",
"state": "acknowledged",
"externalReference": [{"id": "1002",
"externalReferenceType": "order_id",
"name": "ACME Comms"
}
],
"relatedParty": [{"role": "distributor",
"partyOrPartyRole": {"id": "ACME Comms"
}
}
],
"serviceOrderItem": [{"id": "1",
"state": "acknowledged",
"action": "add",
"service": {"id": "2",
"serviceSpecification": {"id": "MOBILE_VOICE_SRV_GIACOM_VF",
"version": "1"
},
"relatedParty": [{"role": "distributor",
"partyOrPartyRole": {"id": "ACME Comms"
}
}
],
"serviceCharacteristic": [{"id": "BILL_LIMIT",
"name": "Bill limit",
"description": "Bill limit",
"valueType": "int",
"value": [{"name": "Bill limit",
"description": "Bill limit",
"valueType": "int",
"value": "100"
}
]
},
{"id": "TARIFF",
"name": "Tariff",
"description": "Giacom mobile tariff. Corresponds to the Giacom Mobile product",
"valueType": "string",
"value": [{"name": "Tariff",
"description": "Giacom mobile tariff. Corresponds to the Giacom Mobile product",
"valueType": "string",
"value": "55638"
}
]
},
{"id": "SUBSCRIBER_NUMBER",
"name": "Subscriber number",
"description": "Subscriber number. Not required for new provisionings since Giacom will attribute one from its pool",
"valueType": "subscriber number",
"value": [{"name": "Subscriber number",
"description": "Subscriber number. Not required for new provisionings since Giacom will attribute one from its pool",
"valueType": "subscriber number",
"value": "07400123456"
}
]
},
{"id": "PAC",
"name": "PAC",
"description": "PAC used for porting the number to this network. This characteristic is deleted after porting",
"valueType": "PAC",
"value": [{"name": "PAC",
"description": "PAC used for porting the number to this network. This characteristic is deleted after porting",
"valueType": "PAC",
"value": "VUK123456"
}
]
},
{"id": "PORT_DATE",
"name": "Port date",
"description": "Port date",
"valueType": "date-time",
"value": [{"name": "Port date",
"description": "Port date",
"valueType": "date-time",
"value": "2025-02-12T16:06:44.318Z"
}
]
},
{"id": "SIM_TYPE",
"name": "SIM type",
"description": "Type of SIM card",
"valueType": "string",
"value": [{"name": "SIM type",
"description": "Type of SIM card",
"valueType": "string",
"value": "e_sim"
}
]
},
{"id": "SIM_SERIAL",
"name": "SIM Serial",
"description": "SIM Serial",
"valueType": "iccid",
"value": [{"name": "SIM Serial",
"description": "SIM Serial",
"valueType": "iccid",
"value": "8944112233445566778"
}
]
},
{"id": "ESIM_DELIVERY_EMAIL",
"name": "eSIM Delivery Email",
"description": "eSIM Delivery Email",
"valueType": "email",
"value": [{"name": "eSIM Delivery Email",
"description": "eSIM Delivery Email",
"valueType": "email",
"value": "[email protected]"
}
]
},
{"id": "ESIM_CONTACT_NAME",
"name": "eSIM contact name",
"description": "eSIM delivery contact name",
"valueType": "string",
"value": [{"name": "eSIM contact name",
"description": "eSIM delivery contact name",
"valueType": "string",
"value": "someone"
}
]
}
],
"feature": [{"id": "BAR_PREMIUM",
"isEnabled": true
},
{"id": "BAR_ROAMING",
"isEnabled": true
},
{"id": "NET_CONF_CALL",
"isEnabled": true
},
{"id": "NET_SRV_MMS",
"isEnabled": true
},
{"id": "NET_SRV_WIFI_CALL",
"isEnabled": true
},
{"id": "APN_INTERNET",
"isEnabled": true
},
{"id": "APN_TETHERING",
"isEnabled": true
}
]
}
}
]
}

Geographic Address

TBD

Create a silver/bronze address

This operation allows creating a silver/bronze address

Request Body schema: application/json
required

The GeographicAddress to be created

city	string City that the address is in
locality	string An area of defined or undefined boundaries within a local authority or other legislatively defined area, usually rural or semi rural in nature. [ANZLIC-STREET], or a suburb, a bounded locality within a city, town or shire principally of urban character [ANZLICSTREET]
postcode	string descriptor for a postal delivery area, used to speed and simplify the delivery of mail (also know as zipcode)
stateOrProvince	string the State or Province that the address is in
streetName	string Name of the street or other street type
streetNr	string Number identifying a specific property on a public street. It may be combined with streetNrLast for ranged addresses
	GeographicSite_FVO (object) (GeographicSiteRefOrValue_FVO) The polymorphic attributes @type, @schemaLocation & @referredType are related to the GeographicSite entity and not the GeographicSiteRefOrValue class itself
	object (GeographicSubAddress_FVO) Representation of a GeographicSubAddress It is used for addressing within a property in an urban area (country properties are often defined differently). It may refer to a building, a building cluster, or a floor of a multistory building.
openreachALK	string Openreach (Access Level Key)

Responses

Request samples

Payload

Content type

application/json

{"city": "string",
"locality": "string",
"postcode": "string",
"stateOrProvince": "string",
"streetName": "string",
"streetNr": "string",
"geographicSite": {"relatedParty": [{"role": "string",
"partyOrPartyRole": { }
}
]
},
"geographicSubAddress": {"buildingName": "string",
"levelNumber": "string",
"levelType": "string"
},
"openreachALK": "string"
}

Response samples

Content type

application/json

{"city": "string",
"locality": "string",
"postcode": "string",
"stateOrProvince": "string",
"streetName": "string",
"streetNr": "string",
"geographicSite": {"code": "BTS",
"relatedParty": [{"role": "string",
"partyOrPartyRole": {"id": "string"
}
}
],
"externalIdentifier": [{"owner": "MagentoCommerce",
"externalIdentifierType": "ProductOrder",
"id": "string"
}
]
},
"geographicSubAddress": {"buildingName": "string",
"levelNumber": "string",
"levelType": "string"
},
"openreachALK": "string",
"openreachQualifier": "GOLD"
}

Address validation/matching

This operation allows validating an address, i.e. performing address matching

The response will include:

submittedGeographicAddress: The address object as defined by the client in the request
validGeographicAddress: An address object built from the Vendor with the exact address matching, if one was produced
alternateGeographicAddress: Alternative address objects matching the request

Request Body schema: application/json
required

The GeographicAddressValidation to be created

provideAlternative	boolean Indicator provided by the requester to specify if alternate addresses must be provided in case of partial or fail result.
	object (GeographicAddress_FVO) Structured textual way of describing how to find a Property in an urban area (country properties are often defined differently). Note : Address corresponds to SID UrbanPropertyAddress

Responses

Request samples

Payload

Content type

application/json

{"provideAlternative": true,
"submittedGeographicAddress": {"city": "string",
"locality": "string",
"postcode": "string",
"stateOrProvince": "string",
"streetName": "string",
"streetNr": "string",
"geographicSite": {"relatedParty": [{"role": "string",
"partyOrPartyRole": { }
}
]
},
"geographicSubAddress": {"buildingName": "string",
"levelNumber": "string",
"levelType": "string"
},
"openreachALK": "string"
}
}

Response samples

Content type

application/json

{"provideAlternative": true,
"state": "acknowledged",
"submittedGeographicAddress": {"city": "string",
"locality": "string",
"postcode": "string",
"stateOrProvince": "string",
"streetName": "string",
"streetNr": "string",
"geographicSite": {"code": "BTS",
"relatedParty": [{"role": "string",
"partyOrPartyRole": {"id": "string"
}
}
],
"externalIdentifier": [{"owner": "MagentoCommerce",
"externalIdentifierType": "ProductOrder",
"id": "string"
}
]
},
"geographicSubAddress": {"buildingName": "string",
"levelNumber": "string",
"levelType": "string"
},
"openreachALK": "string",
"openreachQualifier": "GOLD"
},
"validGeographicAddress": {"city": "string",
"locality": "string",
"postcode": "string",
"stateOrProvince": "string",
"streetName": "string",
"streetNr": "string",
"geographicSite": {"code": "BTS",
"relatedParty": [{"role": "string",
"partyOrPartyRole": {"id": "string"
}
}
],
"externalIdentifier": [{"owner": "MagentoCommerce",
"externalIdentifierType": "ProductOrder",
"id": "string"
}
]
},
"geographicSubAddress": {"buildingName": "string",
"levelNumber": "string",
"levelType": "string"
},
"openreachALK": "string",
"openreachQualifier": "GOLD"
},
"alternateGeographicAddress": [{"city": "string",
"locality": "string",
"postcode": "string",
"stateOrProvince": "string",
"streetName": "string",
"streetNr": "string",
"geographicSite": {"code": "BTS",
"relatedParty": [{"role": "string",
"partyOrPartyRole": {"id": "string"
}
}
],
"externalIdentifier": [{"owner": "MagentoCommerce",
"externalIdentifierType": "ProductOrder",
"id": "string"
}
]
},
"geographicSubAddress": {"buildingName": "string",
"levelNumber": "string",
"levelType": "string"
},
"openreachALK": "string",
"openreachQualifier": "GOLD"
}
]
}

Appointment

TBD

Book an appointment

This operation books an appointment

Request Body schema: application/json;charset=utf-8
required

The Appointment to be created

	object (RelatedSrvCfgValue) A reference to an entity, where the type of the entity is not known in advance. A related entity defines a entity described by reference or by value linked to a specific entity. The polymorphic attributes @type, @schemaLocation & @referredType are related to the Entity and not the RelatedEntityRefOrValue class itself
	object (TimePeriod) A period of time, either as a deadline (endDateTime only) a startDateTime only, or both

Responses

Request samples

Payload

Content type

application/json;charset=utf-8

{"relatedEntity": {"role": "appointment",
"entity": {"startDate": "2019-08-24T14:15:22Z",
"endDate": "2019-08-24T14:15:22Z",
"feature": [{"isEnabled": true,
"id": "string"
}
],
"externalIdentifier": [{"owner": "MagentoCommerce",
"externalIdentifierType": "ProductOrder",
"id": "string"
}
],
"serviceCharacteristic": [{"id": "string",
"value": [{"value": "string"
}
]
}
],
"serviceRelationship": [{"relationshipType": "addon_for",
"service": {"id": "string"
}
}
],
"intent": {"characteristic": [{"id": "string",
"value": [{"value": "string"
}
]
}
]
},
"relatedParty": [{"role": "string",
"partyOrPartyRole": {"id": "string"
}
}
],
"serviceSpecification": {"id": "string",
"version": "string"
},
"id": "string"
}
},
"validFor": {"endDateTime": "2019-08-24T14:15:22Z",
"startDateTime": "2019-08-24T14:15:22Z"
}
}

Response samples

Content type

application/json;charset=utf-8

{"creationDate": "2019-08-24T14:15:22Z",
"externalId": "string",
"relatedEntity": {"role": "appointment",
"entity": {"startDate": "2019-08-24T14:15:22Z",
"endDate": "2019-08-24T14:15:22Z",
"feature": [{"isEnabled": true,
"id": "string"
}
],
"externalIdentifier": [{"owner": "MagentoCommerce",
"externalIdentifierType": "ProductOrder",
"id": "string"
}
],
"serviceCharacteristic": [{"id": "string",
"value": [{"value": "string"
}
]
}
],
"serviceRelationship": [{"relationshipType": "addon_for",
"service": {"id": "string"
}
}
],
"intent": {"characteristic": [{"id": "string",
"value": [{"value": "string"
}
]
}
]
},
"relatedParty": [{"role": "string",
"partyOrPartyRole": {"id": "string"
}
}
],
"serviceSpecification": {"id": "string",
"version": "string"
},
"id": "string"
}
},
"status": "initialized",
"validFor": {"endDateTime": "2019-08-24T14:15:22Z",
"startDateTime": "2019-08-24T14:15:22Z"
}
}

Search appointment slots

This operation allows searching for available time slots to be used when booking Appointments

Request Body schema: application/json;charset=utf-8
required

The SearchTimeSlot to be created

	object (RelatedSrvCfgValue) A reference to an entity, where the type of the entity is not known in advance. A related entity defines a entity described by reference or by value linked to a specific entity. The polymorphic attributes @type, @schemaLocation & @referredType are related to the Entity and not the RelatedEntityRefOrValue class itself
	Array of objects (TimeSlot)

Responses

Request samples

Payload

Content type

application/json;charset=utf-8

{"relatedEntity": {"role": "appointment",
"entity": {"startDate": "2019-08-24T14:15:22Z",
"endDate": "2019-08-24T14:15:22Z",
"feature": [{"isEnabled": true,
"id": "string"
}
],
"externalIdentifier": [{"owner": "MagentoCommerce",
"externalIdentifierType": "ProductOrder",
"id": "string"
}
],
"serviceCharacteristic": [{"id": "string",
"value": [{"value": "string"
}
]
}
],
"serviceRelationship": [{"relationshipType": "addon_for",
"service": {"id": "string"
}
}
],
"intent": {"characteristic": [{"id": "string",
"value": [{"value": "string"
}
]
}
]
},
"relatedParty": [{"role": "string",
"partyOrPartyRole": {"id": "string"
}
}
],
"serviceSpecification": {"id": "string",
"version": "string"
},
"id": "string"
}
},
"requestedTimeSlot": [{"validFor": {"endDateTime": "2019-08-24T14:15:22Z",
"startDateTime": "2019-08-24T14:15:22Z"
}
}
]
}

Response samples

Content type

application/json;charset=utf-8

{"searchDate": "2019-08-24T14:15:22Z",
"availableTimeSlot": [{"validFor": {"endDateTime": "2019-08-24T14:15:22Z",
"startDateTime": "2019-08-24T14:15:22Z"
}
}
],
"relatedEntity": {"role": "appointment",
"entity": {"startDate": "2019-08-24T14:15:22Z",
"endDate": "2019-08-24T14:15:22Z",
"feature": [{"isEnabled": true,
"id": "string"
}
],
"externalIdentifier": [{"owner": "MagentoCommerce",
"externalIdentifierType": "ProductOrder",
"id": "string"
}
],
"serviceCharacteristic": [{"id": "string",
"value": [{"value": "string"
}
]
}
],
"serviceRelationship": [{"relationshipType": "addon_for",
"service": {"id": "string"
}
}
],
"intent": {"characteristic": [{"id": "string",
"value": [{"value": "string"
}
]
}
]
},
"relatedParty": [{"role": "string",
"partyOrPartyRole": {"id": "string"
}
}
],
"serviceSpecification": {"id": "string",
"version": "string"
},
"id": "string"
}
},
"requestedTimeSlot": [{"validFor": {"endDateTime": "2019-08-24T14:15:22Z",
"startDateTime": "2019-08-24T14:15:22Z"
}
}
],
"status": "inProgress"
}