{ "openapi": "3.1.0", "security": [ { "BearerAuth": [] } ], "info": { "title": "Twilio SendGrid Teammates API", "summary": "The Twilio SendGrid Teammates API allows you to add, manage, and remove Teammates, or user accounts, from your SendGrid account.", "description": "The Twilio SendGrid Teammates API allows you to add, manage, and remove Teammates, or user accounts, from your SendGrid account. Teammates function like user accounts on the SendGrid account, allowing you to invite additional users to your account with scoped access. You can think of Teammates as SendGrid's approach to enabling [role-based access control](https://en.wikipedia.org/wiki/Role-based_access_control) for your SendGrid account. For even more control over the access to your account, see the [Twilio SendGrid SSO API](https://docs.sendgrid.com/api-reference/single-sign-on-teammates/), which enables SSO-authenticated Teammates to be managed through a SAML 2.0 identity provider.", "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": "teammates" } }, "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/teammates": { "post": { "operationId": "InviteTeammate", "summary": "Invite teammate", "tags": [ "Teammates" ], "description": "**This endpoint allows you to invite a Teammate to your account via email.**\n\nYou can set a Teammate's initial permissions using the `scopes` array in the request body. Teammate's will receive a minimum set of scopes from Twilio SendGrid that are necessary for the Teammate to function.\n\n**Note:** A teammate invite will expire after 7 days, but you may resend the invitation at any time to reset the expiration date.", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "New teammate's email", "minLength": 5, "maxLength": 255, "pattern": "^.*@.*\\..*" }, "scopes": { "type": "array", "description": "Set to specify list of scopes that teammate should have. Should be empty if teammate is an admin.", "items": { "type": "string" } }, "is_admin": { "type": "boolean", "default": false, "description": "Set to true if teammate should be an admin user" } }, "required": [ "email", "scopes", "is_admin" ], "example": { "email": "teammate1@example.com", "scopes": [ "user.profile.read", "user.profile.update" ], "is_admin": false } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "Token to identify invite" }, "email": { "type": "string", "description": "Teammate's email address" }, "scopes": { "type": "array", "description": "Initial set of permissions to give to teammate if they accept the invite", "items": {} }, "is_admin": { "type": "boolean", "description": "Set to true if teammate should have admin privileges" } } }, "examples": { "response": { "value": { "email": "teammate1@example.com", "scopes": [ "user.profile.read", "user.profile.update" ], "is_admin": false } } } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "field": { "type": "string" } } } } } } } } } } }, "get": { "operationId": "ListTeammate", "summary": "Retrieve all teammates", "tags": [ "Teammates" ], "description": "**This endpoint allows you to retrieve a paginated list of all current Teammates.**\n\nYou can use the `limit` query parameter to set the page size. If your list contains more items than the page size permits, you can make multiple requests. Use the `offset` query parameter to control the position in the list from which to start retrieving additional items.", "parameters": [ { "name": "limit", "in": "query", "description": "`limit` sets the page size, i.e. maximum number of items from the list to be returned for a single API request. If omitted, the default page size is used. The maximum page size for this endpoint is 500 items per page.", "schema": { "type": "integer", "minimum": 0, "maximum": 500, "default": 500 } }, { "$ref": "#/components/parameters/PaginationCommonOffset" }, { "$ref": "#/components/parameters/OnBehalfOf" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "properties": { "username": { "type": "string", "description": "Teammate's username" }, "email": { "type": "string", "description": "Teammate's email" }, "first_name": { "type": "string", "description": "Teammate's first name" }, "last_name": { "type": "string", "description": "Teammate's last name" }, "user_type": { "type": "string", "description": "Indicate the type of user: owner user, teammate admin user, or normal teammate", "$ref": "#/components/schemas/UserType" }, "is_admin": { "type": "boolean", "description": "Set to true if teammate has admin privileges" }, "phone": { "type": "string", "description": "(optional) Teammate's phone number" }, "website": { "type": "string", "description": "(optional) Teammate's website" }, "address": { "type": "string", "description": "(optional) Teammate's address" }, "address2": { "type": "string", "description": "(optional) Teammate's address" }, "city": { "type": "string", "description": "(optional) Teammate's city" }, "state": { "type": "string", "description": "(optional) Teammate's state" }, "zip": { "type": "string", "description": "(optional) Teammate's zip" }, "country": { "type": "string", "description": "(optional) Teammate's country" } } } } } }, "examples": { "response": { "value": { "results": [ { "username": "teammate1", "email": "teammate1@example.com", "first_name": "Jane", "last_name": "Doe", "user_type": "owner", "is_admin": true, "phone": "123-345-3453", "website": "www.example.com", "company": "ACME Inc.", "address": "123 Acme St", "address2": "", "city": "City", "state": "CA", "country": "USA", "zip": "12345" }, { "username": "teammate2", "email": "teammate2@example.com", "first_name": "John", "last_name": "Doe", "user_type": "teammate", "is_admin": false, "phone": "123-345-3453", "website": "www.example.com", "company": "ACME Inc.", "address": "123 Acme St", "address2": "", "city": "City", "state": "CA", "country": "USA", "zip": "12345" }, { "username": "teammate3", "email": "teammate3@example.com", "first_name": "Steve", "last_name": "Doe", "user_type": "admin", "is_admin": true, "phone": "123-345-3453", "website": "www.example.com", "company": "ACME Inc.", "address": "123 Acme St", "address2": "", "city": "City", "state": "CA", "country": "USA", "zip": "12345" } ] } } } } } } } } }, "/v3/teammates/{teammate_name}/subuser_access": { "parameters": [ { "name": "teammate_name", "in": "path", "description": "The username of the Teammate for whom you want to retrieve Subuser access information.", "required": true, "schema": { "type": "string" } }, { "name": "after_subuser_id", "in": "query", "description": "The Subuser ID from which the API request will begin retrieving Subusers. This query parameter can be used in successive API calls to retrieve additional Subusers.", "required": false, "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "description": "Limit the number of Subusers to be returned. The default `limit` is `100` per request.", "required": false, "schema": { "type": "integer", "default": 100 } }, { "name": "username", "in": "query", "description": "A Subuser's username that will be used to filter the returned result.", "required": false, "schema": { "type": "string" } } ], "get": { "operationId": "ListSubuserByTemplate", "summary": "Get Teammate Subuser Access", "tags": [ "Teammates" ], "description": "**This operation allows you to retrieve the Subusers that can be accessed by a specified Teammate.**\n\nThis operation will return the Subusers available to a Teammate, including the scopes available. If the Teammate is an administrator, all Subusers will be returned.", "responses": { "200": { "description": "200 Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "has_restricted_subuser_access": { "type": "boolean", "description": "When this property is set to `true`, the Teammate has permissions to operate only on behalf of a Subuser. This property value is `true` when the `subuser_access` property is not empty. The `subuser_access` property determines which Subusers the Teammate may act on behalf of." }, "subuser_access": { "type": "array", "description": "Specifies which Subusers the Teammate may access and act on behalf of. If this property is populated, the `has_restricted_subuser_access` property will be `true`.", "items": { "type": "object", "description": "An array of Subusers to which the Teammate has access.", "properties": { "id": { "type": "integer", "description": "The ID of a Subuser to which the Teammate has access. You can retrieve Subuser IDs from the [Subusers API](https://docs.sendgrid.com/api-reference/subusers-api/)." }, "username": { "type": "string", "description": "The username of a Subuser to which the Teammate has access." }, "email": { "type": "string", "description": "The email address of a Subuser to which the Teammate has access." }, "disabled": { "type": "boolean", "description": "Indicates if the Subuser is active for the SendGrid account." }, "permission_type": { "type": "string", "description": "The level of access the Teammate has to the specified Subuser. This property value may be either `admin` or `restricted`. When is property is set to `restricted`, the Teammate has only the permissions assigned in the `scopes` property.", "$ref": "#/components/schemas/PermissionType" }, "scopes": { "type": "array", "description": "The permissions or scopes that the Teammate can access on behalf of the Subuser. See [**Teammate Permissions**](https://docs.sendgrid.com/ui/account-and-settings/teammate-permissions) for a complete list of available scopes.", "items": { "type": "string" } } } } }, "_metadata": { "type": "object", "description": "This object contains response metadata. The presence of the `after_subuser_id` property in the metadata indicates that some items are still outstanding and have not been retrieved. You can use the `after_subuser_id` value to retrieve additional items with another request.", "properties": { "next_params": { "type": "object", "properties": { "limit": { "type": "integer", "description": "The limit specified in the `limit` query parameter to constrain the number of Subusers returned." }, "after_subuser_id": { "type": "integer", "description": "The `after_subuser_id` property represents the last processed Subuser. If the `after_subuser_id` property is `null`, there are no more entries available." }, "username": { "type": "string", "description": "The username of a Subuser passed in the `name` query parameter to filter results by username." } } } } } }, "example": { "has_restricted_subuser_access": true, "subuser_access": [ { "id": 1234, "username": "examplesubuser", "email": "subuser@example.com", "disabled": true, "permission_type": "admin", "scopes": [ "billing.read" ] } ], "_metadata": { "next_params": { "limit": 0, "after_subuser_id": 0, "username": "string" } } } } } } }, "400": { "description": "400 Bad request", "content": { "application/json": { "schema": { "type": "object", "description": "An object containing an array of errors objects.", "properties": { "errors": { "type": "array", "items": { "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." } } } } } }, "example": { "errors": [ { "message": "Bad request", "field": "" } ] } } } }, "401": { "description": "401 Forbidden", "content": { "application/json": { "schema": { "type": "object", "description": "An object containing an array of errors objects.", "properties": { "errors": { "type": "array", "items": { "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." } } } } } }, "example": { "errors": [ { "message": "Unauthorized", "field": "" } ] } } } }, "403": { "description": "403 Forbidden", "content": { "application/json": { "schema": { "type": "object", "description": "An object containing an array of errors objects.", "properties": { "errors": { "type": "array", "items": { "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." } } } } } }, "example": { "errors": [ { "message": "Forbidden", "field": "" } ] } } } }, "500": { "description": "500", "content": { "application/json": { "schema": { "type": "object", "description": "An object containing an array of errors objects.", "properties": { "errors": { "type": "array", "items": { "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." } } } } } }, "example": { "errors": [ { "message": "Server error", "field": "" } ] } } } } } } }, "/v3/teammates/{username}": { "parameters": [ { "name": "username", "in": "path", "description": "The username of the teammate that you want to retrieve.", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "GetTeammate", "summary": "Retrieve specific teammate", "tags": [ "Teammates" ], "description": "**This endpoint allows you to retrieve a specific Teammate by username.**\n\nYou can retrieve the username's for each of your Teammates using the \"Retrieve all Teammates\" endpoint.", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "username": { "type": "string", "description": "Teammate's username" }, "first_name": { "type": "string", "description": "Teammate's first name" }, "last_name": { "type": "string", "description": "Teammate's last name" }, "email": { "type": "string", "description": "Teammate's email" }, "scopes": { "type": "array", "description": "Scopes associated to teammate", "items": {} }, "user_type": { "type": "string", "description": "Indicate the type of user: account owner, teammate admin user, or normal teammate", "$ref": "#/components/schemas/UserType1" }, "is_admin": { "type": "boolean", "description": "Set to true if teammate has admin privileges" }, "phone": { "type": "string", "description": "(optional) Teammate's phone number" }, "website": { "type": "string", "description": "(optional) Teammate's website" }, "address": { "type": "string", "description": "(optional) Teammate's address" }, "address2": { "type": "string", "description": "(optional) Teammate's address" }, "city": { "type": "string", "description": "(optional) Teammate's city" }, "state": { "type": "string", "description": "(optional) Teammate's state" }, "zip": { "type": "string", "description": "(optional) Teammate's zip" }, "country": { "type": "string", "description": "(optional) Teammate's country" } } }, "examples": { "response": { "value": { "username": "teammate1", "first_name": "Jane", "last_name": "Doe", "email": "teammate1@example.com", "scopes": [ "user.profile.read", "user.profile.update", "..." ], "user_type": "admin", "is_admin": true, "phone": "123-345-3453", "website": "www.example.com", "company": "ACME Inc.", "address": "123 Acme St", "address2": "", "city": "City", "state": "CA", "country": "USA", "zip": "12345" } } } } } } } }, "patch": { "operationId": "UpdateTeammate", "summary": "Update teammate's permissions", "tags": [ "Teammates" ], "description": "**This endpoint allows you to update a teammate\u2019s permissions.**\n\nTo turn a teammate into an admin, the request body should contain an `is_admin` set to `true`. Otherwise, set `is_admin` to `false` and pass in all the scopes that a teammate should have.\n\n**Only the parent user or other admin teammates can update another teammate\u2019s permissions.**\n\n**Admin users can only update permissions.**", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "scopes": { "type": "array", "description": "Provide list of scopes that should be given to teammate. If specifying list of scopes, is_admin should be set to False.", "items": { "type": "string" } }, "is_admin": { "type": "boolean", "description": "Set to True if this teammate should be promoted to an admin user. If True, scopes should be an empty array." } }, "required": [ "scopes", "is_admin" ], "example": { "scopes": [ "user.profile.read", "user.profile.edit" ], "is_admin": false } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "username": { "type": "string", "description": "Teammate's username" }, "first_name": { "type": "string", "description": "Teammate's first name" }, "last_name": { "type": "string", "description": "Teammate's last name" }, "email": { "type": "string", "description": "Teammate's email address" }, "scopes": { "type": "array", "description": "Scopes given to teammate", "items": { "type": "string" } }, "user_type": { "type": "string", "description": "Indicate the type of user: owner user, teammate admin user, or normal teammate", "$ref": "#/components/schemas/UserType2" }, "is_admin": { "type": "boolean", "description": "Set to true if teammate has admin priveleges" }, "phone": { "type": "string", "description": "(optional) Teammate's phone number" }, "website": { "type": "string", "description": "(optional) Teammate's website" }, "address": { "type": "string", "description": "(optional) Teammate's address" }, "address2": { "type": "string", "description": "(optional) Teammate's address" }, "city": { "type": "string", "description": "(optional) Teammate's city" }, "state": { "type": "string", "description": "(optional) Teammate's state" }, "zip": { "type": "string", "description": "(optional) Teammate's zip" }, "country": { "type": "string", "description": "(optional) Teammate's country" } } }, "examples": { "response": { "value": { "username": "teammate1", "first_name": "Jane", "last_name": "Doe", "email": "teammate1@example.com", "scopes": [ "user.profile.read", "user.profile.edit" ], "user_type": "teammate", "is_admin": false, "phone": "123-345-3453", "website": "www.example.com", "company": "ACME Inc.", "address": "123 Acme St", "address2": "", "city": "City", "state": "CA", "country": "USA", "zip": "12345" } } } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "field": { "type": "string" } } } } } }, "examples": { "response": { "value": { "errors": [ { "message": "one or more of given scopes are invalid", "field": "scopes" } ] } } } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "field": { "type": "string" } } } } } }, "examples": { "response": { "value": { "errors": [ { "message": "username not found", "field": "username" } ] } } } } } } } }, "delete": { "operationId": "DeleteTeammate", "summary": "Delete teammate", "tags": [ "Teammates" ], "description": "**This endpoint allows you to delete a teammate.**\n\n**Only the parent user or an admin teammate can delete another teammate.**", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "responses": { "204": { "description": "The Teammate was successfully deleted." }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "field": { "type": "string" } } } } } }, "examples": { "response": { "value": { "errors": [ { "message": "username not found", "field": "username" } ] } } } } } } } } }, "/v3/teammates/pending": { "get": { "operationId": "ListPendingTeammate", "summary": "Retrieve all pending teammates", "tags": [ "Teammates" ], "description": "**This endpoint allows you to retrieve a list of all pending Teammate invitations.**\n\nEach teammate invitation is valid for 7 days. Users may resend the invitation to refresh the expiration date.", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "Email address teammate invite will be sent to" }, "scopes": { "type": "array", "description": "List of permissions to give teammate if they accept", "items": { "type": "string" } }, "is_admin": { "type": "boolean", "description": "Set to true to indicate teammate should have the same set of permissions as parent user" }, "token": { "type": "string", "description": "Invitation token used to identify user" }, "expiration_date": { "type": "integer", "description": "timestamp indicates when invite will expire. Expiration is 7 days after invite creation" } } } } } }, "examples": { "response": { "value": { "result": [ { "email": "user1@example.com", "scopes": [ "user.profile.read", "user.profile.edit" ], "is_admin": false, "pending_id": "abcd123abc", "expiration_date": 1456424263 }, { "email": "user2@example.com", "scopes": [], "is_admin": true, "pending_id": "bcde234bcd", "expiration_date": 1456424263 } ] } } } } } } } } }, "/v3/teammates/pending/{token}": { "parameters": [ { "name": "token", "in": "path", "description": "The token for the invite you want to delete.", "required": true, "schema": { "type": "string" } } ], "delete": { "operationId": "DeletePendingTeammate", "summary": "Delete pending teammate", "tags": [ "Teammates" ], "description": "**This endpoint allows you to delete a pending teammate invite.**", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "responses": { "204": { "description": "" }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "field": { "type": "string" } } } } } } } } } } } }, "/v3/teammates/pending/{token}/resend": { "parameters": [ { "name": "token", "in": "path", "description": "The token for the invite that you want to resend.", "required": true, "schema": { "type": "string" } } ], "post": { "operationId": "ResendTeammateInvite", "summary": "Resend teammate invite", "tags": [ "Teammates" ], "description": "**This endpoint allows you to resend a Teammate invitation.**\n\nTeammate invitations will expire after 7 days. Resending an invitation will reset the expiration date.", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "ID to identify invite" }, "email": { "type": "string", "description": "Teammate's email address" }, "scopes": { "type": "array", "description": "Initial set of permissions to give to teammate if they accept the invite", "items": { "type": "string" } }, "is_admin": { "type": "boolean", "description": "Set to true if teammate should have admin privileges" } } }, "examples": { "response": { "value": { "pending_id": "abc123abc", "email": "teammate1@example.com", "scopes": [ "user.profile.read", "user.profile.update" ], "is_admin": false } } } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "field": { "type": "string" } } } } } }, "examples": { "response": { "value": { "errors": [ { "message": "invalid pending key", "field": "pending_key" } ] } } } } } } } } } }, "components": { "schemas": { "UserType": { "type": "string", "enum": [ "admin", "owner", "teammate" ] }, "PermissionType": { "type": "string", "enum": [ "admin", "restricted" ] }, "UserType1": { "type": "string", "enum": [ "admin", "owner", "teammate" ] }, "UserType2": { "type": "string", "enum": [ "admin", "owner", "teammate" ] } }, "responses": {}, "parameters": { "OnBehalfOf": { "name": "on-behalf-of", "in": "header", "description": "The `on-behalf-of` header allows you to make API calls from a parent account on behalf of the parent's Subusers or customer accounts. You will use the parent account's API key when using this header. When making a call on behalf of a customer account, the property value should be \"account-id\" followed by the customer account's ID (e.g., `on-behalf-of: account-id `). When making a call on behalf of a Subuser, the property value should be the Subuser's username (e.g., `on-behalf-of: `). See [**On Behalf Of**](https://docs.sendgrid.com/api-reference/how-to-use-the-sendgrid-v3-api/on-behalf-of) for more information.", "required": false, "schema": { "type": "string" } }, "PaginationCommonOffset": { "name": "offset", "in": "query", "required": false, "description": "The number of items in the list to skip over before starting to retrieve the items for the requested page. The default `offset` of `0` represents the beginning of the list, i.e. the start of the first page. To request the second page of the list, set the `offset` to the page size as determined by `limit`. Use multiples of the page size as your `offset` to request further consecutive pages. E.g. assume your page size is set to `10`. An `offset` of `10` requests the second page, an `offset` of `20` requests the third page and so on, provided there are sufficiently many items in your list.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } }, "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": "Teammates", "description": "Twilio SendGrid Teammates API" } ], "externalDocs": { "description": "Twilio SendGrid's official developer documentation.", "url": "https://www.twilio.com/docs/sendgrid" } }