Home Services SPI

This document outlines the Service Provider Interface (SPI) for Home Services within the Category SDK framework. The SPI defines the contract that you can implement to integrate with Alexa+.

Namespace

The namespace for the Home Services SPI is com.amazon.alexa.homeservices.v1.

Interaction patterns

The Home Services SPI supports a number of customer-experience patterns. They fall into three categories — discovery (how the customer finds a professional), account management (how the customer's identity is connected to your platform), and booking (how the project is handed off after matching).

Discovery and account-management patterns can be combined. For example, a partner can support both BROWSE_AND_CHOOSE for some services and AUTO_MATCH for others, and either Account Linking or Automatic Account Matching as the account-management story.

Discovery Patterns

The discovery patterns describe how a customer finds the professional who will perform the project. Partners declare per-service which discovery patterns they support via the matchingStrategies field on the GetServices response.

Browse and Choose (Customer-led)

The customer describes a project, reviews matching professionals, picks one, and sends them a project request. This is the default discovery pattern (BROWSE_AND_CHOOSE).

For this pattern, you must implement the following operations: GetServices, GetServiceSpecification, ListProfessionals, MessageProfessional, and GetUserInfo.

1. Project Definition: The customer describes the project. Alexa+ calls GetServices to identify matching service categories, then GetServiceSpecification to retrieve the per-service form. Alexa+ conducts dynamic Q&A to collect the required details.

2. Search Professionals: Alexa+ calls ListProfessionals with the customer's zip code and project context. You return a ranked, paginated list with ratings, reviews, cost estimates, and response times.

3. Review Results: The customer reviews the professionals. Alexa+ supports voice-driven sorting and filtering by rating, response time, and cost.

4. Reach Out: The customer selects a professional. Alexa+ optionally calls GetUserInfo to retrieve customer details from your account, and then calls MessageProfessional to deliver the project request to the selected professional.

Auto-Match (Platform-led)

The customer does not browse or select a professional. Instead, your platform automatically matches a professional on the customer's behalf. This is the AUTO_MATCH discovery pattern. Browsing operations like ListProfessionals and MessageProfessional are not used in this pattern.

For this pattern, you must implement these operations: GetServices, GetServiceSpecification, CreateBooking, GetUserInfo.

1. Project Definition: Same as Browse and Choose — Alexa+ calls GetServices and GetServiceSpecification to identify matching services and collect project details through dynamic Q&A.

2. Time Selection: The customer picks a preferred appointment date and time.

3. Account Management: If needed, Alexa+ initiates account linking or automatic account matching.

4. Booking Estimate: Alexa+ calls CreateBooking with stage=ESTIMATE. You return estimated charges, policies (cancellation, rescheduling), and the customer's available payment instruments. You also return your own partnerBookingId.

5. Pre-Submit Confirmation: Alexa+ presents the estimate, taxes/fees, and cancellation policy. The customer selects a payment method and confirms.

6. Booking Confirmation: Alexa+ calls CreateBooking again with stage=CONFIRMATION, sending the same alexaBookingId along with your partnerBookingId and the chosen payment instrument.

The booking is tentative until a professional is matched. Alexa+ informs the customer and uses GetBooking to poll status until a professional is assigned.

Account-Management Patterns

The SPI supports two account-management patterns. Partners can support either or both.

Account Linking

The traditional OAuth-based linking flow. When the customer needs to be linked to the partner, Alexa+ initiates account linking via the Alexa permissions framework. The customer sees a QR code on screened devices and a notification on the Alexa mobile app, completes the OAuth flow on a second screen, and returns to the conversation. After linking, Alexa+ can call partner endpoints with the user's access token and retrieve partner-side profile data via GetUserInfo.

Automatic Account Matching

For partners that support it, Alexa+ shares the customer's consented contact information directly with the partner via the userInfo field on MessageProfessional and the booking operations. The partner uses this information to match the customer to an existing account — or to auto-create one server-side — without requiring the customer to go through OAuth.

The customer experience differs from traditional Account Linking in that there is no QR code, no OAuth round-trip, and no second-screen step.

Booking Patterns

Booking patterns describe how the customer's project is handed off after the customer has selected (or been matched with) a professional.

Messaging

Messaging is the default lead-generation pattern, used by the majority of partners. After Alexa+ collects the project details and the customer selects a professional, Alexa+ sends a message to the chosen professional via MessageProfessional. The professional then reaches out to the customer through their own channels to schedule and complete the work.

This is the pattern that pairs naturally with the Browse and Choose discovery pattern. There is no booking-lifecycle state to track on the Alexa side — once the MessageProfessional call succeeds, the partner-side workflow takes over.

Operations

The Home Services SPI supports the following operations. Alexa+ performs permission checks and account linking checks at runtime before running the SPIs.

GetServices

Path: /v1/homeservices/services
Method: GET
Type: Read-only
Account Linking: Not applicable
Applicable interaction patterns: Auto-Match and Browse and Choose

Retrieves an optionally ranked list of supported services such as plumbing, house cleaning, appliance repair, based on a natural language description of a customer's project.

Amazon offers two service selection patterns:

A: Partner-driven selection

You define your service categories and select which category applies to each customer request. This option gives you the flexibility to define service categories that most closely align with your business and your existing service offerings. You influence Alexa's decision by providing a short list, or a single service, with a confidence score greater than 0 and up to 1. If you provide a single service, Alexa+ uses this service. If you return multiple services, Alexa+ attempts to select the service that best matches the request taking into consideration the confidence scores.

B: Alexa+-driven selection

You define your service categories and Alexa+ selects which categories apply to each customer request, based on a natural language description of your customer's project. You can return a list of all services you support, regardless of the project description, and set the confidence score to 0 for each service. Alexa+ then selects one of the services you return, using a best effort to match the project description to the description of each service you offer.

The confidence scores are defined in Service.

The GetServices operation takes input GetServicesRequest and generates output GetServicesResponse.

Request

Response

A successful GetServicesResponse returns a ranked list of supported services available to service the customer's project.

If the response includes no services, Alexa+ interprets this response to indicate your services don't support the customer's project. If the response includes more than one service, Alexa+ selects the best matching service from the list. It considers the description of each service and the confidence values you provide. If the response includes a single service with a confidence score greater than 0.0, Alexa+ interprets this response to indicate that you can support the customer's project and that the service included in the response is the best match for the request.

On error, the response returns one of the following error codes:

• 400 ValidationExceptionResponse

• 400 ClientErrorResponse

• 408 RequestTimeoutErrorResponse

• 429 RequestThrottlingErrorResponse

• 500 InternalServerErrorResponse

GetServiceSpecification

Path: /v1/homeservices/services/{serviceId}/specification
Method: GET
Type: Read-only
Account Linking: Not applicable
Applicable interaction patterns: Auto-Match and Browse and Choose

Retrieves the specification for a given service. You can define a set of parameters associated with each service you support. Alexa+ uses this specification to ask the customer related questions needed to provide the required information to create a booking, or message a professional.

This operation takes input GetServiceSpecificationRequest and generates output GetServiceSpecificationResponse.

Request

Response

A successful GetServiceSpecificationResponse returns a set of parameters that are required when creating a booking, or messaging a professional related to the selected service ID.

On error, the response returns one of the following error codes:

• 400 ValidationExceptionResponse

• 400 ClientErrorResponse

• 408 RequestTimeoutErrorResponse

• 429 RequestThrottlingErrorResponse

• 500 InternalServerErrorResponse

CreateBooking

Path: /v1/homeservices/bookings
Method: POST
Type: Non-idempotent
Required Permissions: READ_MOBILE_NUMBER, READ_EMAIL, READ_FULL_NAME, READ_DEVICE_ADDRESS
Applicable interaction patterns: Auto-Match

Creates a new service booking.

This operation takes input CreateBookingRequest and generates output CreateBookingResponse.

Request

Represents a booking that may be in one of two stages: "ESTIMATE", or "CONFIRMATION".

Alexa+ first sends a request to start a booking process and generates an estimate. You must return the estimated charges and any service charges associated with the request. Also include a list of payment instruments for the customer to pick from.

Alexa+ shares the estimate and the service policies with the customer and allows the customer to select the payment instrument to use to complete the booking.

After the customer has selected a payment instrument and confirmed the request, Alexa+ calls CreateBooking again, sets the BookingStage parameter to CONFIRMATION.

Response

A successful CreateBookingResponse returns purchase details, booking stage, and booking details.

On error, the response returns one of the following error codes:

• 400 ValidationExceptionResponse

• 400 ClientErrorResponse

• 408 RequestTimeoutErrorResponse

• 429 RequestThrottlingErrorResponse

• 500 InternalServerErrorResponse

ListProfessionals

Path: /v1/homeservices/professionals
Method: POST
Type: Read-only
Applicable interaction patterns: Browse and Choose

Lists professionals who offer services for the specified project request.

Request

Response

A successful ListProfessionalsResponse returns a list of professional matching the search criteria, along with service information and pagination metadata.

On error, the response returns one of the following error codes:

• 400 ValidationExceptionResponse

• 400 ClientErrorResponse

• 408 RequestTimeoutErrorResponse

• 429 RequestThrottlingErrorResponse

• 500 InternalServerErrorResponse

MessageProfessional

Path: /v1/homeservices/professionals/{professionalId}/message
Method: POST
Type: Non-idempotent
Required Permissions: READ_MOBILE_NUMBER, READ_EMAIL, READ_FULL_NAME, READ_DEVICE_ADDRESS
Applicable interaction patterns: Browse and Choose

Sends a contact request message to a professional with project information.

Request

Response

A successful MessageProfessionalResponse returns HTTP 204 with no response body.

On error, the response returns one of the following error codes:

• 400 ValidationExceptionResponse

• 400 ClientErrorResponse

• 408 RequestTimeoutErrorResponse

• 429 RequestThrottlingErrorResponse

• 500 InternalServerErrorResponse

GetUserInfo

Path: /v1/homeservices/users/current
Method: GET
Type: Read-only Applicable interaction patterns: Auto-Match and Browse and Choose

Retrieves profile information for the currently authenticated user. This operation returns personal information from your system that the user has consented to share.

This operation takes input GetUserInfoRequest and generates output GetUserInfoResponse.

Request

There is no request body.

Response

A successful GetUserInfoResponse returns the current user's profile information.

On error, the response returns one of the following error codes:

• 400 ValidationExceptionResponse

• 400 ClientErrorResponse

• 408 RequestTimeoutErrorResponse

• 429 RequestThrottlingErrorResponse

• 500 InternalServerErrorResponse

GetBooking

Path: /v1/homeservices/bookings/{partnerBookingId}
Method: GET
Type: Read-only

Retrieves an existing booking by the partner's booking identifier, including current status and the professional assigned to it.

This operation takes input GetBookingRequest and generates output GetBookingResponse.

Request

Response

A successful GetBookingResponse returns booking details including current status and professional assignment.

On error, the response returns one of the following error codes:

• 400 ValidationExceptionResponse

• 400 ClientErrorResponse

• 408 RequestTimeoutErrorResponse

• 429 RequestThrottlingErrorResponse

• 500 InternalServerErrorResponse

CancelBooking

Path: /v1/homeservices/bookings/{partnerBookingId}/cancel
Method: POST
Type: Non-idempotent Required Permissions: READ_MOBILE_NUMBER, READ_EMAIL, READ_FULL_NAME, READ_DEVICE_ADDRESS

Cancels an existing booking using its unique identifier. The booking must be in a cancellable status including PENDING, CONFIRMED, ASSIGNED, or RESCHEDULED. Upon successful cancellation, the system updates the booking status to CANCELLED and releases any associated resources according to the cancellation policy.

This operation takes input CancelBookingRequest and generates output CancelBookingResponse.

Request

Response

A successful CancelBookingResponse returns booking ID and the latest status of the booking.

On error, the response returns one of the following error codes:

• 400 ValidationExceptionResponse

• 400 ClientErrorResponse

• 408 RequestTimeoutErrorResponse

• 429 RequestThrottlingErrorResponse

• 500 InternalServerErrorResponse

ModifyBooking

Path: /v1/homeservices/bookings/{partnerBookingId}/modify
Method: POST
Type: Non-idempotent Required Permissions: READ_MOBILE_NUMBER, READ_EMAIL, READ_FULL_NAME, READ_DEVICE_ADDRESS

Modifies an existing booking's appointment date and time. The booking must be in a modifiable status including PENDING, CONFIRMED, ASSIGNED, or RESCHEDULED. Upon successful modification, the booking status might remain the same or be updated based on your requirements.

This operation takes input ModifyBookingRequest and generates output ModifyBookingResponse.

Request

Response

A successful ModifyBookingResponse returns partnerBookingId and the updated status of the booking.

On error, the response returns one of the following error codes:

• 400 ValidationExceptionResponse

• 400 ClientErrorResponse

• 408 RequestTimeoutErrorResponse

• 429 RequestThrottlingErrorResponse

• 500 InternalServerErrorResponse

Components

Address

Physical address information for the service location.

Badge

Details of a badge (display element) that may be shown together with professional detail cards on Alexa devices with a screen.

Booking

Complete booking entity containing all booking and related data.

BookingStage

Stage of a booking request. A request starts as ESTIMATE — you must respond with estimated costs, policies, and payment instruments. Alexa+ presents these to the customer. After the customer confirms, the request transitions to CONFIRMATION.

BookingStatus

Current booking status.

Charge

Specific charge or fee associated with a service booking.

Constraint

Defines constraints for a form field, such as a regular expression defining the acceptable format, or an enumeration of allowable values.

Condition

Conditional display logic for form fields.

CostEstimate

Cost estimation information for the requested project, including pricing range and unit type.

CostUnit

Defines how the cost estimate should be interpreted and what unit it represents.

CreditCardDetails

Detailed information about a credit card, containing sensitive payment data.

FormField

Defines one form field for collecting a parameter for a ServiceSpecification associated with a service. Each FormField enables you to define one unique question applicable to your service that needs to be answered by the customer. For example, for house cleaning services, you can define a FormField to collect information about number of bathrooms. You can have another FormField to define the cleaning type that accepts one of the following possible values: "Standard", "Deep Cleaning", "Move-out Cleaning".

MonetaryValue

Monetary value representation.

PaymentInstrument

Payment instrument information including type, identifier, and detailed payment data.

PaymentInstrumentDetails

Detailed payment instrument information.

Policy

Business policy defining terms and conditions for service bookings.

Professional

Represents a service professional with their business information, ratings, and service details.

ProfessionalStub

Lighter representation used inside Booking.assignedProfessional. Has the same required fields as Professional (name, id, rating, numReviews) and the optional businessUrl, photoUrl, numProjects, badges — but omits description, costEstimate, responseTimeHours, and reviews.

Project

Project information containing details about the service request.

ProjectDetail

Project detail represents a specific aspect of the service request, for example, number of rooms, number of floors, appliance brand.

Purchase

Complete purchase entity containing all purchase-related information including charges, policies, and payment methods.

PaginationContext

Pagination metadata returned in responses that support paginated result sets.

Review

Individual customer review with rating, text, and reviewer information.

Service

Service information for describing different types of home services you offer.

ServiceSpecification

Defines a set of parameters that need to be collected when customers book a service, or message a professional for a given service type.

ValueConstraints

Defines a permitted value for a constrained parameter, similar to a value defined in enumerations.

UserInfo

User contact information.

Errors

All error responses share a common structure with errorType, errorCode, and message fields.

Error response example

{
  "errorType": "CLIENT_ERROR",
  "errorCode": "NO_ACCOUNT_LINKED_ERROR",
  "message": "The user doesn't have a linked account"
}

Error codes

Related topics

• Create a Category Add-on Manually with the CLI

Last updated: Jul 10, 2026