{
  "openapi": "3.1.0",
  "info": {
    "title": "Company Users",
    "description": "Retrieve the list of users on your Snapdocs company account. Use it to validate current users and their active status against your internal employee systems — an alternative to a dedicated user-synchronization integration.",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://api.snapdocs.com",
      "description": "Production"
    },
    {
      "url": "https://api.cs-demo0.snpd.io",
      "description": "Demo"
    },
    {
      "url": "https://api.cx-int0.snpd.io",
      "description": "Integrator"
    }
  ],
  "paths": {
    "/api/v1/company_users": {
      "get": {
        "summary": "Get company users",
        "description": "Retrieves the full list of company users with their basic information and current active status. The company is derived from the access token; there are no request parameters.\n\nRequires the `users:read:company_users` scope. Note that a Snapdocs-owned account-owner user always exists on the account and is included in the returned list.",
        "operationId": "getCompanyUsers",
        "tags": [
          "Company Users"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Successfully retrieved company users",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GetCompanyUsersResponse"
                },
                "example": {
                  "company_users": [
                    {
                      "active": true,
                      "email": "john.doe@company.com",
                      "first_name": "John",
                      "last_name": "Doe",
                      "role": "closer"
                    },
                    {
                      "active": false,
                      "email": "jane.smith@company.com",
                      "first_name": "Jane",
                      "last_name": "Smith",
                      "role": "admin"
                    },
                    {
                      "active": true,
                      "email": "mike.johnson@company.com",
                      "first_name": "Mike",
                      "last_name": "Johnson",
                      "role": "view_and_comment"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized — the `Authorization` header is missing, malformed, or the bearer token is invalid or expired. The `WWW-Authenticate` response header carries the OAuth error details.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "The 'Authorization' http header of your request was missing, incorrect or expired. The header value is expected to be a Bearer token."
                }
              }
            }
          },
          "403": {
            "description": "Forbidden — the access token does not carry the required `users:read:company_users` scope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "The 'Authorization' http header of your request was missing, incorrect or expired. The header value is expected to be a Bearer token."
                }
              }
            }
          },
          "422": {
            "description": "Unprocessable content — the user list could not be retrieved.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "error": "Unexpected error retrieving users"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "OAuth 2.0 bearer token from the Snapdocs token endpoint. The token must include the `users:read:company_users` scope; the company is resolved from the token itself."
      }
    },
    "schemas": {
      "CompanyUser": {
        "type": "object",
        "required": [
          "active",
          "email",
          "first_name",
          "last_name",
          "role"
        ],
        "properties": {
          "active": {
            "type": "boolean",
            "description": "Whether the user is currently active on the company account",
            "example": true
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "User's email address. Email is the username for Snapdocs sign-on and the expected join key against your own user systems.",
            "example": "john.doe@company.com"
          },
          "first_name": {
            "type": "string",
            "description": "User's first name",
            "example": "John"
          },
          "last_name": {
            "type": "string",
            "description": "User's last name",
            "example": "Doe"
          },
          "role": {
            "type": "string",
            "description": "User's role within the company",
            "example": "closer",
            "enum": [
              "closer",
              "admin",
              "manager",
              "view_and_comment"
            ]
          }
        }
      },
      "GetCompanyUsersResponse": {
        "type": "object",
        "required": [
          "company_users"
        ],
        "properties": {
          "company_users": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CompanyUser"
            },
            "description": "List of company users"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "Human-readable error message",
            "example": "Unexpected error retrieving users"
          }
        }
      }
    }
  },
  "security": [
    {
      "bearerAuth": []
    }
  ]
}