Working with Vonage APIs

Welcome to the Vonage API platform! Vonage provides a suite of APIs that enable you to communicate with your customers using your preferred channels.

This site provides comprehensive documentation for all of our APIs and you’ll find everything you need to know about working with a particular API in the corresponding section.

However, there are some fundamental concepts that you need to understand and tools that might help you that apply across all our APIs:

Signing up for an account

To work with our APIs, you will need to sign up for an account. This will give you an API key and secret that you can use to access our APIs.

Accessing the Developer Dashboard

Once you have an account, you can log into the Developer Dashboard. The Developer Dashboard is a GUI-based approach to managing your account, where you can:

  • View your API key and secret. You will need these to authenticate your requests to our APIs
  • Manage your account balance. Access to our APIs is charged on a per-request basis. We’ll give you some free credit when you first open your account and you can top up when you run low.
  • Rent virtual numbers. You can use virtual numbers provided by Vonage to send and receive calls and messages. See rent a virtual number.
  • Manage applications. Some of our APIs (such as Voice and Messages) require you to create an Application, which acts as a container for security and configuration information. You can create and manage these applications in the Developer Dashboard.
  • Manage your account. You can perform other administration tasks here.

Using the Vonage CLI

You can optionally perform many of the Dashboard tasks from the command line, using the Vonage CLI. This is often quicker and also allows you to script these operations.

The Vonage CLI is written with oclif and can be installed using the Node Package Manager (npm). The README in the Vonage CLI GitHub repo shows you how to install and work with the Vonage CLI.

Authentication

When using the Vonage APIs your requests need to be authenticated. Typically this is done using Basic Authentication or JWTs. You can generate a suitable JWT using the Vonage CLI, or our online tool. While Basic Authentication will work, it will not allow you to receive webhooks - these can only be enabled by using JWTs.

If using Silent Authentication with Verify, it must be the first channel in the workflows array.

Experimenting with our APIs

Ultimately, you’re going to want to build an app in your chosen programming language. But to start with, you might want to make some sample requests to our APIs to check that you have provided the correct parameters and that you are getting back the responses you want.

If you are familiar with the command-line tool Curl, you will find Curl snippets for each of our APIs that you can copy, paste and modify.

Postman

Various GUI tools exist that are easier to use than Curl. A popular one is Postman. Read our guide on using Postman to work with our APIs. Vonage also provides a set of Postman collections, which provides a way to start using the APIs immediately.

OpenAPI

Each of our APIs has its own OpenAPI specification. You can read more about OpenAPI in our documentation. Our specifications conform to OpenAPI specification version 3, also known as OAS3.

Using a Server SDK

When you are ready to start building your app, you’ll want to use one of our Server SDKs instead of coding each request by hand. You can find links to all of our SDKs on the Tools page.

Working with Webhooks

Once you have learned how to make requests to our APIs to place calls, send messages and so on you will want to learn how to receive inbound communications on your virtual number.

When our APIs want to notify your app about something - whether that is an inbound call or message or a status update - they require your app to expose a URL endpoint that our platform can make a request to. These must be accessible over the public Internet.

These endpoints are called Webhooks. Find out more about webhooks. Once you have created your web hook, you must tell our API platform to use it. The process for doing this depends on which API you are using and full instructions can be found in the documentation for that API.

Making these webhooks publicly-accessible during development can be tricky, so we recommend a tool called Ngrok.

Visit our guide on testing with Ngrok to learn how to use it.

Number Format

Within the Vonage APIs, all phone numbers are in E.164 format. This means that numbers:

  • Omit both a leading + and the international access code such as 00 or 001.
  • Contain no special characters, such as space, () or -

For example, a US number would have the format 14155550101. A UK number would have the format 447700900123.

If you are unsure how to format the number, the Number Insight API can be used to find correct information about a number.

See also Number format in the Voice API documentation.

Concepts

There are a number of shared concepts between the Vonage APIs: the use of JSON Web Tokens (JWTs), signed requests, and webhooks. The guides below explain in detail how to use these elements.

  • Applications - Security and configuration information you need to connect to Vonage endpoints.
  • Authentication – API keys and JSON Web Tokens (JWTs).
  • Signing messages – how to cryptographically sign messages and verify message signatures.
  • Webhooks – Vonage's API can send data back to your web server via a webhook.
  • OpenAPI – All Vonage APIs have OpenAPI descriptions that you can take advantage of in your own development process.
  • Glossary – A glossary of common terms used throughout the Vonage platform.

What to do next

This guide introduced you to some of the fundamental concepts and tools that you should know about when working with our APIs.

Once you understand these fundamental concepts and have installed the tools you intend to use, you are ready to start building! View the documentation for your chosen API to get started.

If you encounter any difficulties, check out our Community Slack, or take a look at our knowledge base and reach out for assistance if necessary at our support site.