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.
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.**
You 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.
**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: [email protected]
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: [email protected]
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.**
You 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: [email protected]
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: [email protected]
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: [email protected]
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.**
This 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: [email protected]
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.**
You 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: [email protected]
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: [email protected]
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.**
**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.**
Each 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: [email protected]
scopes:
- user.profile.read
- user.profile.edit
is_admin: false
pending_id: abcd123abc
expiration_date: 1456424263
- email:
# --- truncated at 32 KB (38 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sendgrid/refs/heads/main/openapi/tsg_teammates_v3.yaml