On this page

Create Account

API Overview

The Twilio SendGrid Account Provisioning API provides a platform for Twilio SendGrid resellers to manage their customers. This API is for 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 feature, which is available with Pro and Premier plans.

The Account Provisioning API account operations allow you to create, retrieve, and authenticate customer accounts.

The Create Account operation allows you to create a new customer account. The Create Account operation requires a JSON request body containing a profile object and an array of offerings objects.

Profile object

The profile object contains a customer's identity information such as their first_name, last_name, and email. The fields in the profile object are optional — the customer will be prompted at their first login to enter any profile information you choose not to include when creating the account. See the API reference below for all profile fields.

Offerings array

The offerings array contains offering objects that list the offering's name, type, and quantity. The offerings array is required, and it defines the Twilio SendGrid features or offerings available to the customer's account. The offerings available will depend on your agreement with Twilio SendGrid.

To retrieve a list of all the offerings that you can assign to a customer account, use the List Offerings endpoint. Because the available offerings will change infrequently, you may wish to cache the List Offerings response rather than call the endpoint before each account creation or update. A new account may start on any email offering at any price point. Upgrades and downgrades are also available immediately after account provisioning.

Response

The response to a new account creation is the Twilio Sendgrid account ID. This account ID is used in all subsequent calls to the Account Provisioning API, so you should record it in your database for future use.

Operation overview

POST/v3/partners/accounts

Base url: https://api.sendgrid.com (for global users and subusers)

Base url: https://api.eu.sendgrid.com (for EU regional subusers)

Creates a new account, with specified offering, under the organization.

Operation details

Authentication

API Key

Headers

Property nameTypeRequiredDescription

Authorizationstringrequired

Default: Bearer <<YOUR_API_KEY_HERE>>

T-Test-Accountstring

Optional

OPTIONAL Custom request header provided ONLY for a test account

Request body

Encoding type:application/json

SchemaExample

Property nameTypeRequiredDescriptionChild properties

profileobject

Optional

Show child properties for profile

offeringsarray[object]required

List of offering names to assign to account.

Show child properties for offerings

Responses

201400401403500502503504

Created

SchemaExample

Property nameTypeRequiredDescriptionChild properties

account_idstring

Twilio SendGrid account ID

The request was formatted incorrectly or missing required parameters.

SchemaExample

Property nameTypeRequiredDescriptionChild properties

errorsarray[object]

Show child properties for errors

Request lacks valid authentication credentials

SchemaExample

Property nameTypeRequiredDescriptionChild properties

errorsarray[object]

Show child properties for errors

Not authorized to make the request

SchemaExample

Property nameTypeRequiredDescriptionChild properties

errorsarray[object]

Show child properties for errors

Internal Server Error

SchemaExample

Property nameTypeRequiredDescriptionChild properties

errorsarray[object]

Show child properties for errors

Bad Gateway

SchemaExample

Property nameTypeRequiredDescriptionChild properties

errorsarray[object]

Show child properties for errors

Service Unavailable

SchemaExample

Property nameTypeRequiredDescriptionChild properties

errorsarray[object]

Show child properties for errors

Endpoint request timed out

SchemaExample

Property nameTypeRequiredDescriptionChild properties

errorsarray[object]

Show child properties for errors

Create a customer account

1const client = require("@sendgrid/client");
2client.setApiKey(process.env.SENDGRID_API_KEY);
3
4const data = {
5  profile: {
6    first_name: "Sender",
7    last_name: "Wiz",
8    company_name: "Twilio SendGrid",
9    company_website: "https://sendgrid.com",
10    email: "test@test.com",
11    timezone: "Asia/Tokyo",
12  },
13  offerings: [
14    {
15      name: "org.ei.free.v1",
16      type: "package",
17      quantity: 1,
18    },
19  ],
20};
21
22const request = {
23  url: `/v3/partners/accounts`,
24  method: "POST",
25  body: data,
26};
27
28client
29  .request(request)
30  .then(([response, body]) => {
31    console.log(response.statusCode);
32    console.log(response.body);
33  })
34  .catch((error) => {
35    console.error(error);
36  });

Create test customer account

1const client = require("@sendgrid/client");
2client.setApiKey(process.env.SENDGRID_API_KEY);
3
4const headers = { "T-Test-Account": "true" };
5const data = {
6  profile: {
7    first_name: "Sender",
8    last_name: "Wiz",
9    company_name: "Twilio SendGrid",
10    company_website: "https://sendgrid.com",
11    email: "test@test.com",
12    timezone: "Asia/Tokyo",
13  },
14  offerings: [
15    {
16      name: "org.ei.free.v1",
17      type: "package",
18      quantity: 1,
19    },
20  ],
21};
22
23const request = {
24  url: `/v3/partners/accounts`,
25  method: "POST",
26  headers: headers,
27  body: data,
28};
29
30client
31  .request(request)
32  .then(([response, body]) => {
33    console.log(response.statusCode);
34    console.log(response.body);
35  })
36  .catch((error) => {
37    console.error(error);
38  });