openapi: 3.1.0
info:
  title: Twilio SendGrid Provisioning Account Users API 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: Users API
  description: Twilio SendGrid Users API.
paths:
  /v3/user/account:
    get:
      operationId: ListAccount
      summary: Get a user's account information.
      tags:
      - Users API
      description: '**This endpoint allows you to retrieve your user account details.**


        Your user''s account information includes the user''s account type and reputation.'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                title: GET User Account response
                type: object
                properties:
                  type:
                    type: string
                    description: The type of account for this user.
                    $ref: '#/components/schemas/Type'
                  reputation:
                    type: number
                    description: The sender reputation for this user.
                required:
                - type
                - reputation
              examples:
                response:
                  value:
                    reputation: 100
                    type: paid
  /v3/user/credits:
    get:
      operationId: ListCredit
      summary: Retrieve your credit balance
      tags:
      - Users API
      description: '**This endpoint allows you to retrieve the current credit balance for your account.**


        Each account has a credit balance, which is a base number of emails it can send before receiving per-email charges. For more information about credits and billing, see [Billing and Plan details information](https://sendgrid.com/docs/ui/account-and-settings/billing/).'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  remain:
                    type: integer
                    description: The remaining number of credits available on your account.
                  total:
                    type: integer
                    description: The total number of credits assigned to your account.
                  overage:
                    type: integer
                    description: The number of overdrawn credits for your account.
                  used:
                    type: integer
                    description: The number of credits that you have used.
                  last_reset:
                    type: string
                    description: The date that your credit balance was last reset.
                  next_reset:
                    type: string
                    description: The next date that your credit balance will be reset.
                  reset_frequency:
                    type: string
                    description: The frequency at which your credit balance will be reset.
                required:
                - remain
                - total
                - overage
                - used
                - last_reset
                - next_reset
                - reset_frequency
              examples:
                response:
                  value:
                    remain: 200
                    total: 200
                    overage: 0
                    used: 0
                    last_reset: '2013-01-01'
                    next_reset: '2013-02-01'
                    reset_frequency: monthly
  /v3/user/email:
    get:
      operationId: ListEmail
      summary: Retrieve your account email address
      tags:
      - Users API
      description: '**This endpoint allows you to retrieve the email address currently on file for your account.**'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  email:
                    type: string
                    description: The email address currently on file for your account.
                    format: email
                required:
                - email
              examples:
                response:
                  value:
                    email: test@example.com
    put:
      operationId: UpdateEmail
      summary: Update your account email address
      tags:
      - Users API
      description: '**This endpoint allows you to update the email address currently on file for your account.**'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  description: The new email address that you would like to use for your account.
              example:
                email: example@example.com
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  email:
                    type: string
                    description: The current email address on file for your account.
                    format: email
                required:
                - email
              examples:
                response:
                  value:
                    email: example@example.com
  /v3/user/password:
    put:
      operationId: UpdatePassword
      summary: Update your password
      tags:
      - Users API
      description: '**This endpoint allows you to update your password.**'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                new_password:
                  type: string
                  description: The new password you would like to use for your account.
                old_password:
                  type: string
                  description: The old password for your account.
              required:
              - new_password
              - old_password
              example:
                new_password: new_password
                old_password: old_password
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties: {}
  /v3/user/profile:
    get:
      operationId: ListProfile
      summary: Get a user's profile
      description: '**This endpoint allows you to retrieve your current profile details.**'
      tags:
      - Users API
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                title: GET User Profile response
                type: object
                properties:
                  address:
                    type: string
                    description: The user's address.
                  address2:
                    type: string
                    description: The second line of the user's address.
                  city:
                    type: string
                    description: The user's city.
                  company:
                    type: string
                    description: The name of the user's company.
                  country:
                    type: string
                    description: The user's country.
                  first_name:
                    type: string
                    description: The user's first name.
                  last_name:
                    type: string
                    description: The user's last name.
                  phone:
                    type: string
                    description: The user's phone number.
                  state:
                    type: string
                    description: The user's state.
                  website:
                    type: string
                    description: The user's website URL.
                  zip:
                    type: string
                    description: The user's zip code.
                required:
                - address
                - city
                - company
                - country
                - first_name
                - last_name
                - phone
                - state
                - website
                - zip
              examples:
                response:
                  value:
                    address: 814 West Chapman Avenue
                    address2: ''
                    city: Orange
                    company: SendGrid
                    country: US
                    first_name: Test
                    last_name: User
                    phone: 555-555-5555
                    state: CA
                    website: http://www.sendgrid.com
                    zip: '92868'
    patch:
      operationId: UpdateProfile
      summary: Update a user's profile
      tags:
      - Users API
      description: '**This endpoint allows you to update your current profile details.**


        Any one or more of the parameters can be updated via the PATCH `/user/profile` endpoint. You must include at least one when you PATCH.'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserProfile'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserProfile'
              examples:
                response:
                  value:
                    address: 814 West Chapman Avenue
                    address2: ''
                    city: Orange
                    company: SendGrid
                    country: US
                    first_name: Example
                    last_name: User
                    phone: 555-555-5555
                    state: CA
                    website: http://www.sendgrid.com
                    zip: '92868'
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    errors:
                    - field: null
                      message: authorization required
  /v3/user/username:
    get:
      operationId: ListUsername
      summary: Retrieve your username
      tags:
      - Users API
      description: '**This endpoint allows you to retrieve your current account username.**'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  username:
                    type: string
                    description: Your account username.
                  user_id:
                    type: integer
                    description: The user ID for your account.
                required:
                - username
                - user_id
              examples:
                response:
                  value:
                    username: test_username
                    user_id: 1
    put:
      operationId: UpdateUsername
      summary: Update your username
      tags:
      - Users API
      description: '**This endpoint allows you to update the username for your account.**'
      parameters:
      - $ref: '#/components/parameters/OnBehalfOf'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
                  description: The new username you would like to use for your account.
              example:
                username: test_username
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  username:
                    type: string
                    description: The current username on file for your account.
                required:
                - username
              examples:
                response:
                  value:
                    username: test_username
components:
  schemas:
    Type:
      type: string
      enum:
      - free
      - paid
    UserProfile:
      title: 'User: Profile'
      type: object
      properties:
        address:
          type: string
          description: The street address for this user profile.
        address2:
          type: string
          description: An optional second line for the street address of this user profile.
        city:
          type: string
          description: The city for the user profile.
        company:
          type: string
          description: That company that this user profile is associated with.
        country:
          type: string
          description: Th country of this user profile.
        first_name:
          type: string
          description: The first name of the user.
        last_name:
          type: string
          description: The last name of the user.
        phone:
          type: string
          description: The phone number for the user.
        state:
          type: string
          description: The state for this user.
        website:
          type: string
          description: The website associated with this user.
        zip:
          type: string
          description: The zip code for this user.
      example:
        address: 1451 Larimer Street, 3rd floor
        address2: ''
        city: Denver, CO
        company: SendGrid
        country: US
        first_name: Matthew
        last_name: Bernier
        phone: '7208788003'
        state: CO
        website: http://sendgrid.com
        zip: '80202'
    ErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              message:
                type: string
                description: An error message.
              field:
                description: When applicable, this property value will be the field that generated the error.
                nullable: true
                type: string
              help:
                type: object
                description: When applicable, this property value will be helper text or a link to documentation to help you troubleshoot the error.
        id:
          type: string
          description: When applicable, this property value will be an error ID.
      example:
        errors:
        - field: field_name
          message: error message
  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
  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