Introduction

Network APIs are intended for companies, not individuals, hobbyists, or independent developers. Therefore, before making Network API calls, you must submit your company profile for approval by the Communication Service Providers (CSPs) to gain access. To streamline this process, Vonage handles registration with various CSPs behind the scenes for all supported Network APIs in any country where Vonage services are available.

The approval process consists of two steps:

1. Create a business profile.

2. Create an application profile.

Both steps can be completed using the Vonage Network Registry, either from the dashboard or via API.

Prerequisites

This tutorial assumes that you already have a Vonage account. If you don’t have one, you can create one here. 

Network Registry Dashboard

The Network Registry can be accessed through the user's dashboard. Log in to your Vonage account, and under your avatar image on the right side of the portal, click “My dashboard.” Use the left navigation menu to locate the Build & Manage section. Then click on Registry -> Network Registry.

Create a Business Profile

The business profile includes legal information about your company. Click “Add business profile” and complete the form by providing the following information about your organization:

• Country - where your end users may access your applications.

• Role - your role in your organization.

• Business Name - the name of the legal entity that owns the applications that will be using Vonage Network APIs.

• Organization type - select the most appropriate type from the dropdown list.

• Business registered address/country - the address and country where your organization is registered.

• Business Tax number - your tax reference used by Vonage and its CSPs to validate your organization.

• Privacy policy URL—Vonage and its CSPs require that anyone using Network APIs have a privacy policy that is publicly available on the Internet. Provide the URL for your policy.

• Privacy Policy Manager’s email address - include an email address that can be used for any questions about your privacy policy.

• Data Protection Officer’s (DPO) email address - this is only if you are required by law to have one.

New Business Profile

After submitting, you’ll see a summary of your business profile. This summary helps you keep track of your registration status. You will receive email notifications when the status of your registration changes.

CSP responses to approval requests are asynchronous and may be received by the Vonage Network Registry at different times.

Create an Application Profile

Application profiles are used to describe a specific use case, including which Network APIs are required and the purpose they will be used for. They will be shared with CSPs in the countries included in the associated business profile.

Go to the Network Registry entry from the left navigation menu, click on the business profile name, and then select “Add application profile.” A form will appear where you’ll need to provide more information about the kind of application you are building:

• Profile name - Give your application profile a name for easy identification.

• Category - Select an application category from the drop-down list.

• Infrastructure Locations - Specify country locations where you may process personal data related to the use of the requested Network APIs

• Network APIs - Select the Network APIs that you may want to use.

• Purpose - For each Network API selected, confirm the purpose from the drop-down list, e.g., “Fraud Prevention and Detection”.

• Use case description: Describe your application from a consumer's point of view.

New Application Profile

After submission, you will receive a summary of your application profile request. Email notifications will be sent to you whenever there is a change in your application status.

Monitoring my submission

You can monitor the status of your application profile approval process. Go to the Network Registry entry in the left navigation menu and click on your business profile. The business profile overview page will appear. Once there, uncollapse the application profiles entry at the bottom of the page. A list of CSPs from the countries you selected during the creation of your business profile, along with their approval statuses, will appear. 

Network APIs Submission Status

Network Registry API

The Network Registry API allows developers to submit business and application profiles programmatically. This is particularly useful when different teams within your organization use the Network APIs, allowing each team to create and use distinct application profiles as needed through internal processes.

Authentication

All Network Registry API calls require authentication to be completed. Authentication is based on the API key and secret, which can be found on the overview page of your dashboard and will be sent within the URL. 

API Key Secret

Warning: Your API credentials are secret and for personal use only. Do not share them with anyone.

Business Profiles

The/business-profile endpoint is used for all business profile operations: create, retrieve, delete, etc.

To create a new business profile, we must send a POST request. The body of the call will contain the same information requested by the Network Registry dashboard (role, country, tax number, etc.).

The following example uses cURL to create a new business profile called “My business profile”, requesting access to operators in Spain and Germany:

curl -X POST "http://api-eu.vonage.com/v1/network-registry/business-profiles" \
-H "Content-Type: application/json" \
-u ${API_Key}:${API_Password} \
-d '{
  "contact_role":"developer",
  "name":"my business profile",
  "organisation_type":"forProfitOrganisation",
  "country":"ES",
  "tax_number":"1234567890",
  "privacy_policy_url":"https://1LThiQzd.com",
  "privacy_policy_manager_email":"manager@test.com",
  "dpo_email":"dpo@test.com",
  "dpo_required":true,
  "countries":[
    "ES",
    "DE"
  ],
  "business_information":{
    "address_street_1":"address 1",
    "address_street_2":"address 2",
    "city":"Madrid",
    "province":"Madrid",
    "postal_code":"28020",
    "country":"ES"
  },
  "email_notifications_enabled":true,
  "terms_and_conditions_accepted":true
}'

We could send a GET request to retrieve a list of business profiles to monitor their status:

curl "http://api-eu.vonage.com/v1/network-registry/business-profiles" -u ${API_Key}:${API_Password}

It is also possible to retrieve the business profile information for a given CSP by sending a GET request to the /business-profile/{id}/csps endpoint:

curl "http://api-eu.vonage.com/v1/network-registry/business-profiles/0934561-99ce-123/csps" -u ${API_Key}:${API_Password}

In case we want to modify a business profile, we could send a PUT request to the /change-request

curl -X PUT "http://api-eu.vonage.com/v1/network-registry/business-profiles/0934561-99ce-123/change-request" \
-H "Content-Type: application/json" \
-u ${API_Key}:${API_Password} \
-d '{
   "countries": [
      "ES"
   ],
   "contact_role": "A Business Profile",
   "name": "A Business Profile",
   "trading_name": "A Business Profile Ltd.",
   "organisation_type": "For-Profit Organisation",
   "tax_number": "98284687G",
   "privacy_policy_url": "https://www.businessinc.com/privacy_policy",
   "privacy_policy_manager_email": "privacy.manager@business.com",
   "dpo_email": "dpo@business.com",
   "dpo_required": true,
   "terms_and_conditions_accepted": true,
   "business_information": {
      "address_street_1": "Main Street 5",
      "address_street_2": "Extra long address",
      "postal_code": "W1 5DU",
      "country": "UK",
      "city": "London",
      "province": "City of London"
   },
   "email_notifications_enabled": true
}'

Finally, we could delete an existing business profile by running this command:

curl -X DELETE "http://api-eu.vonage.com/v1/network-registry/business-profiles/0934561-99ce-123

Application Profile

Similar to business profiles, we can use the /application-profiles endpoint to perform all operations related to application profiles.

The following example sends a POST request to create a new application profile:

curl -X POST "http://api-eu.vonage.com/v1/network-registry/application-profiles" \
-H "Content-Type: application/json" \
-u ${API_Key}:${API_Password} \
-d '{
   "business_profile_id": "string",
   "name": "Network Application Profile",
   "description": "This is an example use case for Fraud Prevention",
   "category_id": "finance",
   "network_apis": [
      {
         "network_api_id": "sim-swap",
         "purpose_ids": [
            "FraudPreventionAndDetection"
         ]
      }
   ],
   "terms_and_conditions_accepted": true,
   "infrastructure_locations": [
      "ES"
}'

We could retrieve a list of application profiles by sending a GET request. We could filter the result by sending query parameters like status (pending, accepted, rejected, etc.) or business_profile_id, to get application profiles from a specific business profile.

curl "http://api-eu.vonage.com/v1/network-registry/application-profiles" -u ${API_Key}:${API_Password}

The API Reference contains a detailed description of the rest of the operations.

More Operations

Beyond the operations to manage business and application profiles, the Network Registry API provides useful endpoints for operating with other resources, such as countries, supported network APIs, or organization types.

To get a list of supported countries, we could send a GET request like this example:

curl "http://api-eu.vonage.com/v1/network-registry/catalogue/countries" -u ${API_Key}:${API_Password}

Similarly, by sending a GET request to the /network-api endpoint, we could retrieve a list of supported Network APIs:

curl "http://api-eu.vonage.com/v1/network-registry/catalogue/network-apis" -u ${API_Key}:${API_Password}

The catalogue section of the API Reference contains a list of resources that can be accessed via /catalogue endpoint.

What’s next?

Once your submission is approved by at least one of its CSPs, you can link it to one or more Vonage applications to start using the Network APIs. The Vonage application contains the credentials needed to make API calls.

Get in Touch

We’d love to hear from you! Join the Vonage Community Slack channel to share your experiences using the Network Registry. You can also follow the Vonage Developer Experience team on X, formerly known as Twitter.