Keap Users API

openapi: 3.1.0
info:
  title: Keap Users API
  description: Keap Public API Documentation
  termsOfService: https://www.thryv.com/terms-of-use
  contact:
    name: Keap
    url: https://developer.keap.com/get-support
    email: api.keap@thryv.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  version: v2
servers:
- url: https://api.infusionsoft.com/crm
tags:
- name: Users
paths:
  /rest/v2/users/{user_id}:
    get:
      tags:
      - Users
      summary: Get User
      description: Retrieves a specific User
      operationId: getUserById
      parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: Method Not Implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: Method Not Allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
    patch:
      tags:
      - Users
      summary: Update User
      description: Updates information on a specific User
      operationId: updateUser
      parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: string
      - name: update_mask
        in: query
        description: An optional list of properties to be updated. If set, only the provided properties
          will be updated and others will be skipped.
        required: false
        schema:
          type: array
          items:
            type: string
            enum:
            - address
            - company_name
            - email_address
            - family_name
            - fax_numbers
            - given_name
            - job_title
            - phone_numbers
            - time_zone
            - website
          uniqueItems: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUserRequest'
        required: true
      responses:
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: Method Not Implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: Method Not Allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
  /rest/v2/users:
    get:
      tags:
      - Users
      summary: List Users
      description: Retrieves a list of users
      operationId: listPaginatedUsers
      parameters:
      - name: filter
        in: query
        description: 'Filter to apply, allowed fields are:

          - (String) `email`

          - (String) `given_name`

          - (Boolean) `include_inactive`

          - (Boolean) `include_partners`

          - (Set[String]) `user_ids`


          You will need to apply the `==` operator to check the equality of one of the filters with your
          searched

          word, in the encoded form `%3D%3D`.

          For the filters listed above, here are some examples:

          - `filter=given_name%3D%3DMary`

          - `filter=user_ids%3D%3D123%3Bgiven_name%3D%3DSmith`

          '
        required: false
        schema:
          type: string
      - name: page_token
        in: query
        description: Page token
        required: false
        schema:
          type: string
      - name: order_by
        in: query
        description: 'Attribute and direction to order items.

          One of the following fields:

          - `create_time`

          - `email`

          - `name` (sorts by family name / last name; uses User ID as tiebreaker for stable pagination)


          One of the following directions:

          - `asc`

          - `desc`'
        required: false
        schema:
          type: string
      - name: page_size
        in: query
        description: Total number of items to return per page
        required: false
        schema:
          type: integer
          format: int32
          maximum: 100
          minimum: 1
        example: 10
      responses:
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: Method Not Implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: Method Not Allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListUsersPaginatedResponse'
  /rest/v2/users/{user_id}/signature:
    get:
      tags:
      - Users
      summary: Get User email signature
      description: Retrieves a HTML snippet that contains the user's email signature.
      operationId: getUserSignature
      parameters:
      - name: user_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: Method Not Implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: Method Not Allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: string
  /rest/v2/oauth/connect/userinfo:
    get:
      tags:
      - Users
      summary: Retrieve User Info
      description: Retrieves information for the current authenticated end-user, as outlined by the [OpenID
        Connect specification](http://openid.net/specs/openid-connect-core-1_0.html#UserInfo).
      operationId: getUserInfo
      responses:
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: Method Not Implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: Method Not Allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetUserInfoResponse'
components:
  schemas:
    Address:
      type: object
      properties:
        country:
          type: string
          deprecated: true
          description: Deprecated. The long-name descriptive version of the Country Code. Please use 'country_code'
            for POST/PATCH operations. Maximum length is 100 characters.
          example: United States of America
        line1:
          type: string
          description: Street address line 1. Maximum length is 75 characters for the BILLING address
            and 100 characters for the SHIPPING and OTHER addresses.
          example: 123
        line2:
          type: string
          description: Street address line 2. Maximum length is 75 characters for the BILLING address
            and 100 characters for the SHIPPING and OTHER addresses.
          example: Suite 100
        locality:
          type: string
          description: The municipality to which the address belongs. Maximum length is 50 characters
            for the BILLING address and 100 characters for the SHIPPING and OTHER addresses.
          example: Phoenix
        region:
          type: string
          deprecated: true
          description: The long-name descriptive version of the Region Code. Please use 'region_code'
            for POST/PATCH operations. Maximum length is 50 characters.
          example: Arizona
        field:
          type: string
          description: Address type field
          enum:
          - ADDRESS_FIELD_UNSPECIFIED
          - BILLING
          - SHIPPING
          - OTHER
          example: BILLING
        country_code:
          type: string
          description: An ISO 3166-2 Country Code (https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3)
          example: USA
        postal_code:
          type: string
          description: Postal or ZIP code. Maximum length is 15 characters for the BILLING and OTHER addresses
            and 20 characters for the SHIPPING address.
          example: 85001
        region_code:
          type: string
          description: An ISO 3166-2 Province Code, such as one of the US States (https://en.wikipedia.org/wiki/ISO_3166-2:US)
          example: US-AZ
        zip_code:
          type: string
          description: ZIP code (US). Maximum length is 15 characters for the BILLING and OTHER addresses
            and 20 characters for the SHIPPING address.
          example: 85001
        zip_four:
          type: string
          description: ZIP+4 extension. Maximum length is 10 characters.
          example: 1234
    EmailAddress:
      type: object
      properties:
        email:
          type: string
          description: Email address. Maximum length is 75 characters for EMAIL1 and 100 characters for
            EMAIL2 and EMAIL3.
          example: john.smith@example.com
        field:
          type: string
          description: Email address slot
          enum:
          - EMAIL_FIELD_UNSPECIFIED
          - EMAIL1
          - EMAIL2
          - EMAIL3
          example: EMAIL1
        opt_in_reason:
          type: string
          description: Reason for opting in
          example: Subscribed via website form
        is_opt_in:
          type: boolean
        email_opt_status:
          type: string
          enum:
          - UNENGAGED_MARKETABLE
          - SINGLE_OPT_IN
          - DOUBLE_OPT_IN
          - CONFIRMED
          - UNENGAGED_NON_MARKETABLE
          - NON_MARKETABLE
          - LOCKDOWN
          - BOUNCE
          - HARD_BOUNCE
          - MANUAL
          - ADMIN
          - SYSTEM
          - LIST_UNSUBSCRIBE
          - FEEDBACK
          - SPAM
          - INVALID
          - DEACTIVATED
    EmailAddressRequest:
      type: object
      properties:
        email:
          type: string
          description: Email address. Maximum length is 75 characters for EMAIL1 and 100 characters for
            EMAIL2 and EMAIL3.
          example: john.smith@example.com
        field:
          type: string
          description: Email address slot
          enum:
          - EMAIL_FIELD_UNSPECIFIED
          - EMAIL1
          - EMAIL2
          - EMAIL3
          example: EMAIL1
        opt_in_reason:
          type: string
          description: Reason for opting in
          example: Subscribed via website form
    Error:
      type: object
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
        status:
          type: string
        details:
          type: array
          items:
            $ref: '#/components/schemas/ErrorDetails'
    ErrorDetails:
      type: object
      properties:
        domain:
          type: string
        resource:
          type: string
    FaxNumber:
      type: object
      properties:
        number:
          type: string
          description: Fax number
          example: 5551234568
        type:
          type: string
          description: Fax type
          example: Work
        field:
          type: string
          description: Fax number slot
          enum:
          - FAX_NUMBER_FIELD_UNSPECIFIED
          - FAX1
          - FAX2
          example: FAX1
    GetUserInfoResponse:
      type: object
      description: User information response
      properties:
        email:
          type: string
          description: The user's email address
          example: john.smith@example.com
        sub:
          type: string
          description: The subject identifier
          example: 12345
        id:
          type: string
          description: The global user identifier
          example: 123456
        keap_id:
          type: string
          description: The keap user identifier
          example: john.smith@example.com
        family_name:
          type: string
          description: The user's last name
          example: Smith
        given_name:
          type: string
          description: The user's first name
          example: John
        middle_name:
          type: string
          description: The user's middle name
          example: Robert
        preferred_name:
          type: string
          description: The user's preferred name
          example: Johnny
        is_admin:
          type: boolean
          description: Whether the user is an admin
          example: true
        tenant_id:
          type: string
          description: The tenant ID the user belongs to
          example: xyz789
    ListUsersPaginatedResponse:
      type: object
      description: Paginated response containing a list of users
      properties:
        users:
          type: array
          description: List of users
          items:
            $ref: '#/components/schemas/User'
        next_page_token:
          type: string
    PhoneNumber:
      type: object
      properties:
        extension:
          type: string
          description: Phone extension
          example: 101
        number:
          type: string
          description: Phone number. Maximum length is 40 characters for PHONE1-PHONE3 and 20 characters
            for PHONE4-PHONE5.
          example: 5551234567
        type:
          type: string
          description: Phone type
          example: Work
        field:
          type: string
          description: Phone number slot
          enum:
          - PHONE_NUMBER_FIELD_UNSPECIFIED
          - PHONE1
          - PHONE2
          - PHONE3
          - PHONE4
          - PHONE5
          example: PHONE1
        number_e164:
          type: string
          description: Phone number in E.164 format
          example: '+15551234567'
    SocialAccount:
      type: object
      properties:
        name:
          type: string
          description: Social account username or handle. Maximum length is 255 characters.
          example: '@thryv'
        type:
          type: string
          description: Social account type
          enum:
          - SOCIAL_ACCOUNT_TYPE_UNSPECIFIED
          - FACEBOOK
          - LINKED_IN
          - TWITTER
          - INSTAGRAM
          - SNAPCHAT
          - YOUTUBE
          - PINTEREST
          example: FACEBOOK
      required:
      - type
    UpdateUserRequest:
      type: object
      description: user
      properties:
        address:
          $ref: '#/components/schemas/Address'
          description: The user's address
        title:
          type: string
          description: The user's job title
          example: Sales Manager
        website:
          type: string
          description: The user's website URL
          example: https://example.com
        company_name:
          type: string
          description: The user's company name
          example: Acme Corp
        email_address:
          $ref: '#/components/schemas/EmailAddressRequest'
          description: The user's email address
        family_name:
          type: string
          description: The user's last name
          example: Smith
        fax_numbers:
          type: array
          description: List of user's fax numbers
          items:
            $ref: '#/components/schemas/FaxNumber'
        given_name:
          type: string
          description: The user's first name
          example: John
        phone_numbers:
          type: array
          description: List of user's phone numbers
          items:
            $ref: '#/components/schemas/PhoneNumber'
        time_zone:
          type: string
          description: The user's timezone in IANA format
          example: America/New_York
    User:
      type: object
      description: A user in the system
      properties:
        address:
          $ref: '#/components/schemas/Address'
          description: The user's address
        title:
          type: string
          description: The user's job title
          example: Sales Manager
        website:
          type: string
          description: The user's website URL
          example: https://example.com
        partner:
          type: boolean
          description: Whether the user is a partner
          example: false
        admin:
          type: boolean
          description: Whether the user is an admin
          example: true
        status:
          type: string
          description: The user's status
          enum:
          - ACTIVE
          - INVITED
          - INACTIVE
          - NOT_A_USER
          example: ACTIVE
        id:
          type: string
          description: The unique identifier of the user
          example: 123
        global_user_id:
          type: string
          description: The global user identifier across tenants
          example: usr_abc123
        keap_id:
          type: string
          description: The Keap ID of the user
          example: 456
        given_name:
          type: string
          description: The user's first name
          example: John
        family_name:
          type: string
          description: The user's last name
          example: Smith
        middle_name:
          type: string
          description: The user's middle name
          example: Edward
        nickname:
          type: string
          description: The user's nickname or preferred name
          example: Tony
        spouse_name:
          type: string
          description: The name of the user's spouse
          example: Mia
        suffix:
          type: string
          description: The user's name suffix
          example: Jr.
        phone_numbers:
          type: array
          description: List of user's phone numbers
          items:
            $ref: '#/components/schemas/PhoneNumber'
        fax_numbers:
          type: array
          description: List of user's fax numbers
          items:
            $ref: '#/components/schemas/FaxNumber'
        email_addresses:
          type: array
          description: List of user's email addresses
          items:
            $ref: '#/components/schemas/EmailAddress'
        social_accounts:
          type: array
          description: List of user's social media accounts
          items:
            $ref: '#/components/schemas/SocialAccount'
        company_name:
          type: string
          description: The user's company name
          example: Acme Corp
        created_by:
          type: integer
          format: int64
          description: ID of the user who created this user
          example: 1
        create_time:
          type: string
          format: date-time
          description: When the user was created, in ISO-8601 format
          example: '2024-05-21T14:30:00Z'
        updated_by:
          type: integer
          format: int64
          description: ID of the user who last updated this user
          example: 1
        update_time:
          type: string
          format: date-time
          description: When the user was last updated, in ISO-8601 format
          example: '2024-05-21T15:00:00Z'
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://accounts.infusionsoft.com/app/oauth/authorize
          tokenUrl: https://api.infusionsoft.com/token
          scopes: {}
security:
- oauth2: []