Yelp Home Services API
Home Services operations documented in the Yelp developer reference: Get Jobs; Get Survey; Request a Quote.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/yelp:yelp-home-services-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Home Services API
version: '1.0'
servers:
- url: https://api.yelp.com
security:
- bearerAuth: []
tags:
- name: Home Services
paths:
/v3/jobs:
post:
summary: Get Jobs
tags:
- Home Services
operationId: v3_get_jobs
description: This endpoint identifies the most relevant job types based on the end user's home service needs. By providing details about what the user is looking for, this endpoint returns multiple matching job types. From these, a single job type is selected and used as input for the Get Survey endpoint to continue the matching flow.
requestBody:
required: true
content:
application/json:
schema:
type: object
description: Request object for getting jobs based on natural language query.
properties:
query:
type: string
description: Natural language text describing the needs.
example: Bathroom sink leaking water under cabinet while running
maxLength: 1000
locale:
type: string
description: Locale code in the format of {language code}_{country code}. See the [list of supported locales](https://docs.developer.yelp.com/docs/resources-supported-locales).
example: en_US
default: en_US
pattern: ^[a-z]{2,3}_[A-Z]{2}$
format: yelp-supported-locale
required:
- query
responses:
'200':
description: Successfully retrieved jobs
content:
application/json:
schema:
type: object
description: Response object containing matched jobs.
properties:
jobs:
type: array
items:
type: object
description: Job definition with alias, display name and description.
properties:
job_alias:
type: string
description: Job alias, e.g. job_faucet_repair.
example: job_faucet_repair
display_name:
type: string
description: User-friendly name of the job.
example: Faucet Repair
description:
type: string
description: A description of the job.
example: Repair or replacement of sink, bathtub, or shower faucets
confidence_score:
type: number
format: float
description: Relevance confidence for this job, in the range [0, 1].
example: 0.72
required:
- job_alias
- display_name
- description
required:
- jobs
'400':
description: Bad Request. Message varies depending on failure scenario
content:
application/json:
schema:
type: object
properties:
error:
type: object
required:
- code
- description
properties:
code:
type: string
description: The error code.
description:
type: string
description: The description of the error.
examples:
Invalid Request:
value:
error:
code: INVALID_REQUEST
description: Invalid Request
'401':
description: 'The API key has either expired or doesn''t have the required scopes to query this endpoint.
| code | description |
| ------------- | ------------- |
| UNAUTHORIZED_API_KEY | The API key provided is not currently able to query this endpoint. |
| TOKEN_INVALID | Invalid API key or authorization header. |
'
content:
application/json:
examples:
Unauthorized:
value:
error:
code: UNAUTHORIZED_API_KEY
description: The API key provided is not currently able to query this endpoint.
Invalid Token:
value:
error:
code: TOKEN_INVALID
description: Invalid API key or authorization header.
schema:
$ref: '#/paths/~1v3~1jobs/post/responses/400/content/application~1json/schema'
'403':
description: Authorization Error
content:
application/json:
schema:
$ref: '#/paths/~1v3~1jobs/post/responses/400/content/application~1json/schema'
examples:
Authorization Error:
value:
error:
code: AUTHORIZATION_ERROR
description: Authorization Error
'404':
description: Resource Not Found
content:
application/json:
schema:
$ref: '#/paths/~1v3~1jobs/post/responses/400/content/application~1json/schema'
examples:
Resource Not Found:
value:
error:
code: NOT_FOUND
description: Resource Not Found
'429':
description: You have either exceeded your daily quota, or have exceeded the queries-per-second limit for this endpoint. Try reducing the rate at which you make queries.
content:
application/json:
examples:
Rate limited:
value:
error:
code: TOO_MANY_REQUESTS_PER_SECOND
description: You have exceeded the queries-per-second limit for this endpoint. Try reducing the rate at which you make queries.
schema:
$ref: '#/paths/~1v3~1jobs/post/responses/400/content/application~1json/schema'
'500':
description: Internal Server Error
content:
application/json:
examples:
Internal Server Error:
value:
error:
code: INTERNAL_ERROR
description: Something went wrong internally, please try again later.
schema:
$ref: '#/paths/~1v3~1jobs/post/responses/400/content/application~1json/schema'
/v3/jobs/{job_alias}/survey:
get:
summary: Get Survey
tags:
- Home Services
operationId: v3_job_survey
description: This endpoint returns a tailored set of questions and required information based on the provided job alias. This information must be collected from the end user in order to create a project submission. A project submission is how we match users with qualified home service providers — the more accurately this data is filled out, the higher the quality of the submission, leading to better and more relevant matches.
parameters:
- name: job_alias
in: path
required: true
description: The job alias to get the survey for.
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
job_alias:
type: string
description: The job alias for the survey.
display_name:
type: string
description: User-friendly name of the job.
example: Faucet Repair
description:
type: string
description: A description of the job.
example: Repair or replacement of sink, bathtub, or shower faucets
questions:
type: array
items:
type: object
description: The survey questions for the job
properties:
question_alias:
type: string
description: The alias for the survey question.
question_text:
type: string
description: The text of the survey question.
available_choices:
type: array
items:
type: string
description: The available choices for the survey question.
only_accepts_choices:
type: boolean
description: Whether the survey question only accepts predefined choices.
is_multi_select:
type: boolean
description: Whether the survey question allows selecting multiple available choices.
is_required:
type: boolean
description: Whether the survey question is required.
required:
- question_alias
- question_text
- available_choices
- only_accepts_choices
- is_multi_select
- is_required
required:
- job_alias
- display_name
- description
- questions
'400':
$ref: '#/paths/~1v3~1jobs/post/responses/400'
'401':
$ref: '#/paths/~1v3~1jobs/post/responses/401'
'403':
$ref: '#/paths/~1v3~1jobs/post/responses/403'
'404':
$ref: '#/paths/~1v3~1jobs/post/responses/404'
'429':
$ref: '#/paths/~1v3~1jobs/post/responses/429'
'500':
$ref: '#/paths/~1v3~1jobs/post/responses/500'
/v3/projects:
post:
summary: Request a Quote
tags:
- Home Services
description: This endpoint allows users to request quotes from home service professionals for their specific needs. After submitting the project details and user contact information, a project is created and a unique project ID is returned. Yelp will then automatically match the request with relevant home service businesses and invite them to provide quotes.
operationId: v3_raq_submit_project
requestBody:
content:
application/json:
schema:
type: object
description: 'Request body for submitting a quote request.
'
properties:
business_id:
type: string
description: The Yelp business ID to submit the quote request to.
format: business-id
job_alias:
type: string
description: The job alias for the quote request.
survey_responses:
type: array
items:
type: object
description: 'Details of a single survey question response for Request a Quote submission.
'
properties:
question_alias:
type: string
description: Unique identifier for the question.
user_response:
type: array
items:
type: string
description: The answers to the question. This will contain multiple entries if the customer selected multiple answers, for example, a list of items that need to be installed.
required:
- question_alias
- user_response
description: List of survey question responses.
submit_to_nearby_businesses:
type: boolean
description: Whether to submit quote request to nearby businesses. If business_id is not provided, this will be set to true.
customer_info:
description: Customer information for the quote request.
type: object
properties:
first_name:
type: string
description: Customer's first name.
minLength: 1
last_name:
type: string
description: Customer's last name.
x-nullable: true
email:
type: string
description: Customer's email address.
phone:
type: string
description: Customer's phone number in E.164 format.
x-nullable: true
zip_code:
type: string
description: Zip code of the project location. US (e.g. 94103, 94103-1234) or Canadian (e.g. V0R 1X9).
pattern: ^(\d{5}(-\d{4})?|[A-Za-z]\d[A-Za-z] ?\d[A-Za-z]\d)$
required:
- first_name
- email
- zip_code
required:
- job_alias
- survey_responses
- submit_to_nearby_businesses
- customer_info
responses:
'200':
description: The quote request has been submitted successfully.
content:
application/json:
schema:
type: object
description: 'Response object after submitting a Request a Quote survey.
'
properties:
project_id:
type: string
description: The ID of the created project for the quote request
matched_businesses:
type: array
items:
type: object
description: A business matched for a RAQ submission.
properties:
id:
type: string
format: business-id
description: The Yelp business ID
name:
type: string
description: The display name of the business
x-nullable: true
rating:
type: number
format: float
description: The average rating of the business
x-nullable: true
review_count:
type: integer
description: The total number of reviews of the business
x-nullable: true
required:
- id
description: The businesses matched for the quote request, with basic display details
x-nullable: true
required:
- project_id
'400':
$ref: '#/paths/~1v3~1jobs/post/responses/400'
'401':
$ref: '#/paths/~1v3~1jobs/post/responses/401'
'403':
$ref: '#/paths/~1v3~1jobs/post/responses/403'
'404':
$ref: '#/paths/~1v3~1jobs/post/responses/404'
'429':
$ref: '#/paths/~1v3~1jobs/post/responses/429'
'500':
$ref: '#/paths/~1v3~1jobs/post/responses/500'
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: 'To authenticate API calls with the API Key, set the Authorization HTTP header value as `Bearer API_KEY`.
Example: `Bearer 23813239889e947efd3e787cc41b0b839f442a85c5bfd30bd4b9a85ec3a54d5cae4d52b37ff52e64deb9c83bd04883812a6cebde04f2f25752f31be0ac74b514`.
You can create or find your API Key at [yelp.com](https://www.yelp.com/developers/v3/manage_app).
'
x-provenance:
method: searched
source: https://docs.developer.yelp.com/reference
harvested: '2026-11-05'
tool: harvest-readme-openapi.py
note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
assembled_from:
- https://docs.developer.yelp.com/reference/v3_get_jobs.md
- https://docs.developer.yelp.com/reference/v3_job_survey.md
- https://docs.developer.yelp.com/reference/v3_raq_submit_project.md
merge:
pages: 3
deduped: 4
conflicts_kept_first: 0