---
updatedAt: 2026-05-27T16:52:24.000Z
agentTools:
  projectIndex: https://developer.bill.com/llms.txt
---

# Get user details

Get details about an existing user.

# OpenAPI definition

```json
{
  "openapi": "3.0.1",
  "info": {
    "title": "BILL v3 API",
    "description": "BILL is a cloud-based financial operations platform for an organization's accounts payable (AP), accounts receivable (AR), and spend & expense (S&E) automation.\n\nThe BILL v3 API gives you access to the same infrastructure that powers the AP, AR, and S&E products. In addition, you can receive real-time event notifications with webhooks.\n\nThe BILL Developer Documentation is available at [developer.bill.com](https://developer.bill.com/docs/home).\n\n## Quickstart\nSign-up and generate a developer key for working with the BILL v3 API. With this key, you can build with the AP, AR, BILL network, and webhook workflows. See [Sandbox API sign up](https://developer.bill.com/docs/api-sandbox-sign-up) for more information.\n\n### Spend & Expense API\nAn API token is required for working with the Spend & Expense API. See [Authentication with Spend & Expense API token](https://developer.bill.com/docs/authentication-with-api-token) for more information.\n\n### BILL v3 API in Postman\nWith this collection, you have access to the BILL v3 API in Postman. When you save your sandbox API credentials as environment variables in Postman, you can simply refer to the variables when you are testing with the BILL v3 API. See [BILL v3 API in Postman](https://developer.bill.com/docs/bill-v3-api-in-postman) for more information.",
    "version": "1"
  },
  "servers": [
    {
      "url": "https://gateway.stage.bill.com/connect",
      "description": "sandbox"
    }
  ],
  "paths": {
    "/v3/spend/users/{userId}": {
      "get": {
        "tags": [
          "users"
        ],
        "summary": "Get user details",
        "description": "Get details about an existing user.",
        "operationId": "getUser",
        "parameters": [
          {
            "name": "apiToken",
            "in": "header",
            "schema": {
              "type": "string",
              "description": "Access token for Spend & Expense API authentication",
              "nullable": true,
              "example": "{{api_token}}"
            }
          },
          {
            "name": "userId",
            "in": "path",
            "required": true,
            "schema": {
              "minLength": 1,
              "type": "string",
              "description": "BILL-generated ID or UUID of the user",
              "example": "{{se_user_uuid}}"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Get user details response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserResponseDto"
                }
              }
            }
          },
          "4XX": {
            "description": "List of errors.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/BdcError"
                  }
                }
              }
            }
          },
          "5XX": {
            "description": "List of errors.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/BdcError"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "BdcError": {
        "required": [
          "category",
          "code",
          "severity",
          "timestamp"
        ],
        "type": "object",
        "properties": {
          "timestamp": {
            "type": "string",
            "format": "date-time"
          },
          "code": {
            "type": "string"
          },
          "severity": {
            "$ref": "#/components/schemas/Severity"
          },
          "category": {
            "$ref": "#/components/schemas/Category"
          },
          "message": {
            "type": "string"
          },
          "params": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Param"
            }
          },
          "detail": {
            "type": "string"
          },
          "help": {
            "type": "string"
          }
        }
      },
      "Category": {
        "type": "string",
        "enum": [
          "REQUEST",
          "APPLICATION",
          "SERVER",
          "DOWNSTREAM"
        ]
      },
      "Param": {
        "required": [
          "name",
          "value"
        ],
        "type": "object",
        "properties": {
          "additional": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "name": {
            "minLength": 1,
            "type": "string"
          },
          "value": {
            "minLength": 1,
            "type": "string"
          }
        }
      },
      "RoleType": {
        "type": "string",
        "description": "Spend \\& Expense User Role type information.",
        "enum": [
          "ADMIN",
          "APPROVER",
          "AUDITOR",
          "BOOKKEEPER",
          "MEMBER",
          "FINANCE_ADMIN",
          "NO_ACCESS"
        ]
      },
      "Severity": {
        "type": "string",
        "enum": [
          "ERROR",
          "WARNING",
          "INFORMATION"
        ]
      },
      "UserResponseDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "BILL-generated ID of the user",
            "deprecated": true
          },
          "uuid": {
            "type": "string",
            "description": "BILL-generated UUID of the user"
          },
          "firstName": {
            "type": "string",
            "description": "User first name"
          },
          "lastName": {
            "type": "string",
            "description": "User last name"
          },
          "email": {
            "type": "string",
            "description": "User email address"
          },
          "receiptEmail": {
            "type": "string",
            "description": "Receipt categorization email address"
          },
          "retired": {
            "type": "boolean",
            "description": "Set as `true` if the user is deleted"
          },
          "useCompanyMailingAddress": {
            "type": "boolean",
            "description": "Set as `true` if the company email address is set for the user"
          },
          "smsOptIn": {
            "type": "boolean",
            "description": "Set as `true` if SMS notifications are enabled for the user"
          },
          "hasDateOfBirth": {
            "type": "boolean",
            "description": "Set as `true` if the user date of birth is set"
          },
          "role": {
            "allOf": [
              {
                "$ref": "#/components/schemas/RoleType"
              },
              {
                "description": "User role"
              }
            ]
          },
          "phoneNumber": {
            "type": "string",
            "description": "User phone number"
          },
          "createdTime": {
            "type": "string",
            "description": "User created date and time",
            "format": "date-time"
          }
        },
        "description": "Users response."
      }
    }
  }
}
```