---
updatedAt: 2026-04-23T05:40:30.000Z
---

# Retrieves a list of users

# OpenAPI definition

```json
{
  "openapi": "3.0.1",
  "info": {
    "title": "API V1",
    "version": "v1"
  },
  "paths": {
    "/users": {
      "get": {
        "summary": "Retrieves a list of users",
        "tags": [
          "Users"
        ],
        "parameters": [
          {
            "name": "_limit",
            "in": "query",
            "description": "Maximum number of users to return",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 20
            }
          },
          {
            "name": "_offset",
            "in": "query",
            "description": "Number of users to skip before starting to return. Offset pages have no defined order and each page costs more than the last, so for a full crawl of a large organization use _cursor instead.",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 0
            }
          },
          {
            "name": "_cursor",
            "in": "query",
            "description": "Keyset pagination, recommended for crawling a whole organization. Pass \"start\" for the first page, then pass meta.next_cursor from each response to get the next page. When _cursor is present, _offset is ignored, pages are ordered by creation time, and every page costs the same regardless of depth. meta.next_cursor is null on the last page.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "_since",
            "in": "query",
            "description": "UTC timestamp in seconds since the Unix epoch (e.g., 1622559600) to filter users updated after this time",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 0
            }
          },
          {
            "name": "user_list_ids",
            "in": "query",
            "description": "Comma-separated list of user list IDs to apply",
            "required": false,
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "phone_number",
            "in": "query",
            "description": "Filter by phone number (any format accepted, will be normalized)",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "email",
            "in": "query",
            "description": "Filter by email address (case-insensitive)",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "successful",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/User"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "total_count": {
                          "type": "integer"
                        },
                        "limit": {
                          "type": "integer"
                        },
                        "offset": {
                          "type": "integer",
                          "description": "Present on offset-paginated responses."
                        },
                        "next_cursor": {
                          "type": "string",
                          "nullable": true,
                          "description": "Present on _cursor responses. Pass it as _cursor to fetch the next page; null on the last page."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "invalid user filter"
          }
        }
      }
    }
  },
  "servers": [
    {
      "url": "https://api.solidarity.tech/v1",
      "variables": {
        "defaultHost": {
          "default": "api.solidarity.tech/v1"
        }
      }
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "schemas": {
      "User": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer"
          },
          "hash_id": {
            "type": "string"
          },
          "phone_number": {
            "type": "string",
            "nullable": true
          },
          "email": {
            "type": "string",
            "nullable": true
          },
          "first_name": {
            "type": "string",
            "nullable": true
          },
          "last_name": {
            "type": "string",
            "nullable": true
          },
          "alternate_name": {
            "type": "string",
            "nullable": true,
            "description": "Alternate name (nickname, community name, or alternate romanization). Searchable."
          },
          "preferred_language": {
            "type": "string"
          },
          "second_language": {
            "type": "string",
            "nullable": true
          },
          "chapter_id": {
            "type": "integer"
          },
          "chapter_ids": {
            "type": "array",
            "items": {
              "type": "integer"
            },
            "description": "Array of all chapter IDs this user belongs to (primary + secondary)"
          },
          "branch_id": {
            "type": "integer",
            "nullable": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "custom_user_properties": {
            "type": "object",
            "additionalProperties": {
              "oneOf": [
                {
                  "type": "string"
                },
                {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                }
              ]
            },
            "description": "Custom property values. String for single-value fields, array of strings for Multiple Checkboxes fields."
          },
          "address": {
            "type": "object",
            "properties": {
              "address1": {
                "type": "string",
                "nullable": true
              },
              "address2": {
                "type": "string",
                "nullable": true
              },
              "city": {
                "type": "string",
                "nullable": true
              },
              "state": {
                "type": "string",
                "nullable": true
              },
              "zip_code": {
                "type": "string",
                "nullable": true
              },
              "country": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "sms_permission": {
            "type": "boolean"
          },
          "call_permission": {
            "type": "boolean"
          },
          "email_permission": {
            "type": "boolean"
          },
          "other_emails": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Additional email addresses stored on the user profile, excluding the primary email."
          },
          "other_phone_numbers": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Additional phone numbers stored on the user profile, excluding the primary phone number."
          }
        }
      }
    }
  }
}
```