openapi: 3.2.0 info: version: '2018-07-16' title: Kelley Blue Book(SM) Instant Cash Offer (ICO) Prospect API description: All methods related to a prospect servers: - url: https://api.kbb.com/ico/v1 security: - keyQuery: [] tags: - name: Prospect description: All methods related to a prospect paths: /prospects: post: description: Creates a new vehicle prospect. security: - keyQuery: [] tags: - Prospect parameters: - $ref: '#/components/parameters/apiKey' responses: 201: description: Successful response content: application/json: schema: allOf: - $ref: '#/components/schemas/Response' - type: object required: - data properties: meta: type: object properties: codes: type: array items: type: integer enum: - 201000 - 200422 description: '200100 - Prospect created. 200422 - Mileage exceeds offer eligibility threshold. ' data: $ref: '#/components/schemas/Prospect' 400: description: Error response content: application/json: schema: type: object required: - meta properties: meta: type: object properties: codes: type: array items: type: integer description: "400001 - Invalid schema.\n400010 - Invalid vehicle configuration.\n400011 - Unavailable vehicle Year.\n400012 - Unavailable vehicle Make.\n400013 - Unavailable vehicle Model.\n400014 - Unavailable vehicle Trim.\n400015 - Unavailable vehicle Transmission.\n400016 - Unavailable vehicle Engine.\n400017 - Unavailable vehicle Drivetrain.\n400018 - Unavailable vehicle Color.\n400020 - Zip code not servicable.\n400022 - Prospect vehicle does not match VIN decode vehicle. \n400030 - Unavailable Dealer.\n" enum: - 400001 - 400010 - 400011 - 400012 - 400013 - 400014 - 400015 - 400016 - 400017 - 400018 - 400020 - 400022 - 400030 403: $ref: '#/components/responses/InvalidAuth' 500: $ref: '#/components/responses/ServerError' requestBody: content: application/json: schema: $ref: '#/components/schemas/ProspectRequest' required: true summary: Create prospects x-summary-source: derived operationId: postProspects x-operation-id-source: derived options: security: - keyQuery: [] tags: - Prospect responses: default: description: Allowed origins, methods, and headers headers: Access-Control-Allow-Headers: schema: type: string default: Content-Type Access-Control-Allow-Methods: schema: type: string default: POST Access-Control-Allow-Origin: schema: type: string default: '*' summary: Describe prospects x-summary-source: derived operationId: optionsProspects x-operation-id-source: derived /prospects/{prospectId}: get: description: Gets the state of the current prospect parameters: - $ref: '#/components/parameters/apiKey' - $ref: '#/components/parameters/prospectId' - $ref: '#/components/parameters/include' - $ref: '#/components/parameters/exclude' security: - keyQuery: [] tags: - Prospect responses: 200: description: TBD content: application/json: schema: allOf: - $ref: '#/components/schemas/Response' - type: object required: - data properties: meta: type: object properties: codes: type: array items: type: integer enum: - 200000 data: $ref: '#/components/schemas/Prospect' 404: description: Prospect not found content: application/json: schema: type: object required: - meta properties: meta: type: object properties: codes: type: array items: type: integer enum: - 404000 description: '404000 - Prospect not found. ' 403: $ref: '#/components/responses/InvalidAuth' 500: $ref: '#/components/responses/ServerError' summary: Get prospects by prospect id x-summary-source: derived operationId: getProspectsByProspectId x-operation-id-source: derived options: security: - keyQuery: [] tags: - Prospect parameters: - $ref: '#/components/parameters/prospectId' responses: default: description: Allowed origins, methods, and headers headers: Access-Control-Allow-Headers: schema: type: string default: Content-Type Access-Control-Allow-Methods: schema: type: string default: GET Access-Control-Allow-Origin: schema: type: string default: '*' summary: Describe prospects by prospect id x-summary-source: derived operationId: optionsProspectsByProspectId x-operation-id-source: derived /prospects/{prospectId}/history: get: description: Gets the required history specific condition questions for a given vehicle prospect security: - keyQuery: [] tags: - Prospect parameters: - $ref: '#/components/parameters/apiKey' - $ref: '#/components/parameters/prospectId' - $ref: '#/components/parameters/include' - $ref: '#/components/parameters/exclude' - $ref: '#/components/parameters/filter' responses: 200: description: Returns a set of condition questions content: application/json: schema: allOf: - $ref: '#/components/schemas/Response' - type: object required: - data properties: data: $ref: '#/components/schemas/Questions' 404: description: Prospect not found content: application/json: schema: type: object required: - meta properties: meta: type: object properties: codes: type: array items: type: integer enum: - 404000 description: '404000 - Prospect not found. ' 403: $ref: '#/components/responses/InvalidAuth' 500: $ref: '#/components/responses/ServerError' summary: Get prospects by prospect id history x-summary-source: derived operationId: getProspectsByProspectIdHistory x-operation-id-source: derived patch: description: Change history information associated with the prospect security: - keyQuery: [] tags: - Prospect parameters: - $ref: '#/components/parameters/apiKey' - $ref: '#/components/parameters/prospectId' responses: 200: description: Returns the successfully changed history questions content: application/json: schema: allOf: - $ref: '#/components/schemas/Response' - type: object required: - data properties: meta: type: object required: - codes properties: codes: type: array items: type: integer enum: - 200000 description: 200000 - All questions answered. data: $ref: '#/components/schemas/Questions' 400: description: Error response content: application/json: schema: type: object required: - meta properties: meta: type: object properties: codes: type: array items: type: integer enum: - 400001 - 400050 - 400051 - 400052 - 400053 - 400054 - 400055 - 400056 - 400057 - 400058 description: '400001 - Invalid schema 400050 - Invalid Vehicle Ownership answer. 400051 - Invalid Vehicle title answer. 400052 - Invalid Vehicle history report answer. 400053 - Invalid Vehicle insurance claim answer. 400054 - Invalid Vehicle odor answer. 400055 - Invalid Vehicle service records answer. 400056 - Invalid Vehicle key set answer. 400057 - Invalid Vehicle auto auction answer. 400058 - Invalid Vehicle rental answer. ' 404: description: Prospect not found content: application/json: schema: type: object required: - meta properties: meta: type: object properties: codes: type: array items: type: integer description: '404000 - Prospect not found. ' enum: - 404000 403: $ref: '#/components/responses/InvalidAuth' 500: $ref: '#/components/responses/ServerError' requestBody: content: application/json: schema: $ref: '#/components/schemas/QuestionsRequest' required: true summary: Update prospects by prospect id history x-summary-source: derived operationId: patchProspectsByProspectIdHistory x-operation-id-source: derived options: security: - keyQuery: [] tags: - Prospect parameters: - $ref: '#/components/parameters/prospectId' responses: default: description: Allowed origins, methods, and headers headers: Access-Control-Allow-Headers: schema: type: string default: Content-Type Access-Control-Allow-Methods: schema: type: string default: GET,PATCH Access-Control-Allow-Origin: schema: type: string default: '*' summary: Describe prospects by prospect id history x-summary-source: derived operationId: optionsProspectsByProspectIdHistory x-operation-id-source: derived /prospects/{prospectId}/options: patch: description: Change option information associated with the prospect security: - keyQuery: [] tags: - Prospect parameters: - $ref: '#/components/parameters/apiKey' - $ref: '#/components/parameters/prospectId' - $ref: '#/components/parameters/include' - $ref: '#/components/parameters/exclude' - $ref: '#/components/parameters/filter' - $ref: '#/components/parameters/count' responses: 200: description: Returns any changed options content: application/json: schema: allOf: - $ref: '#/components/schemas/Response' - type: object required: - data properties: data: $ref: '#/components/schemas/Options' 400: description: Error response content: application/json: schema: type: object required: - meta properties: meta: type: object properties: codes: type: array items: type: integer enum: - 400001 - 400060 description: '400001 - Invalid schema. 400060 - Invalid Vehicle option setting. ' 404: description: Prospect not found content: application/json: schema: type: object required: - meta properties: meta: type: object properties: codes: type: array items: type: integer description: '404000 - Prospect not found ' enum: - 404000 403: $ref: '#/components/responses/InvalidAuth' 500: $ref: '#/components/responses/ServerError' requestBody: content: application/json: schema: $ref: '#/components/schemas/OptionsRequest' required: true summary: Update prospects by prospect id options x-summary-source: derived operationId: patchProspectsByProspectIdOptions x-operation-id-source: derived options: security: - keyQuery: [] parameters: - $ref: '#/components/parameters/prospectId' tags: - Prospect responses: default: description: Allowed origins, methods, and headers headers: Access-Control-Allow-Headers: schema: type: string default: Content-Type Access-Control-Allow-Methods: schema: type: string default: PATCH Access-Control-Allow-Origin: schema: type: string default: '*' summary: Describe prospects by prospect id options x-summary-source: derived operationId: optionsProspectsByProspectIdOptions x-operation-id-source: derived /prospects/{prospectId}/conditions: get: description: Gets the condition questions for a given vehicle prospect security: - keyQuery: [] tags: - Prospect parameters: - $ref: '#/components/parameters/apiKey' - $ref: '#/components/parameters/prospectId' - $ref: '#/components/parameters/include' - $ref: '#/components/parameters/exclude' - $ref: '#/components/parameters/filter' - $ref: '#/components/parameters/count' responses: 200: description: Returns a set of condition questions content: application/json: schema: allOf: - $ref: '#/components/schemas/Response' - type: object required: - data properties: data: $ref: '#/components/schemas/Questions' 404: description: Prospect not found content: application/json: schema: type: object required: - meta properties: meta: type: object properties: codes: type: array items: type: integer description: '404000 - Prospect not found. ' enum: - 404000 403: $ref: '#/components/responses/InvalidAuth' 500: $ref: '#/components/responses/ServerError' summary: Get prospects by prospect id conditions x-summary-source: derived operationId: getProspectsByProspectIdConditions x-operation-id-source: derived patch: description: Modifies the condition of the vehicle propsect security: - keyQuery: [] tags: - Prospect parameters: - $ref: '#/components/parameters/apiKey' - $ref: '#/components/parameters/prospectId' - $ref: '#/components/parameters/include' - $ref: '#/components/parameters/exclude' - $ref: '#/components/parameters/filter' - $ref: '#/components/parameters/count' responses: 200: description: Returns a set of condition questions content: application/json: schema: allOf: - $ref: '#/components/schemas/Response' - type: object required: - data properties: data: $ref: '#/components/schemas/Questions' 400: description: Error response content: application/json: schema: type: object required: - meta properties: meta: type: object properties: codes: type: array items: type: integer enum: - 400001 - 400074 - 400106 description: '400001 - Invalid schema. 400074 - Condition question not accepting comment. 400106 - Invalid Vehicle condition value. ' 404: description: Prospect not found content: application/json: schema: type: object required: - meta properties: meta: type: object properties: codes: type: array items: type: integer description: '404000 - Prospect not found. ' enum: - 404000 403: $ref: '#/components/responses/InvalidAuth' 500: $ref: '#/components/responses/ServerError' requestBody: content: application/json: schema: $ref: '#/components/schemas/QuestionsRequest' required: true summary: Update prospects by prospect id conditions x-summary-source: derived operationId: patchProspectsByProspectIdConditions x-operation-id-source: derived options: security: - keyQuery: [] tags: - Prospect parameters: - $ref: '#/components/parameters/prospectId' responses: default: description: Allowed origins, methods, and headers headers: Access-Control-Allow-Headers: schema: type: string default: Content-Type Access-Control-Allow-Methods: schema: type: string default: GET,PATCH Access-Control-Allow-Origin: schema: type: string default: '*' summary: Describe prospects by prospect id conditions x-summary-source: derived operationId: optionsProspectsByProspectIdConditions x-operation-id-source: derived /prospects/{prospectId}/contactInfo: get: description: Gets the prospect's contact information. parameters: - $ref: '#/components/parameters/apiKey' - $ref: '#/components/parameters/prospectId' security: - keyQuery: [] tags: - Prospect responses: 200: description: Contact Information content: application/json: schema: allOf: - $ref: '#/components/schemas/Response' - type: object required: - data properties: data: $ref: '#/components/schemas/ContactInfo' 404: description: Prospect not found content: application/json: schema: type: object required: - meta properties: meta: type: object properties: codes: type: array items: type: integer description: '404000 - Prospect not found. ' enum: - 404000 403: $ref: '#/components/responses/InvalidAuth' 500: $ref: '#/components/responses/ServerError' summary: Get prospects by prospect id contact info x-summary-source: derived operationId: getProspectsByProspectIdContactInfo x-operation-id-source: derived patch: description: Modifies the contact information for the prospect security: - keyQuery: [] tags: - Prospect parameters: - $ref: '#/components/parameters/apiKey' - $ref: '#/components/parameters/prospectId' responses: 200: description: Returns a set of lead content: application/json: schema: allOf: - $ref: '#/components/schemas/Response' - type: object required: - data properties: meta: type: object properties: codes: type: array items: type: integer enum: - 200000 description: 200000 - All questions answered. data: $ref: '#/components/schemas/ContactInfo' 400: description: Error response content: application/json: schema: type: object required: - meta properties: meta: type: object properties: codes: type: array items: type: integer enum: - 400001 - 400080 - 400081 - 400082 - 400083 - 400084 - 400085 - 400086 description: "400001 - Invalid schema\n400080 - Invalid first name answer\n400081 - Invalid last name answer\n400082 - Invalid email answer\n400083 - Invalid confirm email answer\n400084 - Invalid phone number answer\n400085 - Invalid legal acceptance answer\n400086 - Email and confirmation do not match \n" 404: description: Prospect not found content: application/json: schema: type: object required: - meta properties: meta: type: object properties: codes: type: array items: type: integer description: '404000 - Prospect not found ' enum: - 404000 403: $ref: '#/components/responses/InvalidAuth' 500: $ref: '#/components/responses/ServerError' requestBody: content: application/json: schema: $ref: '#/components/schemas/ContactInfoRequest' required: true summary: Update prospects by prospect id contact info x-summary-source: derived operationId: patchProspectsByProspectIdContactInfo x-operation-id-source: derived options: security: - keyQuery: [] tags: - Prospect parameters: - $ref: '#/components/parameters/prospectId' responses: default: description: Allowed origins, methods, and headers headers: Access-Control-Allow-Headers: schema: type: string default: Content-Type Access-Control-Allow-Methods: schema: type: string default: GET,PATCH Access-Control-Allow-Origin: schema: type: string default: '*' summary: Describe prospects by prospect id contact info x-summary-source: derived operationId: optionsProspectsByProspectIdContactInfo x-operation-id-source: derived /offers: post: description: Creates an offer from the Prospect security: - keyQuery: [] parameters: - $ref: '#/components/parameters/apiKey' - name: prospectId in: query required: true schema: type: string tags: - Prospect responses: 201: description: Returns an offer for the given vehicle prospect content: application/json: schema: allOf: - $ref: '#/components/schemas/Response' - type: object required: - data properties: data: $ref: '#/components/schemas/Offer' 400: description: Error response content: application/json: schema: type: object required: - meta properties: meta: type: object properties: codes: type: array items: type: integer enum: - 400091 - 400092 - 400093 - 400094 - 400110 description: '400091 - Vehicle history information questions have not been answered in full. 400092 - Contact information questions have not been answered in full. 400093 - Offer already processed 400094 - Unsupported Usage Detected 400110 - Invalid prospectId ' 403: $ref: '#/components/responses/InvalidAuth' 500: $ref: '#/components/responses/ServerError' summary: Create offers x-summary-source: derived operationId: postOffers x-operation-id-source: derived options: security: - keyQuery: [] tags: - Prospect parameters: - name: prospectId in: query required: true schema: type: string responses: default: description: Allowed origins, methods, and headers headers: Access-Control-Allow-Headers: schema: type: string default: Content-Type Access-Control-Allow-Methods: schema: type: string default: POST Access-Control-Allow-Origin: schema: type: string default: '*' summary: Describe offers x-summary-source: derived operationId: optionsOffers x-operation-id-source: derived components: schemas: ContactInfoRequest: type: object properties: firstName: type: string minLength: 1 maxLength: 50 lastName: type: string minLength: 1 maxLength: 50 email: type: string format: email confirmEmail: type: string format: email phone: type: string format: phone zip: type: string minLength: 1 maxLength: 5 legalAcceptance: type: boolean ProspectRequest: type: object required: - vehicle - mileage - dealerId properties: vehicle: $ref: '#/components/schemas/VehicleIdentity' mileage: type: integer minimum: 0 maximum: 1000000 dealerId: type: integer minimum: 0 incomingUrl: type: string VehicleIdentity: type: object required: - yearId - makeId - modelId - trimId - transmissionId - engineId - drivetrainId - colorId properties: yearId: type: integer minimum: 0 makeId: type: integer minimum: 0 modelId: type: integer minimum: 0 trimId: type: integer minimum: 0 transmissionId: type: integer minimum: 0 engineId: type: integer minimum: 0 drivetrainId: type: integer minimum: 0 colorId: type: integer minimum: 0 vin: type: string minLength: 0 maxLength: 17 Questions: description: An array of questions. type: array items: $ref: '#/components/schemas/Question' url: type: string pattern: ^(https?:\/\/)?[\w-]+\.[\w-]+(:\d+)?(\/)?\S*$ Options: description: An array of vehicle makes. type: array items: $ref: '#/components/schemas/Option' Prospect: type: object allOf: - $ref: '#/components/schemas/ProspectRequest' - type: object required: - prospectId - status properties: prospectId: type: string format: uuid status: type: string enum: - inProgress - submitted - canSubmit history: $ref: '#/components/schemas/Questions' options: $ref: '#/components/schemas/Options' conditions: $ref: '#/components/schemas/Questions' contactInfo: $ref: '#/components/schemas/ContactInfo' Question: allOf: - $ref: '#/components/schemas/QuestionRequest' - type: object discriminator: propertyName: questionType required: - questionId - questionType properties: questionId: type: string pattern: ^[a-zA-Z0-9\/]+$ tags: type: array items: type: string enum: - abs - aftermarket - air-bags - air-conditioning - alignment - alternator - anti-lock - battery - body - brakes - bumper - burns - cargo-bed - carpets - catalytic-converters - check-engine - clutch - cold-air-intake - comment - computer-chip - convertible - cracked - damage - dashboard - dealer - deck-lid - dent - deployed - ding - dock - door - drums - electrical - engine - exhaust - exterior - factory - factory-style - faded - fender - fifty - frame - front - functional - gate - glass - grille - hard-top - headers - headliner - heater - hood - hubcaps - included - inner - installed - interior - ipod - leaks - left - less - lift - lights - low-coolant - lowered - maintenance - major - makes-noise - manifolds - mechanical - minor - mirror - missing - modified - modified-install - module - molding - moon-roof - more - muffler - must - non-factory - non-functional - non-modified-install - non-original - not-included - odometer - oil-pressure - one-inch - original - other - overheats - pads - paint - panel - percent - performance - power - quarter - racing-style - rack - radiator - radio - rail - raised - rear - remote-start - removable - repair - repairable - replace - replaced - right - roadside-kit - roadster - rocker - roof - rotors - rust - satellite - seats - service-engine - shock - should - side - simulated - spoiler - stains - stars - steering - sun-roof - support - suspension - t-tops - tail - tears - thirty - tint - tires - top - tower - transmission - trim - tune-up - turbo-supercharger - two-inch - usb - vinyl - warning-light - wear - wear-tear - wheels - wheels-rims - window questionType: type: string enum: - YesNo - Text - Number - Enum label: type: string OptionsRequest: description: An Option with its selected value. type: array items: $ref: '#/components/schemas/OptionRequest' QuestionsRequest: description: An array of questions with their values. type: array items: $ref: '#/components/schemas/QuestionRequest' Option: allOf: - $ref: '#/components/schemas/OptionRequest' - type: object properties: displayName: type: string groupName: type: string Response: properties: meta: type: object required: - codes properties: codes: type: array items: type: integer minimum: 0 links: type: array items: type: object properties: rel: type: string enum: - required - optional - self - doc - deprecated - next - error href: type: string format: uri method: type: string enum: - GET - POST - PATCH properties: type: object templated: type: boolean uuid: type: string pattern: ^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$ OptionRequest: type: object required: - optionId - isSelected properties: optionId: type: integer minimum: 0 isSelected: type: boolean Offer: type: object allOf: - $ref: '#/components/schemas/Prospect' - type: object required: - offerId properties: offerId: $ref: '#/components/schemas/uuid' priceAdvisor: $ref: '#/components/schemas/url' amount: type: integer expirationDate: type: string format: date status: type: string enum: - ACTIVE - AUCTION - CHECK - CLEARED - CONFIRMED - EXPIRED - FR - GROUNDED - INELIGIBLE - INSPECTION - MODIFIED - PURCHASED - RECEIVED - SOLD QuestionRequest: allOf: - type: object required: - questionId properties: questionId: type: string pattern: ^[a-zA-Z0-9\/]+$ - type: object required: - value properties: value: type: boolean - type: object required: - value properties: value: type: string - type: object required: - value properties: value: type: number ContactInfo: allOf: - $ref: '#/components/schemas/ContactInfoRequest' - type: object properties: required: type: array description: This array of property names indicates which fields are required items: type: string enum: - firstName - lastName - email - confirmEmail - phone - legalAcceptance - zip responses: InvalidAuth: description: An unauthenticated operation has been attempted content: application/json: schema: $ref: '#/components/schemas/Response' ServerError: description: An internal server error has occured content: application/json: schema: $ref: '#/components/schemas/Response' parameters: prospectId: name: prospectId description: Unique identifier to represent all aspects of a prospective vehicle offer including vehicle configuration, condition, and contact info. in: path required: true x-valid: b0afc168-ff1d-4858-955e-4a375189ecdd x-invalid: afc168-ff1d-4858-955e-4a375189ecdd schema: type: string include: name: include in: query description: The fields that should be included in the returned object. required: false x-valid: foo x-invalid: 123 schema: type: string pattern: /([a-zA-Z]+),?/g exclude: name: exclude in: query description: The fields that should be included in the returned object. required: false x-valid: foo x-invalid: 123 schema: type: string pattern: /([a-zA-Z]+),?/g count: name: count in: query description: The number of items returned in a collection required: false x-valid: 100 x-invalid: -1 schema: type: integer default: 100 apiKey: name: api_key description: Unique identifier to authorize the request in: query required: true x-valid: b0afc168-ff1d-4858-955e-4a375189ecd0 x-invalid: afc168-ff1d-4858-955e-4a375189ecd schema: type: string filter: name: filter in: query description: A list of fields that should be filtered on required: false x-valid: foo=bar x-invalid: 123 schema: type: string pattern: /([a-zA-Z]+\:[a-zA-Z\,]+);?/g securitySchemes: keyQuery: type: apiKey name: api_key in: query