{ "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.\n\nYou 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": "test@test.com", "created_at": "2006-01-02T15:04:05Z", "updated_at": "2009-01-02T15:04:05Z" }, { "id": "sg2a2bcd3ef4ab5c67d8efab91c01de2fa", "email": "testing@test.com", "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": "test@test.com", "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/AccountProvisioningAssignedOfferingList" } } } }, "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" } } } }, "AccountProvisioningAssignedOfferingList": { "title": "AssignedOfferingList", "type": "object", "properties": { "offerings": { "type": "array", "items": { "$ref": "#/components/schemas/AccountProvisioningAssignedOfferingV1" } } } }, "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": "mail@example.com", "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 } }, "AccountProvisioningAssignedOfferingV1": { "title": "AssignedOffering", "type": "object", "description": "An offering assigned to an account, including optional start and end dates indicating when the offering was activated and when it expires.", "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/Type1" }, "quantity": { "type": "integer", "format": "int64", "description": "Quantity of the specified addon. If offering type is `package`, quantity must be 1." }, "start_date": { "type": "string", "format": "date-time", "description": "Timestamp indicating when the offering was activated on the account. Format is [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339)." }, "end_date": { "type": "string", "format": "date-time", "description": "Timestamp indicating when the offering expires. Format is [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339). Absent if the offering has no expiry." } }, "required": [ "name", "type" ], "example": { "name": "org.ei.free.v1", "type": "package", "quantity": 1, "start_date": "2024-01-02T15:04:05Z", "end_date": "2025-01-02T15:04:05Z" } }, "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" ] }, "Type1": { "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" } }