Unlocking Seamless Integration with Operate API

DevRel | 11 Jun 2025
8 minutes reading time


What is Operate API?

Operate API, or TMF931 Open Gateway Onboarding and Ordering API as it is officially named, is a standardised REST API designed to streamline the onboarding, registration and management processes between Channel Partners and Mobile Operators. As its official name indicates, it is part of the GSMA Open Gateway initiative and aims at establishing uniform services APIs and integration mechanisms, allowing for various platforms and telecom service providers to ensure seamless interoperability across them.

Why use Operate API?

Operate API enables a headless approach for servicing aggregators through consistent, configurable APIs, ensuring seamless integration and interoperability across systems. It streamlines onboarding and ordering, reducing manual effort and errors. By simplifying partner and application integration, it supports service expansion and through programmatic provisioning and ordering, enhances security by minimising exposure. 

Some of the use cases for Operate API are enhancing collaboration between telecom operators and service providers, as well as facilitating integration between marketplace providers with telecom services.

How does Operate API work?

There are three key components and processes:

  • Application Owner registration: it is the entity that develops and publishes applications intending to use CAMARA APIs.

  • Application registration: it is the software making use of the CAMARA APIs.

  • API Product Order: it represents the purchase of rights to use one or more CAMARA APIs.

Using the different endpoints available, wholesale partners can register new Application Owners and Applications, create an API Product Order and get information on all previous items.

Before going through the steps, let's set up a scenario. A Channel Partner (for example, an aggregator), we will call them MaxAgg Co. are selling Vodafone's Number Verify API to a third party (the Application Owner), SecureApps Ltd. MaxAgg Co., had already been onboarded into Vodafone's Developer Marketplace Portal, have a set of credentials (generated by following the steps 3 and 4 listed here) enabling them to use the Operate API.

Note: For this guide, the application cURL (https://curl.se/) will be used for sharing sample commands, but the actual implementation of these API calls can be done with whichever programming language the reader prefers.

Authentication

Once the Channel Partner and the Application Owner have established their commercial relationship, MaxAgg Co. will need to authenticate with Vodafone's platform to proceed with the requests. This can be done via a command like the one below:

curl -L 'https://api-sandbox.vf-dmp.engineering.vodafone.com/oauth2/v1/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Authorization: Basic {base64 encoded string of clientID:clientSecret}' \
-d 'grant_type=client_credentials'

This will return an access token which can then be used to perform the other calls, before it expires. Once it does, a new one needs to be requested through the same call above.

Application Owner

Once authenticated in the platform, MaxAgg Co. will need to create an entry on Vodafone systems for SecureApps Ltd. which are the Application Owner. The minimum required information for the request is listed below:

  • @type: specifies the type of the resource. In this case, "ApplicationOwner".

  • name: a unique name identifying the ApplicationOwner entity. This is typically the official or registered name of the organisation.

  • description: a brief description of the Application Owner's role or purpose wihthin the Open Gateway context.

  • engagedParty: represents a group of people identified by shared interests or purpose. Examples include business, department and enterprise. It contains the following fields:

    • @type: indicates the type of the engaged party. For organisations, it should be "ApplicationOwnerOrganization".

    • contactMedium: a list containing the contact mediums that could be used to contact the party. Can be instanciated as EmailContactMedium, FaxContactMedium, GeopgraphicAddres, ContactMedium, PhoneContactMedium, SocialContactMedium or WebFormContactMedium.

      • @type: type of the contact, as described above.

      • url or emailAddress: depending on the contact type, the actual contact detail.

    • name: the full legal name of the organisation.

    • organizationIdentification: represents the registration of information used as proof of identity by an organisation.

      • @type: type of identification (e.g., "OrganizationIdentification").

      • identificationId: the official reesgistration number or ID issued by a government or authority.

    • registeredGeographicAddress: the official address of the organisation, including:

      • @type: should be "LightGeographicAddress".

      • city: the city where the organisation is located.

      • countryCode: ISO3166-1 Alpha-2 country code (e.g., "GB"), with:

        • @type: "ISO31661Alpha2StandardIdentifier".

        • value: the actual country code.

    • taxNumber: tax number of the Organisation in the country.

    • tradingName: the commercial or brand name that the Organisation trades under.

With those in hand, the following command can be executed:

curl -L 'https://api-sandbox.vf-dmp.engineering.vodafone.com/tmf-api/openGatewayOperateAPIOnboardingAndOrdering/v5/applicationOwner?fields=id' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {accessToken}' \
--data-raw '{
  "@type": "ApplicationOwner",
  "name": "SecureApps Ltd",
  "description": "SecureApps Ltd is a leading provider of secure financial applications, focusing on a greate end user experience.",
  "engagedParty": {
    "@type": "ApplicationOwnerOrganization",
    "contactMedium": [
      {
        "@type": "EmailContactMedium",
        "emailAddress": "jane.oconnor@secureapps.com"
      }
    ],
    "name": "SecureApps Ltd",
    "organizationIdentification": [
      {
        "@type": "OrganizationIdentification",
        "identificationId": "REG-987654"
      }
    ],
    "registeredGeographicAddress": {
      "@type": "LightGeographicAddress",
      "city": "London",
      "countryCode": {
        "@type": "ISO31661Alpha2StandardIdentifier",
        "value": "GB"
      }
    },
    "taxNumber": "123456789",
    "tradingName": "SecApps"
  }
}'

The request above was made with the minimum required fields. Details on a full request can be found here.

If successful, the response should return an HTTP code of 201 and look like the below. The fields returned on the response are controlled by the parameters passed on the "location" URL ("id" for this example):

{
  "@type": "ApplicationOwner",
  "id": "104cf995-d965-4dcf-abb6-4dd230cc779c"
}

Note that if there is an attempt to register a second Application Owner with the same tradingName, taxNumber and country, the platform will return an error as it will be a duplicate entry.

Application

Once the Application Owner has been created, it is time to create the Application in the system, which is linked to MaxAgg Co. via the credentials used and to SecureApps Ltd. via the id generated in the previous call.

The minimum required information for this request is:

  • @type: specifies the type of the resource. For Application, this should be "Application".

  • name: the internal name of the application. This is for identification within the system only.

  • commercialName: the public-facing name of the application, as seen by end users.

  • description: a short summary describing the purpose or functionality of the application.

  • applicationOwner: a reference to the ApplicationOwner entity that owns this application. See preivous section for reference on how it is created.

    • @type: type of the reference ApplicationOwner, typically "PartyRoleRef".

    • id: the unique identifier of the ApplicationOwner entity, returned at the moment of creation.

It is worth mentioning that if the Channel Partner decides to add the privacyRights option to their request, it must be either an email address or a web link. A request containing any other format for this field will be refused.

Here is what a request with the minimum required fields would look like:

curl -L 'https://api-sandbox.vf-dmp.engineering.vodafone.com/tmf-api/openGatewayOperateAPIOnboardingAndOrdering/v5/application?fields=id%2C%20description' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {accessToken}' \
--data-raw '{
  "@type": "Application",
  "name": "VerySafeApp",
  "commercialName": "VerySafe",
  "description": "The safest of financial apps",
  "applicationOwner": {
    "@type": "PartyRoleRef",
    "id": "{{APPLICATION_OWNER_ID}}"
  }
}'

Details on what a full request is can be found here.

A successful request will return an HTTP code 201 response, containing a body like the one below:

{
  "@type": "Application",
  "id": "104cf995-d965-4dcf-abb6-4dd230cc779c",
  "description": "The safest of financial apps"
}

Again, the contents of the response can be controlled by the parameters sent with the request.

API Product Order

The next step is for MaxAgg Co. to inform Vodafone which APIs the app by SecureApps Ltd. will subscribe to. This can be done via the API Product Order endpoint, which has the following minimum requirements:

  • productOrderItem: a list of one or more items that make up the product order. Each item represents a specific action (add, modify, delete) on a product.
    • @type: specifies the tupe of the order item. Must be one of ApiProductOrderItemAdd, ApiProductOrderItemModify or ApiProductOrderItemDelete.
    • id: a unique identifier for the order item, typically a sequence number like "1", "2", etc.
    • product: a reference to the product being ordered. This includes the product ID and type.
    • productOffering: a reference to the product offering being ordered. Includes the offering ID and name.
    • productAction: describes the action to be performed on the product (eg., add), and includes any required parameters.
    • approvedProductOfferingTermOrCondition: the URL to the document containing a list of terms and conditions that have been approved for the product offering.

The request containing all of the minimum required fields will then look like the one below:

curl -L 'https://api-sandbox.vf-dmp.engineering.vodafone.com/tmf-api/openGatewayOperateAPIOnboardingAndOrdering/v5/apiProductOrder?fields=id' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {accessToken}' \
--data-raw '{
  "@type": "ApiProductOrder",
  "productOrderItem": [
    {
      "@type": "ApiProductOrderItemAdd",
      "approvedProductOfferingTermOrCondition": [
        {
          "@type": "ProductOfferingTermOrCondition",
          "name": "Device Location Verification Terms",
          "userConsentScreenshot": {
            "@type": "SimpleAttachment",
            "content": "...",
            "mimeType": "application/pdf"
          },
          "productOfferingTermOrConditionSpecRef": {
            "@type": "ProductOfferingTermOrConditionSpecRef",
            "id": "55d316f1-4e0a-4e69-9d73-181c20a61165",
            "version": "1.1"
          }
        }
      ],
      "id": "1",
      "productAction": {
        "@type": "ApiProductActionAdd",
        "purpose": "dpv:FraudPreventionAndDetection",
        "countryCode": [
          {
            "@type": "ISO31661Alpha2StandardIdentifier",
            "value": "ES"
          }
        ],
        "targetApplication": {
          "@type": "ApplicationRef",
          "id": "{{APPLICATION_ID}}"
        }
      },
      "productOffering": {
        "@type": "ProductOfferingRef",
        "id": "fa013ed0-36a0-4d42-8046-8801ab870604",
        "name": "vodafone_device_location_verification"
      }
    }
  ],
  "channelPartner": {
    "@type": "PartyRoleRef",
    "id": "{{APPLICATION_OWNER_ID}}"
  }
}'

Details on the full request can be found here.

A successful call results in an HTTP 201 response like the one below, where the information presented is defined by the parameters passed along the URL:

{
  "@type": "ApiProductOrder",
  "id": "104cf995-d965-4dcf-abb6-4dd230cc779c"
}

To ensure that Channel Partners are aware of the status of their ApplicationOwner, Application or API Product Order requests, HTTP notifications can be configured to communicate whenever one of the following happens:

  • ApplicationOwner and Application creation or approval.
  • API Product Order creation and state changes.

This currently requires the Channel Partners to provide the necessary configuration (URL or webhooks) to set them up.

Enhance Your Telecom Integration with Operate API

This article introduced the Operate API and presented some of its features, including examples of requests that would be used in a real-word scenario. It also showcased the following features:

  • A robust and streamlined solution for integrations and management of applications.
  • Efficient handling of onboarding, registration and ordering processes, by using a standardised REST API.
  • Seamless interoperability across different platforms and service providers.
  • Support for service growth and expansion of partnerships and applications.
  • Comprehensive set of endpoints and processes.

If you are interested in integrating your application workflow with Vodafone telecom services, don't hesitate to reach out through the form here.

Ready to start building?

Start now

Got Questions?

See our FAQ Drop us a line
X Facebook

Vodafone Developer Portal

Discover, try, and purchase our APIs to start building your own apps