---
updatedAt: 2026-10-02T08:20:18.000Z
agentTools:
  projectIndex: https://docs.bkbn.com/llms.txt
---

# List users

Returns a paginated list of users in the authenticated client's workspace. Pass the zero-based `page` query parameter to page through the results and the `size` query parameter to control the page size (default 50, clamped to the range 1..100; a `size` below 1 is treated as 1). Negative `page` values are treated as 0. The response echoes the effective (clamped) `page` and `size`. Filtering and sorting are not supported.

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "BKBN Sync API",
    "description": "API connector for customer applications.",
    "version": "2.16.0"
  },
  "servers": [
    {
      "url": "http://sync-dev.bkbn.com",
      "description": "Generated server url"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Users",
      "description": "Operations for managing users within a workspace"
    },
    {
      "name": "Webhook Events",
      "description": "Event payloads BKBN POSTs to your callback URL. You receive these; you do not call them."
    }
  ],
  "paths": {
    "/v1/users": {
      "get": {
        "tags": [
          "Users"
        ],
        "summary": "List users",
        "description": "Returns a paginated list of users in the authenticated client's workspace. Pass the zero-based `page` query parameter to page through the results and the `size` query parameter to control the page size (default 50, clamped to the range 1..100; a `size` below 1 is treated as 1). Negative `page` values are treated as 0. The response echoes the effective (clamped) `page` and `size`. Filtering and sorting are not supported.",
        "operationId": "listUsers",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 0
            }
          },
          {
            "name": "size",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "format": "int32",
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Page of users successfully retrieved",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PageResponseDTOUserListItemResponseDTO"
                }
              }
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {}
            }
          },
          "403": {
            "description": "Access denied",
            "content": {
              "application/json": {}
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "PageResponseDTOUserListItemResponseDTO": {
        "type": "object",
        "description": "A single page of results with pagination metadata.",
        "properties": {
          "content": {
            "type": "array",
            "description": "The items on the current page.",
            "items": {
              "$ref": "#/components/schemas/UserListItemResponseDTO"
            }
          },
          "page": {
            "type": "integer",
            "format": "int32",
            "description": "Zero-based index of the current page.",
            "example": 0
          },
          "size": {
            "type": "integer",
            "format": "int32",
            "description": "Number of items requested per page.",
            "example": 50
          },
          "totalElements": {
            "type": "integer",
            "format": "int64",
            "description": "Total number of items across all pages.",
            "example": 137
          },
          "totalPages": {
            "type": "integer",
            "format": "int32",
            "description": "Total number of pages available.",
            "example": 3
          },
          "first": {
            "type": "boolean",
            "description": "Whether this is the first page."
          },
          "last": {
            "type": "boolean",
            "description": "Whether this is the last page."
          }
        },
        "required": [
          "content",
          "first",
          "last",
          "page",
          "size",
          "totalElements",
          "totalPages"
        ]
      },
      "UserListItemResponseDTO": {
        "type": "object",
        "description": "Compact representation of a user as returned in listing responses.",
        "properties": {
          "internalId": {
            "type": "string",
            "format": "uuid",
            "description": "BKBN primary key of the user."
          },
          "userReferenceId": {
            "type": "string",
            "description": "External reference ID from the caller's own system, if set."
          },
          "email": {
            "type": "string",
            "description": "The user's email address."
          },
          "name": {
            "type": "string",
            "description": "The user's full name."
          },
          "language": {
            "type": "string",
            "description": "The user's preferred language."
          },
          "phone": {
            "type": "string",
            "description": "The user's phone number, if set."
          },
          "country": {
            "type": "string",
            "description": "The user's country."
          }
        },
        "required": [
          "country",
          "email",
          "internalId",
          "language",
          "name"
        ]
      },
      "VisualsReadyEvent": {
        "type": "object",
        "required": [
          "event",
          "timestamp",
          "orderId",
          "assignmentId",
          "visualType",
          "product"
        ],
        "properties": {
          "event": {
            "type": "string",
            "const": "VISUALS_READY"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "description": "When the webhook was sent.",
            "example": "2023-01-15T12:45:00Z"
          },
          "orderId": {
            "type": "string",
            "example": "100234"
          },
          "assignmentId": {
            "type": "string",
            "example": "a1b2c3d4"
          },
          "visualType": {
            "type": "string",
            "description": "Resource type that is ready. Mirrors the platform resource taxonomy.",
            "example": "POST"
          },
          "product": {
            "type": "string",
            "description": "Product/deliverable that is ready. Mirrors the platform product taxonomy.",
            "example": "GROUND_PHOTO"
          },
          "realEstatePropertyId": {
            "type": "string",
            "format": "uuid",
            "description": "Real estate property id, if applicable."
          },
          "objectReferenceId": {
            "type": "string",
            "description": "Client-supplied object reference, if provided."
          }
        }
      },
      "PhotographerBookedEvent": {
        "type": "object",
        "required": [
          "event",
          "timestamp",
          "orderId",
          "photographerId"
        ],
        "properties": {
          "event": {
            "type": "string",
            "const": "PHOTOGRAPHER_BOOKED"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "example": "2023-01-15T12:45:00Z"
          },
          "orderId": {
            "type": "string",
            "example": "100234"
          },
          "photographerId": {
            "type": "string",
            "description": "Public id of the photographer (creative) who accepted.",
            "example": "55021"
          },
          "assignmentId": {
            "type": "string",
            "description": "Assignment id, when available.",
            "example": "a1b2c3d4"
          }
        }
      },
      "OrderStatusUpdatedEvent": {
        "type": "object",
        "required": [
          "event",
          "occurredAt",
          "orderId",
          "previousStatus",
          "newStatus"
        ],
        "properties": {
          "event": {
            "type": "string",
            "const": "ORDER_STATUS_UPDATED"
          },
          "occurredAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the change occurred on the platform.",
            "example": "2026-06-25T09:30:00Z"
          },
          "orderId": {
            "type": "string",
            "example": "100234"
          },
          "previousStatus": {
            "type": "string",
            "example": "PLACED"
          },
          "newStatus": {
            "type": "string",
            "example": "IN_PROGRESS"
          }
        }
      },
      "AssignmentStatusUpdatedEvent": {
        "type": "object",
        "required": [
          "event",
          "occurredAt",
          "orderId",
          "assignmentId",
          "previousStatus",
          "newStatus"
        ],
        "properties": {
          "event": {
            "type": "string",
            "const": "ASSIGNMENT_STATUS_UPDATED"
          },
          "occurredAt": {
            "type": "string",
            "format": "date-time",
            "example": "2026-06-25T09:30:00Z"
          },
          "orderId": {
            "type": "string",
            "example": "100234"
          },
          "assignmentId": {
            "type": "string",
            "example": "a1b2c3d4"
          },
          "previousStatus": {
            "type": "string",
            "example": "SCHEDULED"
          },
          "newStatus": {
            "type": "string",
            "example": "IN_PRODUCTION"
          },
          "assignmentType": {
            "type": "string",
            "description": "Assignment type, when available."
          },
          "scheduledAt": {
            "type": "string",
            "format": "date-time",
            "description": "Confirmed shooting start, when available."
          },
          "estimatedDeliveryAt": {
            "type": "string",
            "format": "date",
            "description": "Estimated delivery date (date-only), when available."
          },
          "actionRequired": {
            "type": "string",
            "description": "Action-required detail, when applicable."
          }
        }
      },
      "AppointmentDateUpdatedEvent": {
        "type": "object",
        "required": [
          "event",
          "occurredAt",
          "orderId",
          "assignmentId",
          "scheduledAt"
        ],
        "properties": {
          "event": {
            "type": "string",
            "const": "APPOINTMENT_DATE_UPDATED"
          },
          "occurredAt": {
            "type": "string",
            "format": "date-time",
            "example": "2026-06-25T09:30:00Z"
          },
          "orderId": {
            "type": "string",
            "example": "100234"
          },
          "assignmentId": {
            "type": "string",
            "example": "a1b2c3d4"
          },
          "assignmentType": {
            "type": "string",
            "description": "Assignment type, when available."
          },
          "scheduledAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "New confirmed shooting start. Always present; `null` means the appointment was cleared (reschedule pending).\n"
          }
        }
      },
      "EstimatedDeliveryUpdatedEvent": {
        "type": "object",
        "required": [
          "event",
          "occurredAt",
          "orderId",
          "assignmentId",
          "estimatedDeliveryAt"
        ],
        "properties": {
          "event": {
            "type": "string",
            "const": "ESTIMATED_DELIVERY_UPDATED"
          },
          "occurredAt": {
            "type": "string",
            "format": "date-time",
            "example": "2026-06-25T09:30:00Z"
          },
          "orderId": {
            "type": "string",
            "example": "100234"
          },
          "assignmentId": {
            "type": "string",
            "example": "a1b2c3d4"
          },
          "assignmentType": {
            "type": "string",
            "description": "Assignment type, when available."
          },
          "estimatedDeliveryAt": {
            "type": "string",
            "format": "date",
            "description": "Estimated delivery date (date-only).",
            "example": "2026-07-02"
          }
        }
      },
      "MarketingMaterialsReadyEvent": {
        "type": "object",
        "required": [
          "event",
          "timestamp",
          "propertyId",
          "targetPlatform"
        ],
        "properties": {
          "event": {
            "type": "string",
            "const": "MARKETING_MATERIALS_READY"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "example": "2023-01-15T12:45:00Z"
          },
          "propertyId": {
            "type": "string",
            "format": "uuid",
            "description": "Real estate property id."
          },
          "targetPlatform": {
            "type": "string",
            "description": "Target platform the materials were prepared for."
          }
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "description": "JWT Authentication. Enter your token in the format: Bearer {token}",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    },
    "parameters": {
      "EventTypeHeader": {
        "name": "X-Event-Type",
        "in": "header",
        "required": true,
        "description": "The event name. Matches the `event` field in the body.",
        "schema": {
          "type": "string",
          "example": "ASSIGNMENT_STATUS_UPDATED"
        }
      }
    }
  },
  "webhooks": {
    "visualsReady": {
      "post": {
        "summary": "Visuals ready",
        "description": "Sent when materials (visuals, documents, or other deliverables) are ready for download. On receipt, call the Materials API to retrieve the actual files.\n",
        "operationId": "onVisualsReady",
        "parameters": [
          {
            "$ref": "#/components/parameters/EventTypeHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VisualsReadyEvent"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Acknowledged by the consumer."
          }
        },
        "tags": [
          "Webhook Events"
        ]
      }
    },
    "photographerBooked": {
      "post": {
        "summary": "Photographer booked",
        "description": "Sent when a photographer (creative) has accepted an assignment.",
        "operationId": "onPhotographerBooked",
        "parameters": [
          {
            "$ref": "#/components/parameters/EventTypeHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PhotographerBookedEvent"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Acknowledged by the consumer."
          }
        },
        "tags": [
          "Webhook Events"
        ]
      }
    },
    "orderStatusUpdated": {
      "post": {
        "summary": "Order status updated",
        "description": "Sent when an order transitions between statuses.",
        "operationId": "onOrderStatusUpdated",
        "parameters": [
          {
            "$ref": "#/components/parameters/EventTypeHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OrderStatusUpdatedEvent"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Acknowledged by the consumer."
          }
        },
        "tags": [
          "Webhook Events"
        ]
      }
    },
    "assignmentStatusUpdated": {
      "post": {
        "summary": "Assignment status updated",
        "description": "Sent when an assignment transitions between statuses. May also be sent as a same-status nudge carrying refreshed logistics fields.\n",
        "operationId": "onAssignmentStatusUpdated",
        "parameters": [
          {
            "$ref": "#/components/parameters/EventTypeHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AssignmentStatusUpdatedEvent"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Acknowledged by the consumer."
          }
        },
        "tags": [
          "Webhook Events"
        ]
      }
    },
    "appointmentDateUpdated": {
      "post": {
        "summary": "Appointment date updated",
        "description": "Sent when an assignment's shooting appointment date changes. `scheduledAt` is always present and is `null` when the appointment was cleared (reschedule pending).\n",
        "operationId": "onAppointmentDateUpdated",
        "parameters": [
          {
            "$ref": "#/components/parameters/EventTypeHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AppointmentDateUpdatedEvent"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Acknowledged by the consumer."
          }
        },
        "tags": [
          "Webhook Events"
        ]
      }
    },
    "estimatedDeliveryUpdated": {
      "post": {
        "summary": "Estimated delivery updated",
        "description": "Sent when an assignment's estimated delivery date changes.",
        "operationId": "onEstimatedDeliveryUpdated",
        "parameters": [
          {
            "$ref": "#/components/parameters/EventTypeHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EstimatedDeliveryUpdatedEvent"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Acknowledged by the consumer."
          }
        },
        "tags": [
          "Webhook Events"
        ]
      }
    },
    "marketingMaterialsReady": {
      "post": {
        "summary": "Marketing materials ready",
        "description": "Sent when marketing materials for a property are ready for a target platform.",
        "operationId": "onMarketingMaterialsReady",
        "parameters": [
          {
            "$ref": "#/components/parameters/EventTypeHeader"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MarketingMaterialsReadyEvent"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Acknowledged by the consumer."
          }
        },
        "tags": [
          "Webhook Events"
        ]
      }
    }
  }
}
```