swagger: '2.0' info: version: 3.0.0 title: appointments adopt query API description: "## Fortellis - Service - Appointments\nA service appointment is a booking of a vehicle into the service department for work that needs to be carried out on the vehicle. This could be a service, repair, body repair, government test etc.\n\n## What does this API do?\nThe API will allow you to query, create and manage service appointments. \n\n## Intended Audience\nIt is expected that systems that require create, read, update, and delete access to appointments will use this API. Systems implementing service-scheduling will use this API to store appointment records.\n" contact: name: Developer Evangelists url: https://example.com email: support@fortellis.io host: fortellis.io basePath: /sales/notification/v3 schemes: - https security: - permission-model: - anonymous tags: - name: query paths: /: get: consumes: - application/json summary: Query appointments description: Query appointments operationId: queryAppointments tags: - query parameters: - $ref: '#/parameters/header.Accept' - $ref: '#/parameters/header.Accept-Charset' - $ref: '#/parameters/header.Accept-Language' - $ref: '#/parameters/header.If-Match' - $ref: '#/parameters/header.If-None-Match' - $ref: '#/parameters/header.Prefer' - $ref: '#/parameters/header.Request-Id' - $ref: '#/parameters/header.Subscription-Id' - $ref: '#/parameters/header.Authorization' - $ref: '#/parameters/query.dateTimeInterval' - $ref: '#/parameters/query.vehicleHref' - $ref: '#/parameters/query.customerHref' - $ref: '#/parameters/query.advisorHref' produces: - application/json responses: '200': $ref: '#/responses/AppointmentCollection' '400': $ref: '#/responses/BadRequest' '401': $ref: '#/responses/Unauthorized' '403': $ref: '#/responses/Forbidden' /{appointmentId}: get: consumes: - application/json summary: Query an appointment description: Query an appointment operationId: queryAppointment tags: - query parameters: - $ref: '#/parameters/header.Accept' - $ref: '#/parameters/header.Accept-Charset' - $ref: '#/parameters/header.Accept-Language' - $ref: '#/parameters/header.If-Match' - $ref: '#/parameters/header.If-None-Match' - $ref: '#/parameters/header.Prefer' - $ref: '#/parameters/header.Request-Id' - $ref: '#/parameters/header.Subscription-Id' - $ref: '#/parameters/header.Authorization' - $ref: '#/parameters/path.appointmentId' produces: - application/json responses: '200': $ref: '#/responses/Appointment' '400': $ref: '#/responses/BadRequest' '401': $ref: '#/responses/Unauthorized' '403': $ref: '#/responses/Forbidden' '404': $ref: '#/responses/NotFound' /all-product-info: get: summary: Server example operation description: You can use this call to get the information on all of the products at this resource that you need to use. operationId: allProductInfo parameters: - $ref: '#/parameters/header.Pididle' - $ref: '#/parameters/header.Organization' - $ref: '#/parameters/header.Request-Id_2' - $ref: '#/parameters/header.Subscription-Id' - $ref: '#/parameters/header.Authorization' - $ref: '#/parameters/query.email' consumes: - application/json produces: - application/json responses: '200': $ref: '#/responses/AllProducts' '400': $ref: '#/responses/BadRequest_2' '401': $ref: '#/responses/Unauthorized_2' '403': $ref: '#/responses/Forbidden_2' '503': $ref: '#/responses/ServiceUnavailable' tags: - query externalDocs: description: Find more info here. url: https://swagger.io /all-product-info/{productNumber}: get: tags: - query summary: Specific Product description: Find a specific product. operationId: productInformation parameters: - $ref: '#/parameters/header.Pididle' - $ref: '#/parameters/header.Organization' - $ref: '#/parameters/path.productNumber' - $ref: '#/parameters/header.Request-Id_2' - $ref: '#/parameters/header.Subscription-Id' - $ref: '#/parameters/header.Authorization' consumes: - application/json produces: - application/json responses: '200': $ref: '#/responses/PathProductNumber' '400': $ref: '#/responses/BadRequest_2' '401': $ref: '#/responses/Unauthorized_2' '403': $ref: '#/responses/Forbidden_2' '503': $ref: '#/responses/ServiceUnavailable' /all-product-info/{productNumber}/product-size: get: tags: - query summary: Specific Product Description description: Find the description for a specific product. operationId: productDescription parameters: - $ref: '#/parameters/path.productNumber' - $ref: '#/parameters/header.Request-Id_2' - $ref: '#/parameters/header.Subscription-Id' - $ref: '#/parameters/header.Authorization' consumes: - application/json produces: - application/json responses: '200': $ref: '#/responses/ProductSize' '400': $ref: '#/responses/BadRequest_2' '401': $ref: '#/responses/Unauthorized_2' '403': $ref: '#/responses/Forbidden_2' '503': $ref: '#/responses/ServiceUnavailable' /ping: get: tags: - query summary: Server heartbeat operation description: Solutions can use this operation to check that the server is still available and responding to requests. operationId: healthMonitor parameters: - $ref: '#/parameters/header.Request-Id_2' - $ref: '#/parameters/header.Subscription-Id' - $ref: '#/parameters/header.Authorization' consumes: - application/json produces: - application/json responses: '200': $ref: '#/responses/Ping' '400': $ref: '#/responses/BadRequest_2' '401': $ref: '#/responses/Unauthorized_2' '403': $ref: '#/responses/Forbidden_2' '503': $ref: '#/responses/ServiceUnavailable' definitions: AllProducts: description: This endpoint gives the information on all of the products. type: object properties: products: type: array items: type: object properties: name: type: string description: The name of the pet id: type: string productSize: type: object properties: name: type: string number: type: integer location: type: string productSize: type: object properties: productWidth: type: string productHeight: type: string productWeight: type: string links: type: object properties: self: type: object properties: href: type: string method: type: string thisProductInfo: type: object properties: href: type: string method: type: string thisProductSize: type: object properties: href: type: string method: type: string ping: type: object properties: href: type: string method: type: string required: - products example: products: - name: Gasket id: G45k3T number: 4960 location: 8601 Ranch to Market 2222 Building 1 Austin, TX 78730 ProductSize: productWidth: 4 inches productHeight: 1.8 cm productLength: 4 inches productWeight: 22 g - name: Chasis id: Ch4515 number: 8321 location: CDK Global, 1 Cygnet Way, Charnham Park, Hungerford RG17 0YL, UK ProductSize: productWidth: 7 ft productHeight: 1 ft productLength: 12 ft productWeight: 250 lbs - name: Steering Wheel id: 5T3eR1Ng Wh331 number: 7629 location: 2525 SW 1st Ave Suite 400, Portland, OR 97201 ProductSize: productWidth: 14 1/2 inches productHeight: 3 5/8 inches productLength: 14 1/2 inches productWeight: 385 grams - name: Engine id: 3Ng1N9 number: 2385 location: 1950 Hassell Rd, Hoffman Estates, IL 60169 ProductSize: productWidth: 28 inches productHeight: 27 inches productLength: 26 inches productWeight: 411 lbs. - name: Radiator id: R4d14t0R number: 3897 location: 9th & 10th floor, Binarius Building, Deepak Complex National Games Road, Opp Golf Course, Shastrinagar, Yerawada, Pune, Maharashtra 411006, India ProductSize: productWidth: 19-3/4 inches productHeight: 19-1/8" inches productLength: 2-3/16 productWeight: 17.8 lbs. links: self: href: /all-product-info method: GET thisProductInfo: href: /all-product-info/{productNumber} method: GET thisProductSize: href: '' method: /all-product-info/{productNumber}/product-size ping: href: /ping method: GET BaseCollection: description: This field describes the base collection. type: object properties: totalItems: type: number description: The total number of items contained in the collection totalPages: type: number description: The total number of pages given the requested page size links: $ref: '#/definitions/BaseCollectionLinks' required: - totalItems - totalPages - links example: totalItems: 16 totalPages: 4 links: first: href: https://example.com/first rel: first method: POST title: First page next: href: https://example.com/next rel: next method: POST title: Next page prev: href: https://example.com/prev rel: prev method: POST title: Previous page Measurement: description: This field will let you know about the value and the units of measurement. type: object required: - units - value properties: value: type: number units: type: string enum: - MILES - KM - HOURS example: value: 75201 units: MILES BaseCollectionLinks: description: This field describes the base collection links for the particular endpoint. type: object properties: next: $ref: '#/definitions/LinkDescriptionObject' description: The next page of query results prev: $ref: '#/definitions/LinkDescriptionObject' description: The previous page of query results first: $ref: '#/definitions/LinkDescriptionObject' description: The first page of query results required: - first example: next: href: https://example.com/next rel: next method: POST title: Next page prev: href: https://example.com/prev rel: prev method: POST title: Previous page first: href: https://example.com/first rel: first method: POST title: First page Price: description: This field lists the cost of the appointment. type: object properties: currencyCode: type: string description: The ISO 4217 three letter currency code of the price netPrice: type: number description: Price excluding sales tax / VAT expressed in the given currency grossValue: type: number description: Price including sales tax / VAT expressed in the given currency taxValue: type: number description: Value of tax expressed in the given currency taxRate: type: number description: Tax rate as a percentage netDiscountedPrice: type: number description: Discounted price exluding sales tax in the given currency grossDiscountedPrice: type: number description: Discounted price including sales tax in the given currency required: - currencyCode - netPrice - grossValue - taxValue - taxRate example: currencyCode: US netPrice: 53 grossValue: 57.24 taxValue: 4.24 taxRate: 8 AppointmentCollection: description: This field describes a collection of appointments. type: object allOf: - $ref: '#/definitions/BaseCollection' - properties: items: type: object items: $ref: '#/definitions/Appointment' required: - items required: - items example: items: appointmentId: '123' dateTime: '2019-06-10T16:15:00+08:00' requestedServices: - description: Filler, Tail Lamp Center - Replace (Labor Only) sourceHref: api.fortellis.io/service/reference/v4/service-packages/model/CHEV-CAMAC-2001-US/packages/BF018/specifications/8994972 vehicleHref: api.fortellis.io/service/v1/vehicles/123 vehicleMileage: value: 75201 units: MILES customerHref: api.fortellis.io/service/v1/customers/123 contact: label: mobile uri: tel:1-234-567-8900 preferences: - startDay: MON endDay: FRI startTime: '1000' endTime: '1600' transportHref: api.fortellis.io/service/v1/scheduling/lookups/transports/123 advisorHref: api.fortellis.io/service/v1/scheduling/lookups/advisors/123 concerns: My driver side front door rattles when I drive faster than 45 remarks: Customer reports that driver side front door exhibits a rattle above 45mph links: self: href: api.fortellis.io/service/v3/appointments/123 totalItems: 1 totalPages: 1 links: first: href: api.fortellis.io/service/v3/appointments?page=1&pageSize=1 AppointmentResource: description: This field describes the appointment resources. allOf: - $ref: '#/definitions/Appointment' - type: object properties: appointmentId: type: string description: The appointment unique identifier links: $ref: '#/definitions/AppointmentLinks' description: The hypermedia links of the Appointment resource required: - appointmentId - links example: appointmentId: '123' dateTime: '2019-06-10T16:15:00+08:00' requestedServices: - description: Filler, Tail Lamp Center - Replace (Labor Only) sourceHref: api.fortellis.io/service/reference/v4/service-packages/model/CHEV-CAMAC-2001-US/packages/BF018/specifications/8994972 vehicleHref: api.fortellis.io/service/v1/vehicles/123 vehicleMileage: value: 34760 units: MILES customerHref: api.fortellis.io/service/v1/customers/123 contact: label: mobile uri: tel:1-234-567-8900 preferences: items: startDay: - MON endDay: - SAT startTime: '1985-04-12T23:20:50.52Z' endTime: '1985-04-18T23:20:50.52Z' timezone: CST transportHref: api.fortellis.io/service/v1/scheduling/lookups/transports/123 advisorHref: api.fortellis.io/service/v1/scheduling/lookups/advisors/123 concerns: My driver side front door rattles when I drive faster than 45 remarks: Customer reports that driver side front door exhibits a rattle above 45mph links: self: href: api.fortellis.io/service/v3/appointments/123 PathProductNumber: description: This gives you the unique identifier for the product. type: object properties: name: type: string id: type: string number: type: integer location: type: string productSize: type: object properties: productWidth: type: string productHeight: type: string productWeight: type: string links: type: object properties: self: type: object properties: href: type: string method: type: string allProductInfo: type: object properties: href: type: string method: type: string thisProductSize: type: object properties: href: type: string method: type: string ping: type: object properties: href: type: string method: type: string required: - id - name - links example: name: Radiator id: SomeExampleId number: 5 location: 9th & 10th floor, Binarius Building, Deepak Complex National Games Road, Opp Golf Course, Shastrinagar, Yerawada, Pune, Maharashtra 411006, India ProductSize: productWidth: 19-3/4 inches productHeight: 19-1/8 inches productLength: 2-3/16 productWeight: 17.8 lbs. links: self: href: /all-product-info/{productNumber} method: GET allProductInfo: href: /all-product-info method: GET thisProductSize: href: /all-product-info/all-product-info/{productNumber}/product-size method: GET ping: href: /ping method: GET ProductSize: description: This describes the dimensions of the product to help determine if you have the space to store the product. type: object properties: productWidth: type: string productHeight: type: string productLength: type: string productWeight: type: string links: type: object properties: self: type: object properties: href: type: string method: type: string allProductInfo: type: object properties: href: type: string method: type: string thisProductInfo: type: object properties: href: type: string method: type: string ping: type: object properties: href: type: string method: type: string required: - productWidth - productHeight - productLength - productWeight - links example: productWidth: 4 inches productHeight: 1.8 cm productLength: 4 inches productWeight: 22 g links: self: href: /all-product-info/all-product-info/{productNumber}/product-size method: GET allProductInfo: href: /all-product-info method: GET thisProductInfo: href: /all-product-info/{productNumber} method: GET ping: href: /ping method: GET ContactMethod: description: This is the method that the customer would like you to use to contact them. type: object properties: label: type: string description: A label used to describe the contact method (e.g. home, work-cell). uri: type: string description: The RFC 3986 encoded URI address of the contact method. preferences: type: object items: $ref: '#/definitions/ContactPreference' required: - label - uri example: label: Home Information uri: https://examle.com/person/contact preferences: items: startDay: - MON endDay: - SAT startTime: '1985-04-12T23:20:50.52Z' endTime: '1985-04-18T23:20:50.52Z' timezone: CST Health: description: This is the code that tells you the server is okay. type: object properties: message: type: string code: type: number links: type: object properties: self: type: object properties: href: type: string method: type: string allProductInfo: type: object properties: href: type: string method: type: string thisProductInfo: type: object properties: href: type: string method: type: string thisProductSize: type: object properties: href: type: string method: type: string required: - message - code - links example: message: The server is up code: 200 links: self: href: /ping method: GET allProductInfo: href: /all-product-info method: GET thisProductInfo: href: /all-product-info/{productNumber} method: GET thisProductSize: href: /all-product-info/{productNumber}/product-size method: GET VehicleSpecification: description: This field describes the vehicle. type: object properties: makeCode: type: string description: The make code of the vehicle modelCode: type: string description: The model code of the vehicle modelYear: type: number description: The model year of the vehicle required: - makeCode - modelCode - modelYear example: makeCode: CHEV modelCode: CAMAC modelYear: 2001 RequestedService: description: This fields describes the service requested. type: object properties: description: type: string description: The textual description of the requested service concern: type: string description: The textual description of the concern that prompted the requested service sourceHref: type: string description: "The hypermedia link to the source service specification. This will \nlink to a service-packages Specification or LaborOperation resource.\n" overrides: type: object properties: quote: $ref: '#/definitions/Price' required: - description example: description: Replace Air Filter sourceHref: api.fortellis.io/service/reference/v4/service-packages/model/CHEV-CAMAC-2001-US/packages/BF018/specifications/8994972 Appointment: description: This definition defines the information and format in appointments. properties: dateTime: type: string description: The ISO 8601 encode date and time of the appointment requestedServices: type: array items: $ref: '#/definitions/RequestedService' description: The requested services to be performed on the vehicle vehicleHref: type: string description: The hyperlink to the Vehicle resource scheduled for the appointment. vehicleSpec: $ref: '#/definitions/VehicleSpecification' description: The make, model, and year describing the vehicle to be serviced. This must be provided if the 'vehicleHref' property is not specified. vehicleMileage: $ref: '#/definitions/Measurement' description: The estimated mileage of the vehicle customerHref: type: string description: The hyperlink to the customer who is requesting the vehicle service contact: $ref: '#/definitions/ContactMethod' description: "A contact method for the customer. This takes precedence over contact \nmethods present in the source customer record. This must be provided \nif a customer resource link is not included.\n" transportHref: type: string description: The hyperlink to the requested transport advisorHref: type: string description: The hyperlink to the requested service advisor teamHref: type: string description: The hyperlink to the requested service team concerns: type: string description: Concerns of the customer that prompted the appointment remarks: type: string description: Comments by the service department staff about the appointment required: - dateTime - requestedServices example: dateTime: '2019-06-10T16:15:00+08:00' requestedServices: - description: Filler, Tail Lamp Center - Replace (Labor Only) sourceHref: api.fortellis.io/service/reference/v4/service-packages/model/CHEV-CAMAC-2001-US/packages/BF018/specifications/8994972 vehicleHref: api.fortellis.io/service/v1/vehicles/123 vehicleMileage: value: 34760 units: MILES customerHref: api.fortellis.io/service/v1/customers/123 contact: label: mobile uri: tel:1-234-567-8900 preferences: items: startDay: - MON endDay: - SAT startTime: '1985-04-12T23:20:50.52Z' endTime: '1985-04-18T23:20:50.52Z' timezone: CST transportHref: api.fortellis.io/service/v1/scheduling/lookups/transports/123 advisorHref: api.fortellis.io/service/v1/scheduling/lookups/advisors/123 concerns: My driver side front door rattles when I drive faster than 45 remarks: Customer reports that driver side front door exhibits a rattle above 45mph AppointmentLinks: description: This field describes the appointment links. type: object properties: self: $ref: '#/definitions/LinkDescriptionObject' description: The canonical link to the appointment resource required: - self example: self: href: api.fortellis.io/service/v3/appointments/123 ContactPreference: description: This fields shows the customer's contact preferences. type: object required: - startDay - endDay properties: startDay: type: string enum: - MON - TUE - WED - THU - FRI - SAT - SUN description: The starting day of the interval endDay: type: string enum: - MON - TUE - WED - THU - FRI - SAT - SUN description: The ending day of the interval startTime: type: string description: The RFC 3339 encoded starting time of the interval endTime: type: string description: The RFC 3339 encoded ending time of the interval timeZone: type: string description: The IANA Timezone Database encoded timezone code of the interval example: startDay: MON endDay: SAT startTime: '1985-04-12T23:20:50.52Z' endTime: '1985-04-18T23:20:50.52Z' timezone: CST LinkDescriptionObject: description: These are the linked objects that you send with the request to comply with HATEOAS. type: object properties: href: type: string description: The target URI rel: type: string description: The link relation type method: type: string description: The HTTP verb that MUST be used to make a request to the target of the link title: type: string description: A human readable title for the link that conveys the purpose of the link required: - href example: href: https://example.com rel: self method: POST title: Reference to self at the Example ErrorResponse: description: This is a generic error schema. type: object properties: code: type: integer format: int32 message: type: string required: - code - message example: code: 24 message: Error Message used for debugging ErrorResponse_2: description: Common error response object. properties: code: type: integer format: int32 message: type: string required: - code - message example: code: 400 message: Bad Request parameters: header.Accept-Language: description: This header describes the languages that the client accepts. name: Accept-Language in: header type: string path.appointmentId: name: appointmentId in: path required: true type: string description: The appointment identifier header.Authorization: name: Authorization in: header required: true type: string format: guid description: Provides authorization to access Fortellis APIs. For calling a Fortellis Provider, this must be an OAuth 2.0 token issued by the Fortellis authorization server, but you may call the simulator platform with Basic Authorization using your API key and secret. path.productNumber: name: productNumber in: path description: Filters for a specific product required: true type: number header.Prefer: description: This header describes the preferences of the client calling the API. name: Prefer in: header type: string enum: - return=representation - return=minimal query.vehicleHref: name: vehicleHref in: query required: false type: string description: The vehicle resource hyperlink to filter query results header.Subscription-Id: name: Subscription-Id in: header required: true type: string format: guid description: The Fortellis Marketplace subscription identifier between a user entity and the solution. For sample responses use the Subscription-Id 'test'. header.Request-Id_2: name: Request-Id in: header required: true type: string format: guid description: A correlation ID that should be returned back to the caller to indicate the return of the given request query.advisorHref: name: advisorHref in: query required: false type: string description: The advisor resource hyperlink to filter query results query.dateTimeInterval: name: dateTimeInterval in: query required: false type: string description: The ISO 8601 data and time interval to filter the appointment query header.Organization: name: Organization in: header description: Identifies the organization that the user is in required: true type: string header.Request-Id: name: Request-Id in: header required: true type: string format: guid description: You must include the Request-Id in every call to track the same call across systems. header.If-Match: name: If-Match in: header type: string description: Specifies a conditional request to only return the resource when it does match one of the included ETag values query.customerHref: name: customerHref in: query required: false type: string description: The customer resource hyperlink to filter query results header.Accept-Charset: description: This header describes the characters that the client will accept. name: Accept-Charset in: header type: string enum: - utf-8 header.Accept: description: This header describes the characters that the API will accept. name: Accept in: header type: string enum: - application/json header.If-None-Match: name: If-None-Match in: header type: string description: Specifies a conditional request to only return the resource when it doesn't match one of the included ETag values query.email: name: email in: query description: Filters customers by email address type: string header.Pididle: name: User-Id in: header description: Identifies the user accessing the account required: true type: string responses: Forbidden_2: description: 403 - Forbidden headers: Request-Id: type: string schema: $ref: '#/definitions/ErrorResponse_2' AllProducts: description: This sends a response with all the products, their size, and their location. headers: Request-Id: type: string schema: $ref: '#/definitions/AllProducts' Unauthorized: description: 401 - Unauthorized headers: Content-Language: type: string Content-Type: type: string Request-Id: type: string schema: $ref: '#/definitions/ErrorResponse' Forbidden: description: 403 - Forbidden headers: Content-Language: type: string Content-Type: type: string Request-Id: type: string schema: $ref: '#/definitions/ErrorResponse' BadRequest: description: 400 - Bad Request headers: Content-Language: type: string Content-Type: type: string Request-Id: type: string schema: $ref: '#/definitions/ErrorResponse' ServiceUnavailable: description: 503 - Service Unavailable headers: Request-Id: type: string schema: $ref: '#/definitions/ErrorResponse_2' Ping: description: 200 - OK headers: Request-Id: type: string schema: $ref: '#/definitions/Health' AppointmentCollection: description: OK headers: Request-Id: type: string schema: $ref: '#/definitions/AppointmentCollection' Unauthorized_2: description: 401 - Unauthorized headers: Request-Id: type: string schema: $ref: '#/definitions/ErrorResponse_2' PathProductNumber: description: This sends the information on a particular product based on the product number. headers: Request-Id: type: string schema: $ref: '#/definitions/PathProductNumber' NotFound: description: 404 - Not Found headers: Content-Language: type: string Content-Type: type: string Request-Id: type: string schema: $ref: '#/definitions/ErrorResponse' ProductSize: description: This sends the product size for a particular product to help you determine if you have the inventory space for that product. headers: Request-Id: type: string schema: $ref: '#/definitions/ProductSize' Appointment: description: OK headers: Request-Id: type: string Preference-Applied: type: string enum: - return=representation - return=minimal schema: $ref: '#/definitions/AppointmentResource' BadRequest_2: description: 400 - Bad Request headers: Request-Id: type: string schema: $ref: '#/definitions/ErrorResponse_2' securityDefinitions: permission-model: type: oauth2 flow: implicit authorizationUrl: https://identity.fortellis.io/oauth2/ scopes: anonymous: Create, Query, Update, and Delete appointments