---
updatedAt: 2026-05-11T06:52:42.000Z
agentTools:
  projectIndex: https://platform.simpplr.com/llms.txt
---

# List people with search or filter

You can filter by standard fields (like `department`, `division`, `title`) or custom fields  (ending with `__c`, like `team__c`).

Example request payload showing filter applied on a standard field (department) and a custom field (team__c): The query finds users in one of the two Marketing department teams.
```
{
  "pageSize": 10,
  "department": ["Marketing"],
  "team__c": ["Branding Brainiacs", "Ad-Vengers"]
}
```


# OpenAPI definition

````json
{
  "openapi": "3.0.2",
  "info": {
    "version": "1.0.0",
    "title": "Simpplr User API Documentation",
    "description": ""
  },
  "x-proxy-enabled": true,
  "tags": [
    {
      "name": "People",
      "description": "Everything about People"
    }
  ],
  "servers": [
    {
      "url": "https://{endpoint}/v1",
      "variables": {
        "env": {
          "default": "app"
        },
        "endpoint": {
          "default": "platform.app.simpplr.com"
        }
      }
    }
  ],
  "paths": {
    "/identity/people/list": {
      "post": {
        "operationId": "listPeople",
        "tags": [
          "People"
        ],
        "summary": "List people with search or filter",
        "description": "You can filter by standard fields (like `department`, `division`, `title`) or custom fields  (ending with `__c`, like `team__c`).\n\nExample request payload showing filter applied on a standard field (department) and a custom field (team__c): The query finds users in one of the two Marketing department teams.\n```\n{\n  \"pageSize\": 10,\n  \"department\": [\"Marketing\"],\n  \"team__c\": [\"Branding Brainiacs\", \"Ad-Vengers\"]\n}\n```\n",
        "requestBody": {
          "description": "Get people list",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "description": "Request schema for getting a list of people with filtering and pagination options.\n",
                "properties": {
                  "sortBy": {
                    "type": "string",
                    "description": "List of fields to sort by. If sortBy is not provided, the default sort will be by userId.",
                    "example": "firstName"
                  },
                  "sortOrder": {
                    "type": "string",
                    "description": "Order in which to sort the results. Valid values are ASC (ascending) or DESC (descending).",
                    "example": "DESC"
                  },
                  "pageSize": {
                    "type": "integer",
                    "description": "Number of items per page. Default value is 10.",
                    "maximum": 200,
                    "example": 16
                  },
                  "pageToken": {
                    "type": "string",
                    "description": "A cursor to use in pagination. Should be nextPageToken received in previous page response."
                  },
                  "includeTotal": {
                    "type": "boolean",
                    "description": "Whether to include the total user count in the response",
                    "default": false,
                    "example": true
                  },
                  "q": {
                    "type": "string",
                    "description": "Query string for searching users (supports first name and last name).",
                    "example": "abc"
                  },
                  "timezone": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "List of timezones to filter by.",
                    "example": [
                      "Asia/Kolkata"
                    ]
                  },
                  "title": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "List of titles to filter by.",
                    "example": [
                      "Software Developer"
                    ]
                  },
                  "userType": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "List of user types to filter by.",
                    "example": [
                      "Contractor"
                    ]
                  },
                  "division": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "List of divisions to filter by.",
                    "example": [
                      "Developer"
                    ]
                  },
                  "department": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "List of departments to filter by.",
                    "example": [
                      "Engineering"
                    ]
                  },
                  "businessUnit": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "List of business units to filter by.",
                    "example": [
                      "Tata"
                    ]
                  },
                  "companyName": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "List of company names to filter by.",
                    "example": [
                      "simpplr"
                    ]
                  },
                  "startDate": {
                    "oneOf": [
                      {
                        "type": "object",
                        "properties": {
                          "start": {
                            "type": "string",
                            "format": "date",
                            "description": "Start date for start date filter",
                            "example": "2024-01-01"
                          },
                          "end": {
                            "type": "string",
                            "format": "date",
                            "description": "End date for start date filter",
                            "example": "2024-12-31"
                          }
                        },
                        "required": [
                          "start",
                          "end"
                        ]
                      },
                      {
                        "type": "string",
                        "pattern": "^(\\d+)(d|m|M|w|y)$",
                        "description": "Relative date filter for start date (e.g., \"20d\" for 20 days, \"2m\" for 2 months, \"1M\" for 1 month, \"3w\" for 3 weeks, \"1y\" for 1 year)",
                        "example": "20d"
                      }
                    ],
                    "description": "Filter by start date range. Can be either an object with start/end dates or a relative date string."
                  },
                  "workAnniversary": {
                    "oneOf": [
                      {
                        "type": "object",
                        "properties": {
                          "start": {
                            "type": "string",
                            "format": "date",
                            "description": "Start date for work anniversary filter",
                            "example": "2024-01-01"
                          },
                          "end": {
                            "type": "string",
                            "format": "date",
                            "description": "End date for work anniversary filter",
                            "example": "2024-12-31"
                          }
                        },
                        "required": [
                          "start",
                          "end"
                        ]
                      },
                      {
                        "type": "string",
                        "pattern": "^(\\d+)(d|m|M|w|y)$",
                        "description": "Relative date filter for work anniversary (e.g., \"20d\" for 20 days, \"2m\" for 2 months, \"1M\" for 1 month, \"3w\" for 3 weeks, \"1y\" for 1 year)",
                        "example": "20d"
                      }
                    ],
                    "description": "Filter by work anniversary date range. Can be either an object with start/end dates or a relative date string. The difference between start and end dates cannot be more than 90 days."
                  },
                  "birthAnniversary": {
                    "oneOf": [
                      {
                        "type": "object",
                        "properties": {
                          "start": {
                            "type": "string",
                            "format": "date",
                            "description": "Start date for birth anniversary filter",
                            "example": "2024-01-01"
                          },
                          "end": {
                            "type": "string",
                            "format": "date",
                            "description": "End date for birth anniversary filter",
                            "example": "2024-12-31"
                          }
                        },
                        "required": [
                          "start",
                          "end"
                        ]
                      },
                      {
                        "type": "string",
                        "pattern": "^(\\d+)(d|m|M|w|y)$",
                        "description": "Relative date filter for birth anniversary (e.g., \"60d\" for 60 days, \"2m\" for 2 months, \"1M\" for 1 month, \"3w\" for 3 weeks, \"1y\" for 1 year)",
                        "example": "60d"
                      }
                    ],
                    "description": "Filter by birth anniversary date range. Can be either an object with start/end dates or a relative date string. The difference between start and end dates cannot be more than 90 days."
                  },
                  "state": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "List of states to filter by.",
                    "example": [
                      "New Delhi",
                      "Uttarakhand"
                    ]
                  },
                  "city": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "List of cities to filter by.",
                    "example": [
                      "Delhi",
                      "Mumbai"
                    ]
                  },
                  "country": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "List of countries to filter by.",
                    "example": [
                      "India",
                      "USA"
                    ]
                  },
                  "location": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "city": {
                          "type": "string",
                          "description": "City name",
                          "example": "Delhi"
                        },
                        "state": {
                          "type": "string",
                          "description": "State name",
                          "example": "Maharashtra"
                        },
                        "country": {
                          "type": "string",
                          "description": "Country name",
                          "example": "India"
                        }
                      },
                      "required": [
                        "city"
                      ]
                    },
                    "description": "List of location objects.\n\nOne of the entries should match for user record to appear in response.\n\nAtleast one of city, state & country should be in an entry.\n\nWith in an entry all given props (city, state, country) should match what set for a user.\n",
                    "example": [
                      {
                        "city": "Delhi"
                      },
                      {
                        "city": "Amaravati",
                        "state": "Maharashtra"
                      },
                      {
                        "city": "Amaravati",
                        "state": "Maharashtra",
                        "country": "India"
                      }
                    ]
                  },
                  "customField": {
                    "type": "array",
                    "description": "Filter property name will be UUID or string endig with `__c`.\n\nValue passed must be an array of strings.\n",
                    "items": {
                      "type": "string",
                      "example": [
                        "value1",
                        "value2"
                      ]
                    }
                  }
                }
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "description": "Response status",
                      "example": "success"
                    },
                    "message": {
                      "type": "string",
                      "description": "Success message",
                      "example": "EC users fetched successfully"
                    },
                    "result": {
                      "type": "object",
                      "properties": {
                        "items": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "description": "Unique identifier for the user",
                                "example": "85dcc783-6afd-4871-9ad6-637abb29841b"
                              },
                              "username": {
                                "type": "string",
                                "description": "User's username/email",
                                "example": "ankur.gupta+test@simpplr.com"
                              },
                              "status": {
                                "type": "string",
                                "description": "User's status",
                                "example": "Active"
                              },
                              "firstName": {
                                "type": "string",
                                "description": "User's first name",
                                "example": "Am Edit User"
                              },
                              "lastName": {
                                "type": "string",
                                "description": "User's last name",
                                "example": "Role Testing"
                              },
                              "pronouns": {
                                "type": "string",
                                "description": "User's preferred pronouns",
                                "example": "he_him_his"
                              },
                              "pronunciationUrl": {
                                "type": "string",
                                "description": "URL to pronunciation audio",
                                "nullable": true,
                                "example": null
                              },
                              "extn": {
                                "type": "string",
                                "description": "Phone extension",
                                "nullable": true,
                                "example": null
                              },
                              "photo": {
                                "type": "string",
                                "description": "Profile photo path",
                                "example": "/content/o/286d4be1-0232-462e-ac01-4049e4a53dae"
                              },
                              "coverImage": {
                                "type": "string",
                                "description": "Cover image path",
                                "example": "/content/o/4702bd35-8c54-411f-8297-6f6be3001e96"
                              },
                              "createdOn": {
                                "type": "string",
                                "format": "date-time",
                                "description": "User creation date",
                                "example": "2024-10-16T02:16:38.763Z"
                              },
                              "modifiedOn": {
                                "type": "string",
                                "format": "date-time",
                                "description": "User last modified date",
                                "example": "2025-10-14T09:10:08.075Z"
                              },
                              "mobile": {
                                "type": "string",
                                "description": "User's mobile number",
                                "nullable": true,
                                "example": null
                              },
                              "phone": {
                                "type": "string",
                                "description": "User's phone number",
                                "nullable": true,
                                "example": null
                              },
                              "about": {
                                "type": "string",
                                "description": "JSON string containing user's about information",
                                "example": "{\"type\":\"tiptap\",\"value\":{\"type\":\"doc\",\"content\":[{\"type\":\"paragraph\",\"attrs\":{\"textAlign\":\"left\"},\"content\":[{\"type\":\"text\",\"text\":\"Am Edit User Role Testing hasnt added any about text\"}]}]}}"
                              },
                              "birthDayDay": {
                                "type": "string",
                                "description": "Birth day",
                                "example": "08"
                              },
                              "birthDayMonth": {
                                "type": "string",
                                "description": "Birth month",
                                "example": "08"
                              },
                              "linkedinUrl": {
                                "type": "string",
                                "description": "LinkedIn profile URL",
                                "nullable": true,
                                "example": null
                              },
                              "twitterUrl": {
                                "type": "string",
                                "description": "Twitter profile URL",
                                "nullable": true,
                                "example": null
                              },
                              "facebookUrl": {
                                "type": "string",
                                "description": "Facebook profile URL",
                                "nullable": true,
                                "example": null
                              },
                              "youtubeUrl": {
                                "type": "string",
                                "description": "YouTube channel URL",
                                "nullable": true,
                                "example": null
                              },
                              "instagramUrl": {
                                "type": "string",
                                "description": "Instagram profile URL",
                                "nullable": true,
                                "example": null
                              },
                              "addressLine2": {
                                "type": "string",
                                "description": "Address line 2",
                                "nullable": true,
                                "example": null
                              },
                              "city": {
                                "type": "string",
                                "description": "User's city",
                                "example": "Delhi"
                              },
                              "state": {
                                "type": "string",
                                "description": "User's state",
                                "example": "Delhi"
                              },
                              "postalCode": {
                                "type": "string",
                                "description": "Postal/ZIP code",
                                "nullable": true,
                                "example": null
                              },
                              "country": {
                                "type": "string",
                                "description": "User's country",
                                "example": "India"
                              },
                              "title": {
                                "type": "string",
                                "description": "User's job title",
                                "nullable": true,
                                "example": null
                              },
                              "businessUnit": {
                                "type": "string",
                                "description": "Business unit",
                                "nullable": true,
                                "example": null
                              },
                              "companyName": {
                                "type": "string",
                                "description": "Company name",
                                "example": "Simpplr"
                              },
                              "startDate": {
                                "type": "string",
                                "format": "date",
                                "description": "Start date",
                                "example": "2025-10-03"
                              },
                              "userType": {
                                "type": "string",
                                "description": "User type",
                                "nullable": true,
                                "example": null
                              },
                              "peopleCategory": {
                                "type": "string",
                                "description": "People category",
                                "example": "Country-US"
                              },
                              "segmentId": {
                                "type": "string",
                                "description": "Segment ID",
                                "example": "ebeb0722-a38b-47b7-aabe-c867d9567f33"
                              },
                              "timezone": {
                                "type": "string",
                                "description": "User's timezone",
                                "example": "America/Los_Angeles"
                              },
                              "locale": {
                                "type": "string",
                                "description": "User's locale",
                                "example": "en-US"
                              },
                              "managerId": {
                                "type": "string",
                                "description": "Manager ID",
                                "nullable": true,
                                "example": null
                              },
                              "assistantId": {
                                "type": "string",
                                "description": "Assistant ID",
                                "nullable": true,
                                "example": "84c542ac-6fdf-4d37-8788-b0c4546eb9fa"
                              }
                            }
                          }
                        },
                        "total": {
                          "type": "integer",
                          "description": "Total number of users matching the criteria (only included when includeTotal=true in request)",
                          "example": 2
                        },
                        "pageToken": {
                          "type": "number",
                          "description": "Next page token",
                          "example": 1
                        }
                      }
                    },
                    "responseTimeStamp": {
                      "type": "integer",
                      "description": "Response timestamp",
                      "example": 1761108072626
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request - Invalid Input",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "description": "Response status",
                      "example": "error"
                    },
                    "message": {
                      "type": "string",
                      "description": "Error message",
                      "example": "The input provided is invalid."
                    },
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "message": {
                            "type": "string",
                            "description": "Specific error message",
                            "example": "Invalid birth anniversary date range format"
                          },
                          "code": {
                            "type": "string",
                            "description": "Error code",
                            "example": "INVALID_INPUT"
                          }
                        },
                        "required": [
                          "message",
                          "code"
                        ]
                      },
                      "description": "Array of specific error details"
                    },
                    "timestamp": {
                      "type": "integer",
                      "description": "Response timestamp",
                      "example": 1761571631200
                    },
                    "delay": {
                      "type": "number",
                      "description": "Response delay in seconds",
                      "example": 30.421958
                    }
                  },
                  "required": [
                    "status",
                    "message",
                    "errors",
                    "timestamp",
                    "delay"
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "Unauthorized": {
        "description": "Authorize error",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "message": {
                  "type": "string",
                  "example": "Missing/Invalid authentication token"
                }
              }
            }
          }
        }
      },
      "Forbidden": {
        "description": "Forbidden error",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "error_code": {
                  "type": "integer",
                  "example": 2001
                },
                "message": {
                  "type": "string",
                  "example": "Something went wrong, please try again"
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "apiAuthSecurity": {
        "type": "oauth2",
        "description": "This API uses OAuth 2 with the implicit grant flow.",
        "flows": {
          "implicit": {
            "authorizationUrl": "https://platform.test.simpplr.xyz/v1",
            "scopes": {
              "read": "read data",
              "write": "create/update data",
              "everything": "allow full access"
            }
          }
        }
      }
    }
  },
  "security": [
    {
      "apiAuthSecurity": []
    }
  ]
}
````