IP Provisioning API Overview

The IP Provisioning API uses standard Twilio Sendgrid API Keys for authentication and authorization. Once onboarded as a reseller, any API keys you create will have access to the IP Provisioning API. Twilio SendGrid recommends creating an Admin API key to manage your IP Provisioning API account. An Admin key is also known as a Full Access key in the Twilio SendGrid user interface.

If you are new to Twilio SendGrid API keys, see the API key docs to create an API key. The Twilio SendGrid v3 APIs expect the key to be passed as a Bearer Token in an Authorization header. See How to Use the SendGrid v3 API for instructions.

The following documentation refers to the owner of an IP Provisioning API account as the reseller. The accounts a reseller owns and manages through this API are referred to as customer accounts. The operations available are provided to you, the reseller, in order to manage your customer accounts' IPs.

The Twilio SendGrid IP Provisioning API allows you to manage IP addresses for your customer accounts. This page provides an overview of the most common operations a reseller will perform:

• Adding IPs to a customer account.
• Listing customer account IPs.
• Removing IPs from a customer account.

For information about the IP Provisioning API operations available, see the API reference documentation for each operation.

Adding IP addresses to a customer account is done with a single POST operation that provisions new dedicated IP addresses and assigns them to the specified customer account. The Add IPs operation requires a JSON request body containing the number of IPs to provision and the region where they should be provisioned.

The request body contains two required fields:

• count: The number of IP addresses to provision (minimum 1, maximum 10 per request)
• region: The geographic region where the IPs should be provisioned (us for United States or eu for Europe)

All IP addresses in a single request must be from the same region. If you need IPs in multiple regions, you must make separate API calls for each region.

The following JSON block shows a request to add 2 IP addresses in the US region:

1
{
2
  "count": 2,
3
  "region": "us"
4
}

The response returns a 201 Created status code along with the provisioned IP addresses and their region:

1
{
2
  "ips": [
3
    "192.168.1.1",
4
    "192.168.1.2"
5
  ],
6
  "region": "us"
7
}

The returned IP addresses are immediately available for use with the customer account.

You can retrieve a paginated list of all IP addresses associated with a customer account using the GET operation. The IPs are returned ordered by most recently added.

The endpoint returns 10 results per request by default. You can specify up to 5,000 results per request using the limit query parameter. Use the offset parameter (set to the last IP address from the previous response) to paginate through results.

The response includes an array of IP objects, each containing the IP address and its region:

1
{
2
  "result": [
3
    {
4
      "ip": "174.0.2.1",
5
      "region": "us"
6
    },
7
    {
8
      "ip": "192.0.0.1",
9
      "region": "eu"
10
    }
11
  ],
12
  "pages": {
13
    "last": "192.0.0.1"
14
  }
15
}

Removing IP addresses from a customer account is done with a single DELETE operation that requires a JSON request body containing an array of specific IP addresses to remove.

The following JSON block shows a request to remove 2 specific IP addresses:

1
{
2
  "ips": [
3
    "174.0.0.3",
4
    "192.0.0.1"
5
  ]
6
}

You can remove between 1 and 10 IP addresses per request. Each IP address must be specified in standard IPv4 dotted-decimal notation.

The response returns a 204 No Content status code, indicating that the IP addresses have been successfully removed from the customer account.