JustCall User Groups API

openapi: 3.2.0
info:
  title: JustCall User Groups API
  description: 'REST APIs

    The REST APIs provide programmatic access to read and write JustCall data. Create a new contact, read them, add notes, and more'
  version: '2'
  contact: {}
servers:
- url: https://api.justcall.io
tags:
- name: User Groups
paths:
  /v2.1/user_groups:
    get:
      operationId: users_groups_list_v21
      summary: List all user groups
      description: Utilize this endpoint to fetch a list of all the user groups added to your JustCall account and to filter a set of user groups via the query parameters.
      parameters:
      - name: per_page
        required: false
        in: query
        description: Number of user group records to be fetched per page. Default value is 50 and maximum value is 100.
        schema:
          example: 10
          type: number
      - name: page
        required: false
        in: query
        description: Page number for which user group records are to be fetched. Default value is 0.
        schema:
          example: 1
          type: number
      - name: order
        required: false
        in: query
        description: Order in which the user group records should appear based on the user group Id. Default value is desc.
        schema:
          example: desc
          type: string
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListUserGroupsResponseDto'
        '400':
          description: Failed due to bad request params.
        '401':
          description: Failed due to unauthorized access.
        '403':
          description: This error occurred when there is some validation error or you don't have access to that resource.
        '404':
          description: Requested resource may not exist.
        '500':
          description: This is due to internal server error reason, in this case please contact our support team with attached uuid.
      tags:
      - User Groups
      security:
      - AccessToken: []
    post:
      operationId: users_group_create_v21
      summary: Create a user group
      description: Create a user group using this endpoint by sending the group name, extension and member ids.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserGroupBodyDto'
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserGroup'
        '400':
          description: Failed due to bad request params.
        '401':
          description: Failed due to unauthorized access.
        '403':
          description: This error occurred when there is some validation error or you don't have access to that resource.
        '404':
          description: Requested resource may not exist.
        '500':
          description: This is due to internal server error reason, in this case please contact our support team with attached uuid.
      tags:
      - User Groups
      security:
      - AccessToken: []
  /v2.1/user_groups/{id}:
    get:
      operationId: users_group_get_v21
      summary: Get a user group
      description: Get data for a specific user group using this endpoint by sending its id.
      parameters:
      - name: id
        required: true
        in: path
        description: Unique id of the user group as generated by JustCall. User group id can be accessed using <a href="https://developer.justcall.io/reference/users_groups_list_v21">List all user groups API</a>.
        schema:
          type: number
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserGroup'
        '400':
          description: Failed due to bad request params.
        '401':
          description: Failed due to unauthorized access.
        '403':
          description: This error occurred when there is some validation error or you don't have access to that resource.
        '404':
          description: Requested resource may not exist.
        '500':
          description: This is due to internal server error reason, in this case please contact our support team with attached uuid.
      tags:
      - User Groups
      security:
      - AccessToken: []
    put:
      operationId: users_group_update_v21
      summary: Update a user group
      description: Update a user group using this endpoint by sending the user group id and the group name, extension and member ids.
      parameters:
      - name: id
        required: true
        in: path
        description: Unique id of the user group as generated by JustCall. User group id can be accessed using <a href="https://developer.justcall.io/reference/users_groups_list_v21">List all user groups API</a>.
        schema:
          type: number
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUserGroupReqBodyDto'
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserGroup'
        '400':
          description: Failed due to bad request params.
        '401':
          description: Failed due to unauthorized access.
        '403':
          description: This error occurred when there is some validation error or you don't have access to that resource.
        '404':
          description: Requested resource may not exist.
        '500':
          description: This is due to internal server error reason, in this case please contact our support team with attached uuid.
      tags:
      - User Groups
      security:
      - AccessToken: []
    delete:
      operationId: users_group_delete_v21
      summary: Delete a user group
      description: Delete a user group using this endpoint by sending the user group id.
      parameters:
      - name: id
        required: true
        in: path
        description: Unique id of the user group as generated by JustCall. User group id can be accessed using <a href="https://developer.justcall.io/reference/users_groups_list_v21">List all user groups API</a>.
        schema:
          type: number
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteUserGroupsResponseDto'
        '400':
          description: Failed due to bad request params.
        '401':
          description: Failed due to unauthorized access.
        '403':
          description: This error occurred when there is some validation error or you don't have access to that resource.
        '404':
          description: Requested resource may not exist.
        '500':
          description: This is due to internal server error reason, in this case please contact our support team with attached uuid.
      tags:
      - User Groups
      security:
      - AccessToken: []
  /v2.1/user_groups/{id}/members:
    put:
      operationId: users_group_add_members_v21
      summary: Add members to a user group
      description: Add members to a user group using this endpoint by sending the user group id and the member ids.
      parameters:
      - name: id
        required: true
        in: path
        description: Unique id of the user group as generated by JustCall. User group id can be accessed using <a href="https://developer.justcall.io/reference/users_groups_list_v21">List all user groups API</a>.
        schema:
          type: number
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUserGroupMembersReqBodyDto'
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserGroup'
        '400':
          description: Failed due to bad request params.
        '401':
          description: Failed due to unauthorized access.
        '403':
          description: This error occurred when there is some validation error or you don't have access to that resource.
        '404':
          description: Requested resource may not exist.
        '500':
          description: This is due to internal server error reason, in this case please contact our support team with attached uuid.
      tags:
      - User Groups
      security:
      - AccessToken: []
    delete:
      operationId: users_group_remove_members_v21
      summary: Remove members from a user group
      description: Remove a member from a user group using this endpoint by sending the user group id and the member ids.
      parameters:
      - name: id
        required: true
        in: path
        description: Unique id of the user group as generated by JustCall. User group id can be accessed using <a href="https://developer.justcall.io/reference/users_groups_list_v21">List all user groups API</a>.
        schema:
          type: number
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUserGroupMembersReqBodyDto'
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserGroup'
        '400':
          description: Failed due to bad request params.
        '401':
          description: Failed due to unauthorized access.
        '403':
          description: This error occurred when there is some validation error or you don't have access to that resource.
        '404':
          description: Requested resource may not exist.
        '500':
          description: This is due to internal server error reason, in this case please contact our support team with attached uuid.
      tags:
      - User Groups
      security:
      - AccessToken: []
components:
  schemas:
    UpdateUserGroupReqBodyDto:
      type: object
      properties:
        group_name:
          type: string
          description: Name of the user group. Maximum length is 30 characters. Must be unique and cannot be empty.
          example: Sales Team
        group_extension:
          type: number
          description: Extension number for call routing. Must be unique across and cannot be empty.
          example: '1011'
        member_ids:
          description: User IDs to add as initial members. If omitted, group is created empty. Member IDs can be accessed using <a href="https://developer.justcall.io/reference/users_list_v21">List all users API</a>.
          example:
          - 123456
          - 789012
          - 345678
          type: array
          items:
            type: number
    DeleteUserGroupsResponseDto:
      type: object
      properties:
        status:
          type: string
          description: Status of the API request.
          example: success
          enum:
          - failed
          - success
    CreateUserGroupBodyDto:
      type: object
      properties:
        group_name:
          type: string
          description: Name of the user group. Maximum length is 30 characters. Must be unique and cannot be empty.
          example: Sales Team
        group_extension:
          type: number
          description: Extension number for call routing. Must be unique across and cannot be empty.
          example: '1011'
        member_ids:
          description: User IDs to add as initial members. If omitted, group is created empty. Member IDs can be accessed using <a href="https://developer.justcall.io/reference/users_list_v21">List all users API</a>.
          example:
          - 123456
          - 789012
          - 345678
          type: array
          items:
            type: number
      required:
      - group_name
      - group_extension
    ListUserGroupsResponseDto:
      type: object
      properties:
        status:
          type: string
          default: success
          description: 'Displays the status of the API request : ‘success’ for successful request; error message with description of error for failed request.'
        count:
          type: number
          default: 100
          description: Number of user group records present on the current page.
        total_count:
          type: number
          default: 20
          description: Total number of user group records fetched by the API query.
        current_page:
          type: number
          default: 2
          description: Number of the current page.
        per_page:
          type: number
          default: 50
          description: Maximum number of user group records appearing per page.
        next_page_link:
          type: string
          default: https://api.justcall.io/v2.1/user_groups?page=3
          description: Link to the next page containing user group records.
        prev_page_link:
          type: string
          default: https://api.justcall.io/v2.1/user_groups?page=1
          description: Link to the next page containing user group records.
        data:
          description: Array of JC User Group objects
          type: array
          items:
            $ref: '#/components/schemas/UserGroup'
    UserGroupMembers:
      type: object
      properties:
        id:
          type: number
          default: 2
          description: id of the member
        name:
          type: string
          default: John Doe
          description: name of the member
        email:
          type: string
          default: john.doe@example.co
          description: email of the member
        role:
          type: string
          default: Admin
          description: Role of the member
        timezone:
          type: string
          default: America/New_York
          description: timezone of the member
        extension:
          type: number
          default: 101
          description: extension of the member
    UpdateUserGroupMembersReqBodyDto:
      type: object
      properties:
        member_ids:
          description: Array of user group member IDs to be updated. Member IDs can be accessed using <a href="https://developer.justcall.io/reference/users_list_v21">List all users API</a>.
          example:
          - 123456
          - 789012
          - 345678
          type: array
          items:
            type: number
      required:
      - member_ids
    UserGroup:
      type: object
      properties:
        id:
          type: number
          default: 1234
          description: Unique Id of the user group (team) as generated by JustCall.
        group_name:
          type: string
          default: Sales Team
          description: Name of the user group.
        group_extension:
          type: string
          default: 1011
          description: Extension of the user group.
        updated_on:
          type: string
          default: '2025-01-01 10:01:01'
          description: Date and time of the last update to the user group in UTC timezone.
        total_members:
          type: number
          default: 1
          description: Count of total members added to the user group.
        members:
          type: array
          items:
            $ref: '#/components/schemas/UserGroupMembers'
  securitySchemes:
    AccessToken:
      type: apiKey
      in: header
      name: Authorization
      description: 'The API key can be put in the Authorization header. i.e Authorization: api_key:api_secret. If you use cURL, specify -u “api_key:api_secret”'
x-provenance:
  method: harvested
  publisher: JustCall
  source: https://api.justcall.io/v2/api-docs
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)