> ## Documentation Index > Fetch the complete documentation index at: https://docs.sparkserv.com/llms.txt > Use this file to discover all available pages before exploring further. # Book an appointment > Requires appointments:create. No durable idempotency guarantee; do not blindly retry unknown outcomes. ## OpenAPI ````yaml https://api.sparkserv.com/public/api/swagger.json post /appointments openapi: 3.1.0 info: title: Spark Public API description: >- Dealership discovery and vehicle-specific appointment scheduling. Obtain a token with POST https://auth.sparkserv.com/oauth/token, Content-Type: application/json, and a body containing grant_type: client_credentials, client_id, client_secret, audience: https://api.sparkserv.com/public, and the requested scope string. Send Authorization: Bearer on API requests. Keep client secrets on your server, not in browser applications. Required scopes must be granted both in the token and on the active Spark API client. Dealership access follows its acting-user team memberships. Availability is not a reservation. Booking has no durable idempotency guarantee. Do not blindly retry mutations after timeouts or unknown outcomes; Spark appointment reads are local snapshots, not proof of the current upstream state. Unknown outcomes require reconciliation with the dealership or scheduler. version: '1' contact: {} servers: - url: https://api.sparkserv.com/public/v1 description: Current API environment security: [] tags: [] paths: /appointments: post: tags: - Appointments summary: Book an appointment description: >- Requires appointments:create. No durable idempotency guarantee; do not blindly retry unknown outcomes. operationId: createPublicAppointmentV1 parameters: - name: Dealership-Id in: header required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PublicAppointmentCreateV1Dto' examples: inlineCustomerAndVehicle: summary: >- Book with inline details; replace time and IDs with discovery results value: vehicle: year: 2024 make: Honda model: Civic color: Silver customer: firstName: Jane lastName: Doe phoneNumber: '2125550101' services: - id: f6eeb938-cabe-4a4d-a38d-a47583e074e5 appointmentAt: '2026-11-02T09:00:00-05:00' advisorId: any transportId: drop savedCustomerAndVehicle: summary: Book with authorized customer/vehicle IDs from lookup value: customerId: b9d75ff9-e32b-46bf-8690-85ff6c3993f9 vehicleId: ad503904-cd8a-4fd9-90f0-b176bab906da services: - id: f6eeb938-cabe-4a4d-a38d-a47583e074e5 comments: Inspect brake noise appointmentAt: '2026-11-02T09:00:00-05:00' responses: '201': description: '' content: application/json: schema: $ref: '#/components/schemas/PublicAppointmentDetailsV1ResponseDto' '400': description: >- Invalid request. Inspect code and details and correct the input before retrying. content: application/json: schema: $ref: '#/components/schemas/PublicApiErrorResponseDto' examples: invalidInput: summary: Correct the request fields value: statusCode: 400 code: INVALID_INPUT message: Request validation failed '401': description: >- Missing, invalid or expired client-credentials token, or an inactive client. Obtain a valid token for an active client. content: application/json: schema: $ref: '#/components/schemas/PublicApiErrorResponseDto' examples: unauthorized: summary: Authenticate with an active client value: statusCode: 401 code: UNAUTHORIZED message: The request could not be completed '403': description: The token or active API client lacks a required action scope. content: application/json: schema: $ref: '#/components/schemas/PublicApiErrorResponseDto' examples: forbidden: summary: Grant the required scope and obtain a new token value: statusCode: 403 code: FORBIDDEN message: The request could not be completed '404': description: >- The resource does not exist or is outside the client's dealership access. content: application/json: schema: $ref: '#/components/schemas/PublicApiErrorResponseDto' examples: notFound: summary: Check the resource and dealership access value: statusCode: 404 code: NOT_FOUND message: Resource not found '409': description: >- The scheduler configuration is invalid or the selected appointment time is unavailable. Inspect code before changing the configuration or refreshing availability. content: application/json: schema: $ref: '#/components/schemas/PublicApiErrorResponseDto' examples: schedulerConfiguration: summary: Configure one supported scheduler value: statusCode: 409 code: SCHEDULER_CONFIGURATION message: Exactly one scheduling integration is required slotUnavailable: summary: Refresh availability and select a new slot value: statusCode: 409 code: SLOT_UNAVAILABLE message: The selected appointment time is not available '422': description: >- Customer or vehicle details, service comments, or scheduling selections are missing, conflicting, or unsupported. Inspect code and details. content: application/json: schema: $ref: '#/components/schemas/PublicApiErrorResponseDto' examples: customerRequired: summary: Supply customer name and phone value: statusCode: 422 code: CUSTOMER_REQUIRED message: Customer last name and phone are required '500': description: An unexpected server error prevented the request from completing. content: application/json: schema: $ref: '#/components/schemas/PublicApiErrorResponseDto' examples: requestFailed: summary: Report the unexpected failure value: statusCode: 500 code: REQUEST_FAILED message: The request could not be completed '502': description: >- Preflight discovery may fail before booking is attempted (for example SCHEDULER_UNAVAILABLE or AMBIGUOUS_SERVICES). BOOKING_OUTCOME_UNKNOWN means the booking write could not be confirmed; do not retry blindly and reconcile with the scheduler or dealership. content: application/json: schema: $ref: '#/components/schemas/PublicApiErrorResponseDto' examples: schedulerUnavailable: summary: Retry discovery after the scheduler recovers value: statusCode: 502 code: SCHEDULER_UNAVAILABLE message: The scheduler could not complete the request bookingOutcomeUnknown: summary: Reconcile before retrying value: statusCode: 502 code: BOOKING_OUTCOME_UNKNOWN message: Booking could not be confirmed; do not retry blindly security: - oauth2: - appointments:create components: schemas: PublicAppointmentCreateV1Dto: type: object properties: departmentId: type: string description: An opaque department ID from department discovery customer: description: >- Required during discovery only when the scheduler needs customer identity allOf: - $ref: '#/components/schemas/PublicCustomerDetailsV1Dto' vehicle: description: Supply vehicle details or select a saved vehicle allOf: - $ref: '#/components/schemas/PublicAppointmentVehicleV1Dto' services: minItems: 1 description: Unique Spark service selections with optional write-only comments type: array items: $ref: '#/components/schemas/PublicAppointmentServiceV1Dto' advisorId: type: string description: Advisor ID returned by discovery, or any transportId: type: string description: Transport ID returned by discovery appointmentAt: type: string format: date-time description: Chosen appointment instant; must include Z or an explicit offset example: '2026-11-02T09:00:00-05:00' customerId: type: string format: uuid vehicleId: type: string format: uuid comments: type: string description: Appointment-level public comments required: - services - appointmentAt additionalProperties: false PublicAppointmentDetailsV1ResponseDto: type: object properties: id: type: string format: uuid dealership: $ref: '#/components/schemas/PublicAppointmentDealershipV1ResponseDto' status: type: string enum: - Pending - Canceled - Showed - Missed - Duplicate - Completed - Sold appointmentAt: type: string format: date-time timezone: type: string customer: $ref: '#/components/schemas/PublicAppointmentCustomerV1ResponseDto' vehicle: $ref: '#/components/schemas/PublicAppointmentVehicleV1ResponseDto' department: oneOf: - $ref: '#/components/schemas/PublicAppointmentDepartmentV1ResponseDto' - type: 'null' advisor: $ref: '#/components/schemas/PublicAppointmentAdvisorV1ResponseDto' transport: $ref: '#/components/schemas/PublicAppointmentTransportV1ResponseDto' comments: oneOf: - type: string - type: 'null' services: type: array items: $ref: '#/components/schemas/PublicAppointmentServiceV1ResponseDto' required: - id - dealership - status - appointmentAt - timezone - customer - vehicle - department - advisor - transport - comments - services PublicApiErrorResponseDto: type: object properties: statusCode: type: integer code: type: string description: Stable machine-readable error code message: type: string details: description: >- Validation messages or contextual fields/choices; never raw scheduler error data oneOf: - type: object additionalProperties: true - type: array items: type: string required: - statusCode - code - message PublicCustomerDetailsV1Dto: type: object properties: firstName: type: string description: Omit for a business customer lastName: type: string description: Customer surname or business name phoneNumber: type: string example: '2125550101' email: type: string format: email required: - lastName - phoneNumber additionalProperties: false PublicAppointmentVehicleV1Dto: type: object properties: vin: type: string description: VIN to decode; otherwise supply year, make and model example: 1HGCM82633A004352 year: type: integer minimum: 1886 maximum: 2200 example: 2024 make: type: string example: Honda model: type: string example: Civic trim: type: string mileage: type: integer minimum: 0 color: type: string description: Vehicle color saved in Spark; not sent to the scheduler additionalProperties: false PublicAppointmentServiceV1Dto: type: object properties: id: type: string format: uuid comments: oneOf: - type: string description: >- Omitted or null uses the service default; an empty string clears optional comments - type: 'null' required: - id additionalProperties: false PublicAppointmentDealershipV1ResponseDto: type: object properties: id: type: string format: uuid required: - id PublicAppointmentCustomerV1ResponseDto: type: object properties: id: type: string format: uuid firstName: oneOf: - type: string - type: 'null' lastName: oneOf: - type: string - type: 'null' phoneNumber: oneOf: - type: string - type: 'null' email: oneOf: - type: string - type: 'null' required: - id - firstName - lastName - phoneNumber - email PublicAppointmentVehicleV1ResponseDto: type: object properties: id: type: string format: uuid year: type: number make: type: string model: type: string vin: oneOf: - type: string - type: 'null' mileage: oneOf: - type: number - type: 'null' required: - id - year - make - model - vin - mileage PublicAppointmentDepartmentV1ResponseDto: type: object properties: id: type: string name: oneOf: - type: string - type: 'null' required: - id - name PublicAppointmentAdvisorV1ResponseDto: type: object properties: id: oneOf: - type: string description: Opaque advisor ID, any, or null when not recorded - type: 'null' name: oneOf: - type: string - type: 'null' required: - id - name PublicAppointmentTransportV1ResponseDto: type: object properties: id: type: string name: oneOf: - type: string - type: 'null' required: - id - name PublicAppointmentServiceV1ResponseDto: type: object properties: id: type: string format: uuid name: type: string comments: oneOf: - type: string - type: 'null' required: - id - name - comments securitySchemes: oauth2: type: oauth2 flows: clientCredentials: tokenUrl: https://auth.sparkserv.com/oauth/token scopes: appointments:update: appointments:update appointments:cancel: appointments:cancel dealerships:read: dealerships:read scheduling:read: scheduling:read customers:read: customers:read appointments:read: appointments:read appointments:create: appointments:create ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.