--- agentTools: projectIndex: https://docs.developer.yelp.com/llms.txt --- # Get Jobs 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. # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "Home Services", "version": "1.0" }, "servers": [ { "url": "https://api.yelp.com" } ], "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`.\n\nExample: `Bearer 23813239889e947efd3e787cc41b0b839f442a85c5bfd30bd4b9a85ec3a54d5cae4d52b37ff52e64deb9c83bd04883812a6cebde04f2f25752f31be0ac74b514`.\n\nYou can create or find your API Key at [yelp.com](https://www.yelp.com/developers/v3/manage_app).\n" } } }, "security": [ { "bearerAuth": [] } ], "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.\n", "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.\n\n| code | description |\n| ------------- | ------------- |\n| UNAUTHORIZED_API_KEY | The API key provided is not currently able to query this endpoint. |\n| TOKEN_INVALID | Invalid API key or authorization header. |\n", "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" } } } } } } } }, "x-readme": { "headers": [], "explorer-enabled": true, "proxy-enabled": false, "samples-enabled": true }, "_id": { "buffer": { "0": 105, "1": 128, "2": 197, "3": 40, "4": 224, "5": 169, "6": 184, "7": 60, "8": 78, "9": 1, "10": 60, "11": 237 } } } ```