SendGrid Teammates API

openapi: 3.1.0
info:
  title: Twilio SendGrid Provisioning Account Teammates 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
security:
- BearerAuth: []
tags:
- name: Teammates
  description: Twilio SendGrid Teammates API
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: 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.**


        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: 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.**


        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: 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.**


        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: 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’s permissions.**


        To 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.


        **Only the parent user or other admin teammates can update another teammate’s permissions.**


        **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.**


        **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: 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: 

# --- truncated at 32 KB (36 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sendgrid/refs/heads/main/openapi/sendgrid-teammates-api-openapi.yml