---
"@context": https://schema.org
"@type": TechArticle
"@id": https://www.twilio.com/docs/sendgrid/api-reference/account-provisioning-api#article
headline: Account Provisioning API
description: The Twilio SendGrid Account Provisioning API provides a platform for Twilio SendGrid resellers to manage their customer accounts. This API is for companies that have a formal reseller partnership with Twilio SendGrid.
url: https://www.twilio.com/docs/sendgrid/api-reference/account-provisioning-api
inLanguage: en
dateModified: 2026-10-08T16:11:44.000Z
author:
  "@type": Organization
  name: Twilio Developer Education Team
publisher:
  "@type": Organization
  name: Twilio
---

# Account Provisioning API

To manage their customer accounts, Twilio SendGrid provides the Account Provisioning API for resellers. This API covers companies that have a formal reseller partnership with Twilio SendGrid.

You can access Twilio SendGrid sub-account functionality without becoming a reseller. If you require sub-account functionality, see the Twilio SendGrid [Subusers][subusers] feature available in the [Pro and Premier plans][pricing].

## Authentication and authorization

The Account Provisioning API uses the standard Twilio SendGrid [API Keys][tsc-api-keys] for authentication and authorization. Once onboarded as a reseller, any API keys you create can access the Account Provisioning API. To manage your Account Provisioning API account, create an [Admin API key][admin-api-key], or a [*Full Access* key][create-api-key], in the [Twilio SendGrid console][tsc-api-keys].

* To learn about Twilio SendGrid API keys, see [create an API key][create-api-key]. The Twilio SendGrid v3 APIs expect your app to pass the key as a `Bearer Token` in an `Authorization` header.
* To apply your API key, see [How to use the Twilio SendGrid v3 API][use-v3-api].

## Terminology

* *Reseller*: The individual that owns an Account Provisioning API account.
* *Customer account*: An account that a reseller owns and manages through the API.
* *Offering*: An email package with a set of features.

## Common operations

To create and manage your customers' accounts, use the Account Provisioning API. The most common operations that a reseller performs include:

* Creating a customer account.
* Understanding account state.
* Managing customer account offerings.
* Managing customer IP addresses.
* Deactivating and removing account resources.
* Authenticating customers with *single sign-on* (SSO).

To learn more about the other Account Provisioning API operations, see the API reference documentation for each operation.

### Create a customer account

The Create Account operation requires a JSON request body containing a `profile` object and an array of `offerings` objects. To create a customer account, make a [single `POST` operation][create-account]. This request returns the unique Twilio SendGrid account ID for the created account.

| Component   | Type   | Necessity | Contents                                                                                                                                                                              | API reference         |
| ----------- | ------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
| `profile`   | object | Optional  | Identity data for one customer with their `first_name`, `last_name`, and `email`. If the fields aren't provided, Twilio prompts the customer to enter this data at their first login. | [API][create-account] |
| `offerings` | array  | Required  | Offering objects with its `name`, `type`, and `quantity` that define the features in the customer's account. These offerings depend on your agreement with Twilio SendGrid.           | [API][list-offerings] |

To retrieve a list of all the offerings that you can assign to a customer account, use the [List Offerings endpoint][list-offerings]. Available offerings change infrequently. Rather than call the endpoint before each account creation or update, cache the List Offerings response. An account may start on any email offering at any price point. You can upgrade or downgrade an account immediately after account provisioning.

```json {title="Account creation request payload", description="To create a customer account, write a JSON block that resembles the following:"}
{
  "profile": {
      "first_name": "Jane",
      "last_name": "Doe",
      "company_name": "Cake or Pie Bakery",
      "company_website": "www.example.com",
      "email": "jdoe@example.com",
      "phone": "+15555555555",
      "timezone": "Asia/Tokyo"
  },
  "offerings": [
      {
          "name": "milne.ei.pro-100k.v1",
          "type": "package",
          "quantity": 1
      }
    ]
}
```

```json {title="Account creation response", description="This request responds with a Twilio SendGrid account ID. All subsequent calls to the Account Provisioning API use this account ID. Record it in your database for future use."}
{
  "account_id": "sg2a2bcd3ef4ab5c67d8efab91c01de2fa"
}
```

### Create a customer test account

To create a new customer test account with Account Provisioning API, pass in the following custom header:

```http
T-Test-Account: true
```

You can't allocate a dedicated IP address to a test account. This limits you to sending 100 emails per day irrespective of the offerings used to create the account. You can't change a non-test account that uses this custom header to a test account.

### Work with account state

A customer account exists in one of five states, `activated`, `deactivated`, `suspended`, `banned`, or `indeterminate`\[^1].

* To set the customer account state, make one [`PUT` request][update-acct-state] with one of these states.
* To retrieve the customer account state, make one [`GET` request][get-acct-state] that returns the state for the account.

The following table shows how each state affects an account, including the actions it can take and the resources Twilio SendGrid removes.

| Account state                  | `activated` | `suspended` | `deactivated` | `banned` |
| ------------------------------ | ----------- | ----------- | ------------- | -------- |
| Can log in                     | yes         | yes         | yes           | no       |
| Can request mail messages      | yes         | yes         | no            | no       |
| Can deliver mail messages      | yes         | no          | no            | no       |
| Subusers removed               | no          | no          | no            | yes      |
| Dedicated IP addresses removed | no          | no          | no            | yes      |
| API keys deactivated           | no          | no          | no            | yes      |

\[^1] If you find an account in the `indeterminate` state, [contact Twilio SendGrid support][ts-support].

### Manage customer account offerings

Once you create a customer account, you might need to upgrade or downgrade the account to a different offering. Beyond common email infrastructure offerings, your partner organization might offer "add-ons" features like Marketing Campaigns, Dedicated IP Addresses, and Expert Services.

* To change an account's offerings, make one [`PUT` request][update-acct-offerings] with a JSON request body that contains an `offerings` array.
* To remove offerings from an account, make one `PUT` request that omits the offerings you want to remove from the update request.
  * In each request, pass all offerings you want to keep. Each `PUT` request overwrites the existing offerings for the account.
  * Dedicated IP add-ons are the exception: the `PUT` request ignores them, and omitting them doesn't remove them. To add or remove IPs, see [Manage customer IP addresses](#manage-customer-ip-addresses).
* Changing an account's package removes any offerings the new package does not allow, even if you include them in the request.
  * Dedicated IP add-ons are removed only when the account's current package allows them and the new package doesn't. When they're removed, the account's dedicated IPs are released immediately and can't be returned to the account.
* To get a list of all the offerings that you might assign to a customer account, use the [List Offerings endpoint][list-offerings].
* To get a list of the offerings assigned to an individual customer account, use the [Get Account Offerings][get-acct-offerings] endpoint.

```json {title="Request payload example: Add package offering"}
{
  "offerings": [
    {
      "name": "milne.ei.pro-100k.v1",
      "type": "package",
      "quantity": 1
    }
  ]
}
```

The change offering request returns a list of the account's offerings. This list matches the response to subsequent [Get Account Offerings requests][get-acct-offerings].

### Manage customer IP addresses

To manage dedicated IP addresses for their customer accounts, resellers can use the IP address Provisioning API. To support your customer requirements, you can add, list, and remove IP addresses as needed.

The most common IP address provisioning operations that a reseller uses include:

* Add IP addresses to a customer account.
* List the IP addresses assigned to a customer account.
* Remove IP addresses from a customer account.

#### Add IP addresses to a customer account

To add IP addresses to a customer account, make one [`POST` request][add-ips]. This request provisions and assigns dedicated IP addresses to the specified customer account. This request requires a JSON payload with the quantity of IP addresses and the target region.

The request payload requires two parameters:

| Parameter | Purpose                                                             | Accepted values                     |
| --------- | ------------------------------------------------------------------- | ----------------------------------- |
| `count`   | The number of IP addresses to provision.                            | Number between `1` and `10`         |
| `region`  | The geographic region where the IP addresses should be provisioned. | `us` (United States), `eu` (Europe) |

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

```json {title="Add IP addresses request payload", description="To add two IP addresses in the US region, include a JSON object that resembles the following:"}
{ "count": 2, "region": "us" }
```

```json {title="Add IP addresses response", description="The response returns an HTTP 201 Created status code along with the provisioned IP addresses and their region:"}
{
  "ips": [
    "192.168.1.1",
    "192.168.1.2"
  ],
  "region": "us"
}
```

You can use the returned IP addresses immediately with the customer account.

### List customer account IP addresses

To get a paginated list of all IP addresses associated with a customer account, use a [`GET` operation][list-ips]. This operation returns the IP addresses as last added.

By default, the endpoint returns 10 results per request.

* To change the number of results returned, pass the `limit` query parameter. Each operation can include up to 5,000 results.
* To paginate through results, pass the `offset` parameter. This gets set to the last IP address from the previous response.

```json {title="List IP addresses response", description="The response includes an array of IP address objects, each containing the IP address and its region:"}
{
  "result": [
    {
      "ip": "174.0.2.1",
      "region": "us"
    },
    {
      "ip": "192.0.0.1",
      "region": "eu"
    }
  ],
  "pages": {
    "last": "192.0.0.1"
  }
}
```

### Remove IP addresses from a customer account

To remove IP addresses from a customer account, make a [single `DELETE` operation][delete-ips] that includes a JSON payload.

* The payload contains an array of specific IP addresses.
* Each request can remove between one and 10 IP addresses.
* Specify each IP address in standard [IPv4 notation][ipv4].

```json {title="Remove IP addresses request payload", description="To remove two specific IP addresses, include a JSON object payload that resembles the following:"}
{ "ips": [ "174.0.0.3", "192.0.0.1" ] }
```

A successful response returns a `204 No Content` status code. This removes the IP addresses from the customer account.
When you remove an IP address from a customer account, this stops all email traffic that uses that IP address.
Before removing IP addresses to avoid service disruption, update your customer's sending configuration.

### Deactivate an account

To set the account state to `deactivated`, use the [Update Account State][update-acct-state] operation.

```json {title="Deactivation response"}
{ "state": "deactivated" }
```

### Remove account features

To remove features such as Subusers, use the [Update Account Offerings][update-acct-offerings] operation to move the account to a package that doesn't allow those features.

To remove dedicated IP addresses, use the [Remove IPs][delete-ips] operation.

```json {title="Set offerings payload example", description="This example shows how to update the account with a free offerings payload."}
{
  "offerings": [
    {
      "name": "milne.ei.free-100.v1",
      "type": "package",
      "quantity": 1
    }
  ]
}
```

### Integrate customer SSO

> \[!NOTE]
>
> If you are a customer accessing a SendGrid account provisioned through a cloud marketplace such as AWS, Azure, Google Cloud, or Heroku, see [Cloud marketplace account access](/docs/sendgrid/ui/account-and-settings/marketplace-account-access) for the applicable login flow.

As a reseller partner, you use the Account Provisioning SSO endpoint to trigger a login to the Twilio SendGrid console for the customer.

```mermaid
sequenceDiagram
    autonumber
    participant C as Customer
    participant R as Reseller
    participant API as Account<br>Provisioning API
    participant T as Twilio<br>Console
    link API: Reference @ https://twilio.com/docs/sendgrid/api-reference/account-provisioning-api-account-operations/single-sign-on
    C->>+R: Click "Login"
    R->>+API: POST<br>/v3/partners/accounts<br>/{accountID}/sso
    API->>+R: Redirect<br>(303 "See Other")
    R->>+C: Redirect<br>(303 "See Other")
    C->>+T: Logged in
```

To access accounts provisioned through this API, Twilio only supports *single sign-on* (SSO) for customers. You can't use a username and password option. The reseller can manage their customers' authentication credentials without sharing any data with Twilio. The redirect generated as part of this flow contains a one-time authorization code that logs the user into the Twilio SendGrid console.

* This one-time code lasts 60 seconds.
* You can use each code for login once.
* This blocks any type of man-in-the-middle or replay attack.
* SSO authenticates the customer as an [Admin Teammate][teammate] with permissions to manage every aspect of the customer's account.
* Only the base Admin Teammate can authenticate using SSO.
* Neither teammates nor subusers can use SSO.

From there, set up API keys, create additional teammates or subusers, and configure their sender identity.

> \[!WARNING]
>
> The Account Provisioning API doesn't support the SAML-based SSO offering for customer accounts. All Teammates that belong to a customer account get authenticated with a username and password managed through Twilio SendGrid.

[add-ips]: /docs/sendgrid/api-reference/account-ip-provisioning-api-ip-operations/add-ips

[admin-api-key]: /docs/sendgrid/api-reference/api-key-permissions

[create-account]: /docs/sendgrid/api-reference/account-provisioning-api-account-operations/create-account

[create-api-key]: /docs/sendgrid/ui/account-and-settings/api-keys#create-an-api-key

[delete-ips]: /docs/sendgrid/api-reference/account-ip-provisioning-api-ip-operations/remove-ips

[get-acct-offerings]: /docs/sendgrid/api-reference/account-provisioning-api-offering-operations/get-account-offerings

[get-acct-state]: /docs/sendgrid/api-reference/account-provisioning-api-account-state-operations/get-account-state

[ipv4]: /docs/sendgrid/glossary/ip-address#ipv4-addresses

[list-ips]: /docs/sendgrid/api-reference/account-ip-provisioning-api-ip-operations/list-ips

[list-offerings]: /docs/sendgrid/api-reference/account-provisioning-api-offering-operations/list-offerings

[pricing]: https://www.twilio.com/en-us/products/email-api/pricing

[subusers]: /docs/sendgrid/ui/account-and-settings/subusers

[teammate]: /docs/sendgrid/ui/account-and-settings/teammates#configuring-permissions

[ts-support]: https://support.sendgrid.com/hc/en-us

[tsc-api-keys]: https://app.sendgrid.com/settings/api_keys

[update-acct-offerings]: /docs/sendgrid/api-reference/account-provisioning-api-offering-operations/update-account-offerings

[update-acct-state]: /docs/sendgrid/api-reference/account-provisioning-api-account-state-operations/update-account-state

[use-v3-api]: /docs/sendgrid/api-reference/how-to-use-the-sendgrid-v3-api/authentication