{
  "openapi": "3.0.3",
  "info": {
    "title": "Partners API",
    "version": "1.0.0",
    "description": "Create and update bookings and contacts for one approved WaW customer team. Each customer key is tied to one team and one environment."
  },
  "servers": [
    { "url": "https://acc-api.withoutaworry.com", "description": "Acceptance" },
    { "url": "https://api.withoutaworry.com", "description": "Production" }
  ],
  "security": [{ "partnerKey": [] }],
  "paths": {
    "/v1/bookings": {
      "post": {
        "summary": "Create a booking",
        "operationId": "createBooking",
        "description": "Creates one booking for the team linked to the customer key. Repeat the same request with the same external_id to receive the existing record instead of creating a duplicate.",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBooking" }, "example": { "external_id": "booking-8421", "name": "Wedding Noor and Sam", "start_date": "2027-06-12T16:00:00+02:00", "end_date": "2027-06-13T02:00:00+02:00", "location": "Ghent", "status": "confirmed" } } } },
        "responses": { "201": { "$ref": "#/components/responses/Created" }, "200": { "$ref": "#/components/responses/Replay" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Invalid" } }
      }
    },
    "/v1/bookings/{id}": {
      "patch": {
        "summary": "Update a booking",
        "operationId": "updateBooking",
        "description": "Updates only the supplied fields. The booking must belong to the team linked to the customer key. Use lost_reason when status is lost.",
        "parameters": [{ "$ref": "#/components/parameters/Id" }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateBooking" }, "example": { "location": "Bruges", "status": "confirmed" } } } },
        "responses": { "200": { "$ref": "#/components/responses/Updated" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" } }
      }
    },
    "/v1/contacts": {
      "post": {
        "summary": "Create a contact",
        "operationId": "createContact",
        "description": "Creates a person or company for the team linked to the customer key. Repeat the same request with the same external_id to receive the existing record instead of creating a duplicate.",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateContact" }, "example": { "external_id": "person-8421", "first_name": "Noor", "last_name": "Janssens", "email": "noor@example.com", "phone": "+32470000001" } } } },
        "responses": { "201": { "$ref": "#/components/responses/Created" }, "200": { "$ref": "#/components/responses/Replay" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "422": { "$ref": "#/components/responses/Invalid" } }
      }
    },
    "/v1/contacts/{id}": {
      "patch": {
        "summary": "Update a contact",
        "operationId": "updateContact",
        "description": "Updates only the supplied name, email or phone fields. The contact must belong to the team linked to the customer key.",
        "parameters": [{ "$ref": "#/components/parameters/Id" }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateContact" }, "example": { "phone": "+32470000002" } } } },
        "responses": { "200": { "$ref": "#/components/responses/Updated" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/Invalid" } }
      }
    }
  },
  "components": {
    "securitySchemes": { "partnerKey": { "type": "http", "scheme": "bearer", "bearerFormat": "Customer key" } },
    "parameters": { "Id": { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } },
    "schemas": {
      "CreateBooking": { "type": "object", "required": ["external_id", "name", "start_date", "location"], "additionalProperties": false, "properties": { "external_id": { "type": "string", "maxLength": 128 }, "name": { "type": "string", "maxLength": 300 }, "start_date": { "type": "string", "format": "date-time" }, "end_date": { "type": "string", "format": "date-time", "nullable": true }, "location": { "type": "string", "maxLength": 1000 }, "contact_id": { "type": "string", "format": "uuid", "nullable": true }, "status": { "$ref": "#/components/schemas/BookingStatus" }, "lost_reason": { "type": "string", "maxLength": 1000, "nullable": true } } },
      "UpdateBooking": { "type": "object", "minProperties": 1, "additionalProperties": false, "properties": { "name": { "type": "string", "maxLength": 300 }, "start_date": { "type": "string", "format": "date-time" }, "end_date": { "type": "string", "format": "date-time", "nullable": true }, "location": { "type": "string", "maxLength": 1000 }, "contact_id": { "type": "string", "format": "uuid", "nullable": true }, "status": { "$ref": "#/components/schemas/BookingStatus" }, "lost_reason": { "type": "string", "maxLength": 1000, "nullable": true } } },
      "CreateContact": { "type": "object", "required": ["external_id"], "additionalProperties": false, "properties": { "external_id": { "type": "string", "maxLength": 128 }, "name": { "type": "string", "maxLength": 300 }, "first_name": { "type": "string", "maxLength": 300 }, "last_name": { "type": "string", "maxLength": 300 }, "email": { "type": "string", "format": "email", "maxLength": 320 }, "phone": { "type": "string", "maxLength": 50 }, "entity_type": { "type": "string", "enum": ["person", "company"], "default": "person" } } },
      "UpdateContact": { "type": "object", "minProperties": 1, "additionalProperties": false, "properties": { "name": { "type": "string", "maxLength": 300 }, "first_name": { "type": "string", "maxLength": 300 }, "last_name": { "type": "string", "maxLength": 300 }, "email": { "type": "string", "format": "email", "maxLength": 320, "nullable": true }, "phone": { "type": "string", "maxLength": 50, "nullable": true } } },
      "BookingStatus": { "type": "string", "enum": ["draft", "confirmed", "lost"] },
      "ApiResult": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "external_id": { "type": "string" }, "updated": { "type": "boolean" } } },
      "ApiError": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" } } } } }
    },
    "responses": {
      "Created": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } },
      "Replay": { "description": "Same create request replayed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } },
      "Updated": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResult" } } } },
      "Unauthorized": { "description": "Invalid customer key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } },
      "Forbidden": { "description": "Customer connection is inactive", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } },
      "NotFound": { "description": "Record is outside the customer team", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } },
      "Conflict": { "description": "External ID already exists with different create data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } },
      "Invalid": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }
    }
  }
}
