> For the complete documentation index, see [llms.txt](https://developer.usemultiplier.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.usemultiplier.com/api-reference/partner-management/customer-departments.md).
# Customer Departments
Manage customer departments
## List all departments
> Retrieve all departments for the authenticated company.
```json
{"openapi":"3.0.1","info":{"title":"Multiplier Public REST API","version":"1.0.0"},"tags":[{"name":"Customer Departments","description":"Manage customer departments"}],"servers":[{"url":"https://api.usemultiplier.com","description":"Production API / Partner Sandbox"},{"url":"https://release-api-gateway.api.usemultiplier.com","description":"MPL internal release environment"},{"url":"https://api-gateway.api.acc.staging.usemultiplier.com","description":"MPL internal staging"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","description":"JWT Bearer token authentication.\n\nTo authenticate:\n1. Obtain a JWT token from your authentication endpoint\n2. Click the \"Authorize\" button above\n3. Enter your token in the format: your-jwt-token\n4. Click \"Authorize\" to apply to all requests\n\nThe token will be automatically included in the Authorization header\nas: Authorization: Bearer {token}\n","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"V1DepartmentsGetResponse":{"required":["data"],"type":"object","properties":{"data":{"type":"array","description":"List of all departments for the company","items":{"$ref":"#/components/schemas/DepartmentItem"}}}},"DepartmentItem":{"type":"object","properties":{"id":{"type":"string","description":"Department ID (UUID).","format":"uuid"},"code":{"type":"string","description":"Department code","nullable":true},"name":{"type":"string","description":"Department name"},"description":{"type":"string","description":"Department description","nullable":true},"createdAt":{"type":"string","description":"Timestamp when the department was created (ISO 8601)","format":"date-time"}}},"ErrorResponse":{"required":["code","correlationId","message","path","timestamp"],"type":"object","properties":{"timestamp":{"type":"string","description":"ISO-8601 UTC timestamp of when the error occurred","format":"date-time"},"code":{"type":"string","description":"Machine-readable error category","enum":["BAD_REQUEST","UNAUTHORIZED","FORBIDDEN","NOT_FOUND","CONFLICT","VALIDATION_ERROR","SERVICE_UNAVAILABLE","INTERNAL_SERVER_ERROR"]},"message":{"type":"string","description":"Human-readable description of the error"},"path":{"type":"string","description":"Request URI that produced the error"},"correlationId":{"type":"string","description":"Trace ID for correlating this error in logs"},"errors":{"type":"array","description":"Field-level error details. Present for validation errors; may be present for other errors.","items":{"$ref":"#/components/schemas/ErrorItem"}},"error":{"description":"Deprecated: Use errors instead. Backward-compatible error object.","nullable":true,"deprecated":true,"allOf":[{"$ref":"#/components/schemas/LegacyError"}]}}},"ErrorItem":{"required":["message"],"type":"object","properties":{"property":{"type":"string","description":"The field that caused the error (only present for validation errors)"},"message":{"type":"string","description":"Description of the error"}}},"LegacyError":{"required":["code","message"],"type":"object","properties":{"code":{"type":"string","description":"Machine-readable error code"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"array","description":"Field-level error details. Only present for validation errors.","nullable":true,"items":{"$ref":"#/components/schemas/LegacyFieldError"}}},"deprecated":true},"LegacyFieldError":{"required":["field","message"],"type":"object","properties":{"field":{"type":"string","description":"The field that caused the error"},"message":{"type":"string","description":"Description of the field error"}},"deprecated":true}}},"paths":{"/v1/partner/customers/{customerId}/departments":{"get":{"tags":["Customer Departments"],"summary":"List all departments","description":"Retrieve all departments for the authenticated company.\n","operationId":"listDepartments","parameters":[{"name":"customerId","in":"path","description":"Customer ID (UUID)","required":true,"style":"simple","explode":false,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Departments retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1DepartmentsGetResponse"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Service unavailable - upstream dependency error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
## Create a new department
> Create a new department for the authenticated company.\
> \
> Returns 201 with the full DepartmentItem on success.
```json
{"openapi":"3.0.1","info":{"title":"Multiplier Public REST API","version":"1.0.0"},"tags":[{"name":"Customer Departments","description":"Manage customer departments"}],"servers":[{"url":"https://api.usemultiplier.com","description":"Production API / Partner Sandbox"},{"url":"https://release-api-gateway.api.usemultiplier.com","description":"MPL internal release environment"},{"url":"https://api-gateway.api.acc.staging.usemultiplier.com","description":"MPL internal staging"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","description":"JWT Bearer token authentication.\n\nTo authenticate:\n1. Obtain a JWT token from your authentication endpoint\n2. Click the \"Authorize\" button above\n3. Enter your token in the format: your-jwt-token\n4. Click \"Authorize\" to apply to all requests\n\nThe token will be automatically included in the Authorization header\nas: Authorization: Bearer {token}\n","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"V1DepartmentsPostRequest":{"required":["name"],"type":"object","properties":{"code":{"type":"string","description":"Department code (optional)","nullable":true},"name":{"type":"string","description":"Department name (required)"},"description":{"type":"string","description":"Department description (optional)","nullable":true}}},"DepartmentItem":{"type":"object","properties":{"id":{"type":"string","description":"Department ID (UUID).","format":"uuid"},"code":{"type":"string","description":"Department code","nullable":true},"name":{"type":"string","description":"Department name"},"description":{"type":"string","description":"Department description","nullable":true},"createdAt":{"type":"string","description":"Timestamp when the department was created (ISO 8601)","format":"date-time"}}},"ErrorResponse":{"required":["code","correlationId","message","path","timestamp"],"type":"object","properties":{"timestamp":{"type":"string","description":"ISO-8601 UTC timestamp of when the error occurred","format":"date-time"},"code":{"type":"string","description":"Machine-readable error category","enum":["BAD_REQUEST","UNAUTHORIZED","FORBIDDEN","NOT_FOUND","CONFLICT","VALIDATION_ERROR","SERVICE_UNAVAILABLE","INTERNAL_SERVER_ERROR"]},"message":{"type":"string","description":"Human-readable description of the error"},"path":{"type":"string","description":"Request URI that produced the error"},"correlationId":{"type":"string","description":"Trace ID for correlating this error in logs"},"errors":{"type":"array","description":"Field-level error details. Present for validation errors; may be present for other errors.","items":{"$ref":"#/components/schemas/ErrorItem"}},"error":{"description":"Deprecated: Use errors instead. Backward-compatible error object.","nullable":true,"deprecated":true,"allOf":[{"$ref":"#/components/schemas/LegacyError"}]}}},"ErrorItem":{"required":["message"],"type":"object","properties":{"property":{"type":"string","description":"The field that caused the error (only present for validation errors)"},"message":{"type":"string","description":"Description of the error"}}},"LegacyError":{"required":["code","message"],"type":"object","properties":{"code":{"type":"string","description":"Machine-readable error code"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"array","description":"Field-level error details. Only present for validation errors.","nullable":true,"items":{"$ref":"#/components/schemas/LegacyFieldError"}}},"deprecated":true},"LegacyFieldError":{"required":["field","message"],"type":"object","properties":{"field":{"type":"string","description":"The field that caused the error"},"message":{"type":"string","description":"Description of the field error"}},"deprecated":true}}},"paths":{"/v1/partner/customers/{customerId}/departments":{"post":{"tags":["Customer Departments"],"summary":"Create a new department","description":"Create a new department for the authenticated company.\n\nReturns 201 with the full DepartmentItem on success.\n","operationId":"createDepartment","parameters":[{"name":"customerId","in":"path","description":"Customer ID (UUID)","required":true,"style":"simple","explode":false,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1DepartmentsPostRequest"}}},"required":true},"responses":{"201":{"description":"Department created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DepartmentItem"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable entity - validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Service unavailable - upstream dependency error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
## Update a department
> Partially update a department by its ID.\
> \
> Only supplied fields are updated. If field is not provided, the existing value is preserved.\
> \
> Returns \`200\` with the full \`DepartmentItem\` on success.
```json
{"openapi":"3.0.1","info":{"title":"Multiplier Public REST API","version":"1.0.0"},"tags":[{"name":"Customer Departments","description":"Manage customer departments"}],"servers":[{"url":"https://api.usemultiplier.com","description":"Production API / Partner Sandbox"},{"url":"https://release-api-gateway.api.usemultiplier.com","description":"MPL internal release environment"},{"url":"https://api-gateway.api.acc.staging.usemultiplier.com","description":"MPL internal staging"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","description":"JWT Bearer token authentication.\n\nTo authenticate:\n1. Obtain a JWT token from your authentication endpoint\n2. Click the \"Authorize\" button above\n3. Enter your token in the format: your-jwt-token\n4. Click \"Authorize\" to apply to all requests\n\nThe token will be automatically included in the Authorization header\nas: Authorization: Bearer {token}\n","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"V1DepartmentsPatchRequest":{"type":"object","properties":{"name":{"type":"string","description":"Department name. If omitted, existing name is preserved.","nullable":true},"code":{"type":"string","description":"Department code. If omitted, existing code is preserved.","nullable":true},"description":{"type":"string","description":"Department description. If omitted, existing description is preserved.","nullable":true}}},"DepartmentItem":{"type":"object","properties":{"id":{"type":"string","description":"Department ID (UUID).","format":"uuid"},"code":{"type":"string","description":"Department code","nullable":true},"name":{"type":"string","description":"Department name"},"description":{"type":"string","description":"Department description","nullable":true},"createdAt":{"type":"string","description":"Timestamp when the department was created (ISO 8601)","format":"date-time"}}},"ErrorResponse":{"required":["code","correlationId","message","path","timestamp"],"type":"object","properties":{"timestamp":{"type":"string","description":"ISO-8601 UTC timestamp of when the error occurred","format":"date-time"},"code":{"type":"string","description":"Machine-readable error category","enum":["BAD_REQUEST","UNAUTHORIZED","FORBIDDEN","NOT_FOUND","CONFLICT","VALIDATION_ERROR","SERVICE_UNAVAILABLE","INTERNAL_SERVER_ERROR"]},"message":{"type":"string","description":"Human-readable description of the error"},"path":{"type":"string","description":"Request URI that produced the error"},"correlationId":{"type":"string","description":"Trace ID for correlating this error in logs"},"errors":{"type":"array","description":"Field-level error details. Present for validation errors; may be present for other errors.","items":{"$ref":"#/components/schemas/ErrorItem"}},"error":{"description":"Deprecated: Use errors instead. Backward-compatible error object.","nullable":true,"deprecated":true,"allOf":[{"$ref":"#/components/schemas/LegacyError"}]}}},"ErrorItem":{"required":["message"],"type":"object","properties":{"property":{"type":"string","description":"The field that caused the error (only present for validation errors)"},"message":{"type":"string","description":"Description of the error"}}},"LegacyError":{"required":["code","message"],"type":"object","properties":{"code":{"type":"string","description":"Machine-readable error code"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"array","description":"Field-level error details. Only present for validation errors.","nullable":true,"items":{"$ref":"#/components/schemas/LegacyFieldError"}}},"deprecated":true},"LegacyFieldError":{"required":["field","message"],"type":"object","properties":{"field":{"type":"string","description":"The field that caused the error"},"message":{"type":"string","description":"Description of the field error"}},"deprecated":true}}},"paths":{"/v1/partner/customers/{customerId}/departments/{departmentId}":{"patch":{"tags":["Customer Departments"],"summary":"Update a department","description":"Partially update a department by its ID.\n\nOnly supplied fields are updated. If field is not provided, the existing value is preserved.\n\nReturns `200` with the full `DepartmentItem` on success.\n","operationId":"updateDepartment","parameters":[{"name":"customerId","in":"path","description":"Customer ID (UUID)","required":true,"style":"simple","explode":false,"schema":{"type":"string","format":"uuid"}},{"name":"departmentId","in":"path","description":"Department ID (UUID)","required":true,"style":"simple","explode":false,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V1DepartmentsPatchRequest"}}},"required":true},"responses":{"200":{"description":"Department updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DepartmentItem"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - insufficient permissions","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable entity - validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"Service unavailable - upstream dependency error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://developer.usemultiplier.com/api-reference/partner-management/customer-departments.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.