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. You can access Twilio SendGrid sub-account functionality without becoming a reseller.
openapi: 3.1.0
security:
- BearerAuth: []
info:
title: Twilio SendGrid Account Provisioning API
summary: The Twilio SendGrid Account Provisioning API provides a platform for Twilio
SendGrid resellers to manage their customer accounts.
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.
You can access Twilio SendGrid sub-account functionality without becoming a reseller.
If you require sub-account functionality, see the Twilio [SendGrid Subusers](https://docs.sendgrid.com/ui/account-and-settings/subusers)
feature, which is available with [Pro and Premier plans](https://sendgrid.com/pricing/).'
termsOfService: https://www.twilio.com/legal/tos
contact:
name: Twilio SendGrid Support
url: https://support.sendgrid.com/hc/en-us
license:
name: MIT
url: https://code.hq.twilio.com/twilio/sendgrid-oas/blob/main/LICENSE
version: 1.0.0
x-sendgrid:
libraryPackage: account_provisioning
servers:
- url: https://api.sendgrid.com
description: for global users and subusers
- url: https://api.eu.sendgrid.com
description: for EU regional subusers
paths:
/v3/partners/accounts:
get:
operationId: ListAccount
summary: Get all accounts
tags:
- Account
description: Retrieves all accounts under the organization.
parameters:
- $ref: '#/components/parameters/AccountProvisioningLastParam'
- $ref: '#/components/parameters/AccountProvisioningCountParam'
responses:
'200':
description: OK
content:
application/json:
schema:
title: AccountList
type: object
properties:
accounts:
type: array
description: List of account objects.
items:
$ref: '#/components/schemas/AccountProvisioningAccount'
pages:
$ref: '#/components/schemas/AccountProvisioningPagination'
example:
accounts:
- id: sg2a2bcd3ef4ab5c67d8efab91c01de2fa
email: [email protected]
created_at: '2006-01-02T15:04:05Z'
updated_at: '2009-01-02T15:04:05Z'
- id: sg2a2bcd3ef4ab5c67d8efab91c01de2fa
email: [email protected]
created_at: '2006-01-02T15:04:05Z'
updated_at: '2009-01-02T15:04:05Z'
pages:
last: sg2a2bcd3ef4ab5c67d8efab91c01de2fa
'400':
$ref: '#/components/responses/AccountProvisioningErrorResponse400'
'401':
$ref: '#/components/responses/AccountProvisioningErrorResponse401'
'403':
$ref: '#/components/responses/AccountProvisioningErrorResponse403'
'404':
$ref: '#/components/responses/AccountProvisioningErrorResponse404'
'500':
$ref: '#/components/responses/AccountProvisioningErrorResponse500'
'502':
$ref: '#/components/responses/AccountProvisioningErrorResponse502'
'503':
$ref: '#/components/responses/AccountProvisioningErrorResponse503'
'504':
$ref: '#/components/responses/AccountProvisioningErrorResponse504'
post:
operationId: CreateAccount
summary: Create an account
description: Creates a new account, with specified offering, under the organization.
parameters:
- $ref: '#/components/parameters/AccountProvisioningTestHeader'
tags:
- Account
requestBody:
required: true
content:
application/json:
schema:
title: CreateAccountParams
type: object
properties:
profile:
$ref: '#/components/schemas/AccountProvisioningProfile'
offerings:
type: array
description: List of offering names to assign to account.
items:
$ref: '#/components/schemas/AccountProvisioningOfferingV1'
required:
- offerings
example:
profile:
first_name: Sender
last_name: Wiz
company_name: Twilio SendGrid
company_website: https://sendgrid.com
email: [email protected]
timezone: Asia/Tokyo
offerings:
- name: org.ei.free.v1
type: package
quantity: 1
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/AccountProvisioningAccountId'
'400':
$ref: '#/components/responses/AccountProvisioningErrorResponse400'
'401':
$ref: '#/components/responses/AccountProvisioningErrorResponse401'
'403':
$ref: '#/components/responses/AccountProvisioningErrorResponse403'
'500':
$ref: '#/components/responses/AccountProvisioningErrorResponse500'
'502':
$ref: '#/components/responses/AccountProvisioningErrorResponse502'
'503':
$ref: '#/components/responses/AccountProvisioningErrorResponse503'
'504':
$ref: '#/components/responses/AccountProvisioningErrorResponse504'
/v3/partners/accounts/{accountID}:
parameters:
- $ref: '#/components/parameters/AccountProvisioningAccountId'
delete:
operationId: DeleteAccount
summary: Delete an account
description: "Delete a specific account under your organization by account ID.\
\ Note that this is an **irreversible** action that does the following:\n\n\
\ - Revokes API Keys and SSO so that the account user cannot log in or access\
\ SendGrid data.\n - Removes all offerings and configured SendGrid resources\
\ such as dedicated IPs.\n - Cancels billing effective immediately."
tags:
- Account
responses:
'204':
description: Account successfully deleted.
'400':
$ref: '#/components/responses/AccountProvisioningErrorResponse400'
'401':
$ref: '#/components/responses/AccountProvisioningErrorResponse401'
'403':
$ref: '#/components/responses/AccountProvisioningErrorResponse403'
'404':
$ref: '#/components/responses/AccountProvisioningErrorResponse404'
'500':
$ref: '#/components/responses/AccountProvisioningErrorResponse500'
'502':
$ref: '#/components/responses/AccountProvisioningErrorResponse502'
'503':
$ref: '#/components/responses/AccountProvisioningErrorResponse503'
'504':
$ref: '#/components/responses/AccountProvisioningErrorResponse504'
/v3/partners/accounts/{accountID}/offerings:
parameters:
- $ref: '#/components/parameters/AccountProvisioningAccountId'
get:
operationId: ListAccountOffering
summary: Get account offerings
description: Retrieves offering information about the specified account.
tags:
- Offering
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AccountProvisioningOfferingList'
'400':
$ref: '#/components/responses/AccountProvisioningErrorResponse400'
'401':
$ref: '#/components/responses/AccountProvisioningErrorResponse401'
'403':
$ref: '#/components/responses/AccountProvisioningErrorResponse403'
'404':
$ref: '#/components/responses/AccountProvisioningErrorResponse404'
'500':
$ref: '#/components/responses/AccountProvisioningErrorResponse500'
'502':
$ref: '#/components/responses/AccountProvisioningErrorResponse502'
'503':
$ref: '#/components/responses/AccountProvisioningErrorResponse503'
'504':
$ref: '#/components/responses/AccountProvisioningErrorResponse504'
put:
operationId: UpdateAccountOffering
summary: Update account offerings
description: Changes a package offering for the specified account. Please note
that an account can have only one package offering. Also associates one or
more add-on offerings such as Marketing Campaigns, Dedicated IP Addresses,
and Expert Services to the specified account.
tags:
- Offering
requestBody:
required: true
content:
application/json:
schema:
title: OfferingsToAdd
type: object
properties:
offerings:
type: array
description: List of offerings to assign to account.
items:
$ref: '#/components/schemas/AccountProvisioningOfferingV1'
required:
- offerings
example:
offerings:
- name: org.ei.free.v1
type: package
quantity: 1
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AccountProvisioningOfferingList'
'400':
$ref: '#/components/responses/AccountProvisioningErrorResponse400'
'401':
$ref: '#/components/responses/AccountProvisioningErrorResponse401'
'403':
$ref: '#/components/responses/AccountProvisioningErrorResponse403'
'500':
$ref: '#/components/responses/AccountProvisioningErrorResponse500'
'502':
$ref: '#/components/responses/AccountProvisioningErrorResponse502'
'503':
$ref: '#/components/responses/AccountProvisioningErrorResponse503'
'504':
$ref: '#/components/responses/AccountProvisioningErrorResponse504'
/v3/partners/accounts/{accountID}/sso:
parameters:
- $ref: '#/components/parameters/AccountProvisioningAccountId'
post:
operationId: AuthenticateAccount
summary: Authenticate an account with single sign on
description: Authenticates and logs in a user to Twilio Sendgrid as a specific
admin identity configured for SSO by partner. Any additional teammates or
subusers will need to log in directly via app.sendgrid.com
tags:
- Account
responses:
'303':
description: Successful redirect to app.sendgrid.com.
'401':
$ref: '#/components/responses/AccountProvisioningErrorResponse401'
'403':
$ref: '#/components/responses/AccountProvisioningErrorResponse403'
'404':
$ref: '#/components/responses/AccountProvisioningErrorResponse404'
'500':
$ref: '#/components/responses/AccountProvisioningErrorResponse500'
'502':
$ref: '#/components/responses/AccountProvisioningErrorResponse502'
'503':
$ref: '#/components/responses/AccountProvisioningErrorResponse503'
'504':
$ref: '#/components/responses/AccountProvisioningErrorResponse504'
/v3/partners/accounts/{accountID}/state:
parameters:
- $ref: '#/components/parameters/AccountProvisioningAccountId'
get:
operationId: GetAccountState
summary: Get an account's state
description: Retrieve the state of the specified account.
tags:
- Account State
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AccountProvisioningStateRead'
'400':
$ref: '#/components/responses/AccountProvisioningErrorResponse400'
'401':
$ref: '#/components/responses/AccountProvisioningErrorResponse401'
'403':
$ref: '#/components/responses/AccountProvisioningErrorResponse403'
'404':
$ref: '#/components/responses/AccountProvisioningErrorResponse404'
'500':
$ref: '#/components/responses/AccountProvisioningErrorResponse500'
'502':
$ref: '#/components/responses/AccountProvisioningErrorResponse502'
'503':
$ref: '#/components/responses/AccountProvisioningErrorResponse503'
'504':
$ref: '#/components/responses/AccountProvisioningErrorResponse504'
put:
operationId: UpdateAccountState
summary: Update an account's state
description: Update the state of the specified account.
tags:
- Account State
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AccountProvisioningStateWrite'
responses:
'204':
description: State successfully updated
'400':
$ref: '#/components/responses/AccountProvisioningErrorResponse400'
'401':
$ref: '#/components/responses/AccountProvisioningErrorResponse401'
'403':
$ref: '#/components/responses/AccountProvisioningErrorResponse403'
'500':
$ref: '#/components/responses/AccountProvisioningErrorResponse500'
'502':
$ref: '#/components/responses/AccountProvisioningErrorResponse502'
'503':
$ref: '#/components/responses/AccountProvisioningErrorResponse503'
'504':
$ref: '#/components/responses/AccountProvisioningErrorResponse504'
/v3/partners/offerings:
get:
operationId: ListOffering
summary: Get all available offerings
tags:
- Offering
description: Retrieves offerings available under the organization.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AccountProvisioningCatalog'
'400':
$ref: '#/components/responses/AccountProvisioningErrorResponse400'
'401':
$ref: '#/components/responses/AccountProvisioningErrorResponse401'
'403':
$ref: '#/components/responses/AccountProvisioningErrorResponse403'
'404':
$ref: '#/components/responses/AccountProvisioningErrorResponse404'
'500':
$ref: '#/components/responses/AccountProvisioningErrorResponse500'
'502':
$ref: '#/components/responses/AccountProvisioningErrorResponse502'
'503':
$ref: '#/components/responses/AccountProvisioningErrorResponse503'
'504':
$ref: '#/components/responses/AccountProvisioningErrorResponse504'
components:
schemas:
AccountProvisioningAccount:
title: Account
type: object
properties:
id:
type: string
description: Twilio SendGrid account ID
created_at:
type: string
format: date-time
description: Timestamp indicating when the account was created. Format is
[RFC3339](https://datatracker.ietf.org/doc/html/rfc3339)
required:
- id
- created_at
example:
id: ''
created_at: '2022-01-02T15:04:05Z'
AccountProvisioningAccountId:
title: AccountID
type: object
properties:
account_id:
type: string
description: Twilio SendGrid account ID
required:
- account_id
example:
account_id: sg2a2bcd3ef4ab5c67d8efab91c01de2fa
AccountProvisioningCatalog:
title: Catalog
type: object
properties:
catalog:
type: array
items:
title: CatalogEntry
type: object
properties:
offering:
$ref: '#/components/schemas/AccountProvisioningOfferingV1'
entitlements:
type: object
description: Set of entitlements the specified offering comes with
properties:
email_sends_max_monthly:
type: integer
format: int64
description: Total number of email sends per month
ip_count:
type: integer
format: int64
description: Number of dedicated IPs offered
teammates_max_total:
type: integer
format: int64
description: Total number of teammates allowed
users_max_total:
type: integer
format: int64
description: Total number of subusers allowed
required:
- catalog
example:
catalog:
- offering:
name: org.ei.free.v1
type: package
quantity: 1
entitlements:
email_sends_max_monthly: 10000
ip_count: 0
teammates_max_total: 0
users_max_total: 0
AccountProvisioningOfferingList:
title: OfferingList
type: object
properties:
offerings:
type: array
items:
$ref: '#/components/schemas/AccountProvisioningOfferingV1'
AccountProvisioningPagination:
title: Pagination
type: object
properties:
last:
type: string
description: The last item returned
example:
last: sg2a2bcd3ef4ab5c67d8efab91c01de2fa
AccountProvisioningProfile:
title: Profile
type: object
properties:
first_name:
type: string
description: First name of the account holder
last_name:
type: string
description: Last name of the account holder
company_name:
type: string
description: Company name of the account holder
company_website:
type: string
description: Company website of the account holder
email:
type: string
description: Email of the account holder
phone:
type: string
description: Phone number with a maximum of fifteen digits formatted using
the E.164 standard consisting of [+] [country code] [subscriber number
including area code]
timezone:
type: string
description: Area/Location as listed in the [IANA Time Zone database](https://www.iana.org/time-zones)
example:
first_name: Sender
last_name: Wiz
company_name: Example Co
company_website: https://example.com
email: [email protected]
timezone: Asia/Tokyo
AccountProvisioningStateRead:
title: StateRead
type: object
properties:
state:
type: string
description: The state of the account (e.g., `activated`, `deactivated`,
`suspended`, `banned`, or `indeterminate`)
$ref: '#/components/schemas/State'
required:
- state
example:
state: activated
AccountProvisioningStateWrite:
title: StateWrite
type: object
properties:
state:
type: string
description: The state of the account (e.g., `activated`, `deactivated`)
$ref: '#/components/schemas/State1'
required:
- state
example:
state: activated
AccountProvisioningOfferingV1:
title: Offering
type: object
description: An offering is a package (email infrastructure) or add-on (marketing
campaigns, dedicated IP addresses, EASE) that an account can acquire. Each
offering has a list of entitlements that indicate the benefits the account
receives from the acquisition.
properties:
name:
type: string
description: Name of the offering
type:
type: string
description: Defines the type of offering (e.g., package or addon).
$ref: '#/components/schemas/Type'
quantity:
type: integer
format: int64
description: Quantity of the specified addon to be added. If offering type
is `package`, quantity must be 1.
required:
- name
- type
example:
name: org.ei.free.v1
type: package
quantity: 1
ErrorResponse:
title: Error
type: object
properties:
message:
type: string
description: The message representing the error from the API.
field:
type: string
description: The field associated with the error.
error_id:
type: string
description: ID representing the error as a unique nubmer.
required:
- message
- field
- error_id
State:
type: string
enum:
- activated
- deactivated
- suspended
- banned
- indeterminate
State1:
type: string
enum:
- activated
- deactivated
Type:
type: string
enum:
- package
- addon
responses:
AccountProvisioningErrorResponse400:
description: The request was formatted incorrectly or missing required parameters.
content:
application/json:
schema:
title: Bad Request
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/ErrorResponse'
required:
- errors
example:
errors:
- message: Field must be a valid email
field: email
error_id: 10-40002
- message: Field must be formatted using the E.164 standard consisting
of [+] [country code] [subscriber number including area code] and
can have a maximum of fifteen digits.
field: phone
error_id: 10-40010
- message: Field must be a valid URL
field: company_website
error_id: 10-40008
AccountProvisioningErrorResponse401:
description: Request lacks valid authentication credentials
content:
application/json:
schema:
title: Unauthorized
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/ErrorResponse'
example:
errors:
- message: Failed to authenticate user
field: ''
error_id: 10-40100
AccountProvisioningErrorResponse403:
description: Not authorized to make the request
content:
application/json:
schema:
title: Forbidden
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/ErrorResponse'
example:
errors:
- message: The authenticated user is not authorized to perfrom this request
field: ''
error_id: 10-40300
AccountProvisioningErrorResponse404:
description: Not Found
content:
application/json:
schema:
title: Not Found
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/ErrorResponse'
example:
errors:
- message: No such endpoint
field: ''
error_id: 10-40400
AccountProvisioningErrorResponse500:
description: Internal Server Error
content:
application/json:
schema:
title: InternalServerError
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/ErrorResponse'
example:
errors:
- message: Something went wrong
field: ''
error_id: 10-50000
AccountProvisioningErrorResponse502:
description: Bad Gateway
content:
application/json:
schema:
title: Bad Gateway
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/ErrorResponse'
example:
errors:
- message: Bad Gateway
field: ''
error_id: 10-50200
AccountProvisioningErrorResponse503:
description: Service Unavailable
content:
application/json:
schema:
title: Service Unavailable
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/ErrorResponse'
example:
errors:
- message: Service Unavailable
field: ''
error_id: 10-50300
AccountProvisioningErrorResponse504:
description: Endpoint request timed out
content:
application/json:
schema:
title: Endpoint request timed out
type: object
properties:
errors:
type: array
items:
$ref: '#/components/schemas/ErrorResponse'
example:
errors:
- message: Endpoint request timed out
field: ''
error_id: 10-50400
parameters:
AccountProvisioningAccountId:
name: accountID
in: path
description: Twilio SendGrid account ID
schema:
type: string
required: true
example: sg2a2bcd3ef4ab5c67d8efab91c01de2fa
AccountProvisioningCountParam:
name: limit
in: query
description: The number of items to return
schema:
type: integer
default: 10
maximum: 100
required: false
example: 2
AccountProvisioningLastParam:
name: offset
in: query
description: The last item successfully retrieved
schema:
type: string
required: false
example: sg2a2bcd3ef4ab5c67d8efab91c01de2fa
AccountProvisioningTestHeader:
name: T-Test-Account
in: header
description: '**OPTIONAL** Custom request header provided ONLY for a test account'
schema:
type: string
required: false
examples: {}
requestBodies: {}
headers: {}
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: Twilio SendGrid requires you to authenticate with its APIs using
an API key. The API key must be sent as a bearer token in the Authorization
header.
tags:
- name: Account
description: Twilio SendGrid Account Provisioning API account operations.
- name: Account State
description: Twilio SendGrid Account Provisioning API account state operations.
- name: Offering
description: Twilio SendGrid Account Provisioning API offerings operations.
externalDocs:
description: Twilio SendGrid's official developer documentation.
url: https://www.twilio.com/docs/sendgrid