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: 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: UserType2: type: string enum: - admin - owner - teammate PermissionType: type: string enum: - admin - restricted UserType: type: string enum: - admin - owner - teammate UserType1: type: string enum: - admin - owner - teammate parameters: 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 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 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. externalDocs: description: Twilio SendGrid's official developer documentation. url: https://www.twilio.com/docs/sendgrid