---
updatedAt: 2026-06-29T20:33:19.000Z
agentTools:
  projectIndex: https://developer.bill.com/llms.txt
---

# Update a user

Update details about an existing user.

This operation requires partner-level permissions.
* A `sessionId` header value generated with [API partner login](https://developer.bill.com/reference/partnerlogin)
* An `appKey` header value
* The `organizationId` of the organization

# 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/partner/users/{userId}": {
      "patch": {
        "tags": [
          "partner"
        ],
        "summary": "Update a user",
        "description": "Update details about an existing user.\n\nThis operation requires partner-level permissions.\n* A `sessionId` header value generated with [API partner login](https://developer.bill.com/reference/partnerlogin)\n* An `appKey` header value\n* The `organizationId` of the organization",
        "operationId": "updatePartnerUser",
        "parameters": [
          {
            "name": "sessionId",
            "in": "header",
            "schema": {
              "type": "string",
              "description": "API session ID generated with `/v3/partner/login`",
              "nullable": true,
              "example": "{{partner_session_id}}"
            }
          },
          {
            "name": "appKey",
            "in": "header",
            "schema": {
              "type": "string",
              "description": "Application key sent to you by BILL when you create a partner account",
              "nullable": true,
              "example": "{{app_key}}"
            }
          },
          {
            "name": "organizationId",
            "in": "header",
            "schema": {
              "type": "string",
              "description": "BILL-generated ID of the organization",
              "nullable": true,
              "example": "{{partner_organization_id}}"
            }
          },
          {
            "name": "userId",
            "in": "path",
            "required": true,
            "schema": {
              "minLength": 1,
              "type": "string",
              "description": "BILL-generated ID of the user. The value begins with `006`.",
              "example": "{{partner_user_id}}"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PartnerUserUpdateRequestDto"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Update a user response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrganizationUserResponseDto"
                }
              }
            }
          },
          "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"
        ]
      },
      "OrganizationUserResponseDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "BILL-generated ID of the user. The value begins with `006`."
          },
          "archived": {
            "type": "boolean",
            "description": "Set as `true` if the user is archived"
          },
          "firstName": {
            "type": "string",
            "description": "User first name"
          },
          "lastName": {
            "type": "string",
            "description": "User last name"
          },
          "email": {
            "type": "string",
            "description": "User email address"
          },
          "role": {
            "allOf": [
              {
                "$ref": "#/components/schemas/UserRoleResponseDto"
              },
              {
                "description": "User role information"
              }
            ]
          },
          "createdTime": {
            "type": "string",
            "description": "Created date and time",
            "format": "date-time"
          },
          "updatedTime": {
            "type": "string",
            "description": "Updated date and time",
            "format": "date-time"
          }
        },
        "description": "Users response."
      },
      "OrganizationUserRoleType": {
        "type": "string",
        "description": "Enumeration of organization user roles.",
        "enum": [
          "ADMINISTRATOR",
          "CLERK",
          "APPROVER",
          "ACCOUNTANT",
          "CUSTOM",
          "PAYER",
          "PARTNER",
          "AUDITOR",
          "NO_ACCESS",
          "MEMBER",
          "MEMBER_PLUS",
          "INTERNAL",
          "PURCHASE_REQUESTER",
          "CONSOLE_CUSTOM",
          "RECEIVER",
          "PROCUREMENT_USER",
          "UNDEFINED"
        ]
      },
      "Param": {
        "required": [
          "name",
          "value"
        ],
        "type": "object",
        "properties": {
          "additional": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "name": {
            "minLength": 1,
            "type": "string"
          },
          "value": {
            "minLength": 1,
            "type": "string"
          }
        }
      },
      "PartnerUserUpdateRequestDto": {
        "type": "object",
        "properties": {
          "firstName": {
            "type": "string",
            "description": "User first name"
          },
          "lastName": {
            "type": "string",
            "description": "User last name"
          },
          "email": {
            "type": "string",
            "description": "User email address"
          },
          "roleId": {
            "type": "string",
            "description": "BILL-generated ID of the user role. The value begins with `0po`.\n\nIf you do not set `roleId`, the default `ADMINISTRATOR` user role is assigned to the created user. You can get the list of available user roles with `GET /v3/partner/roles`."
          }
        },
        "description": "Update a user (last name updated)",
        "example": {
          "lastName": "Soupsmithson"
        }
      },
      "Severity": {
        "type": "string",
        "enum": [
          "ERROR",
          "WARNING",
          "INFORMATION"
        ]
      },
      "UserRoleResponseDto": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "BILL-generated ID of the user role. The value begins with `0po`."
          },
          "type": {
            "allOf": [
              {
                "$ref": "#/components/schemas/OrganizationUserRoleType"
              },
              {
                "description": "User role type."
              }
            ]
          },
          "description": {
            "type": "string",
            "description": "User role description"
          }
        },
        "description": "User roles response."
      }
    }
  }
}
```