---
updatedAt: 2026-04-30T11:04:59.000Z
agentTools:
  projectIndex: https://docs.bkbn.com/llms.txt
---

# Create a new user

Creates a new user in the system. The user will be associated with the authenticated client's workspace. The user will still have to create their profile in the Auth0 authentication system, but their data will be linked upon successful login. Email is a mandatory field. Returns the full user profile including the generated BKBN primary key.

# 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": {
      "post": {
        "tags": [
          "Users"
        ],
        "summary": "Create a new user",
        "description": "Creates a new user in the system. The user will be associated with the authenticated client's workspace. The user will still have to create their profile in the Auth0 authentication system, but their data will be linked upon successful login. Email is a mandatory field. Returns the full user profile including the generated BKBN primary key.",
        "operationId": "createUser",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UserRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "User successfully created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserProfile"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {}
            }
          },
          "401": {
            "description": "Authentication required",
            "content": {
              "application/json": {}
            }
          },
          "403": {
            "description": "Access denied",
            "content": {
              "application/json": {}
            }
          },
          "422": {
            "description": "Unprocessable entity",
            "content": {
              "application/json": {}
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "UserRequest": {
        "type": "object",
        "description": "Broker to create or update in your workspace. On POST, `email` and `country` are both required; omitting either is refused with a 422 naming the field. On PATCH, send only the fields you want to change — an omitted field is left unchanged.",
        "properties": {
          "email": {
            "type": "string",
            "description": "Broker's email address. Required on create; lower-cased before storage, so it is never case-sensitive. It is the broker's identity on the platform and must be unique — re-using an address currently surfaces as a server error rather than a conflict, so treat it as non-retryable and check your own records first."
          },
          "firstName": {
            "type": "string",
            "description": "Given name. Stored as an empty string when omitted on create."
          },
          "lastName": {
            "type": "string",
            "description": "Family name. Stored as an empty string when omitted on create."
          },
          "country": {
            "type": "string",
            "description": "Country the broker operates in, as an ISO 3166-1 alpha-2 code. Required on create — it selects the price book the broker's orders are quoted from, so it is not cosmetic.",
            "enum": [
              "CH",
              "DE",
              "AT",
              "FR",
              "LU",
              "GB",
              "HR",
              "ES",
              "BE",
              "NL",
              "IT",
              "UK",
              "XX"
            ],
            "example": "CH"
          },
          "timezone": {
            "type": "string",
            "description": "IANA timezone used for the broker's appointments and notifications. Defaults to Europe/Berlin when omitted on create.",
            "example": "Europe/Zurich"
          },
          "language": {
            "type": "string",
            "description": "Language the broker is addressed in. Defaults to EN when omitted on create.",
            "enum": [
              "EN",
              "FR",
              "DE",
              "ES",
              "NL",
              "IT"
            ],
            "example": "FR"
          },
          "phone": {
            "type": "string",
            "description": "Contact phone number. Stored as an empty string when omitted on create.",
            "example": "+41 79 123 45 67"
          },
          "personalBillingReference": {
            "type": "string",
            "description": "Your own billing reference for this broker (cost centre, agency code). Carried on the broker record for invoicing; not used for order matching — see the order's `reference`."
          },
          "userReferenceId": {
            "type": "string",
            "description": "This broker's id in your own system. Set it on create and you can address the broker by it afterwards (`/users/by-reference/{userReferenceId}`) instead of storing our `internalId`. It cannot be changed by an update. Keep it unique within your workspace: nothing rejects a duplicate at write time, but the by-reference lookups then fail for every broker sharing it.",
            "example": "broker-4711"
          }
        }
      },
      "UserProfile": {
        "type": "object",
        "description": "A broker in your workspace.",
        "properties": {
          "internalId": {
            "type": "string",
            "format": "uuid",
            "description": "Backbone's id for this broker — the id used by `/users/{userId}` and by session creation."
          },
          "userReferenceId": {
            "type": "string",
            "description": "The broker's id in your own system, if one was supplied on create.",
            "example": "broker-4711"
          },
          "email": {
            "type": "string",
            "description": "Email address."
          },
          "name": {
            "type": "string",
            "description": "Full display name (given and family name joined), not the two fields sent on create. A broker created with neither part comes back as a single space rather than empty."
          },
          "language": {
            "type": "string",
            "description": "Language the broker is addressed in.",
            "example": "FR"
          },
          "phone": {
            "type": "string",
            "description": "Contact phone number. An empty string when the broker was created through this API without one, and null for a broker created any other way — so treat both as absent."
          },
          "country": {
            "type": "string",
            "description": "Country as an ISO 3166-1 alpha-2 code.",
            "example": "CH"
          }
        },
        "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"
        ]
      }
    }
  }
}
```