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


        **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: true
      schema:
        type: string
    post:
      operationId: ResendTeammateInvite
      summary: Resend teammate invite
      tags:
      - Teammates
      description: '**This endpoint allows you to resend a Teammate invitation.**


        Teammate 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 <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: <subuser-username>`). 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