LeadObject

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/yelp/json-schema/yelp-lead-object-schema.json",
  "title": "LeadObject",
  "x-generated": "2026-11-05",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/yelp-leads-api-openapi.yml#/components/schemas/LeadObject",
  "type": "object",
  "properties": {
    "id": {
      "description": "The Yelp Lead ID (same as the ID query parameter)",
      "type": "string"
    },
    "business_id": {
      "description": "The Yelp Business ID",
      "type": "string"
    },
    "conversation_id": {
      "description": "The Conversation ID. Can be used to construct a link to Yelp Biz Inbox (URL format https://biz.yelp.com/messaging/[business-id]/thread/[conversation-id]).\n\n**NOTE** We will eventually migrate all users to the Yelp Leads Center, at which point this URL scheme will become obsolete as it uses the Lead ID instead.\n",
      "type": "string"
    },
    "temporary_email_address": {
      "description": "A temporary, one-time-use email address which the biz user can use to reply to the lead.\n\n**Note** In some cases, we may not return this temporary email address. Cases when this can happen include:\n\n* Access to proxy email addresses has not been enabled for you, see [Yelp Partner APIs](https://docs.developer.yelp.com/docs/yelp-partner-apis) on how to get access\n* The lead has been created more than 30 days ago\n* The lead has already been replied to by any biz user\n",
      "type": "string"
    },
    "temporary_email_address_expiry": {
      "description": "The expiry time of the reply email address (replies after expiry will be rejected).\nThis field will only be included if a temporary email address is returned as well.\n",
      "type": "string",
      "format": "date-time"
    },
    "temporary_phone_number": {
      "description": "**Deprecated.** The consumer's phone number. Only present if you were already receiving this field; otherwise, use `phone_number`.\n\n**Note** This field may not be returned if the consumer has not opted into receiving phone calls.\n",
      "type": "string",
      "deprecated": true
    },
    "temporary_phone_number_expiry": {
      "description": "**Deprecated.** The expiry time associated with the temporary phone number.\nIf `temporary_phone_number` is present, this value will be `2099-12-31T23:59:59+00:00`.\n",
      "type": "string",
      "format": "date-time",
      "deprecated": true
    },
    "phone_number": {
      "description": "The consumer's phone number.\n\n**Note** This field may not be returned if the consumer has not opted into receiving phone calls.\n",
      "type": "string"
    },
    "time_created": {
      "description": "The time when the lead was created",
      "type": "string",
      "format": "date-time"
    },
    "last_event_time": {
      "description": "Time of the last event on the lead",
      "type": "string",
      "format": "date-time"
    },
    "user": {
      "$ref": "#/$defs/ProjectConsumerUser"
    },
    "project": {
      "$ref": "#/$defs/Project"
    },
    "link_to_reply_in_yelp": {
      "description": "A direct link to the lead in Yelp's Leads Center, where the business can reply to the consumer.\nPlease contact Yelp if you want to receive this field in the response.\n",
      "type": "string"
    }
  },
  "required": [
    "id",
    "business_id",
    "time_created",
    "last_event_time"
  ],
  "$defs": {
    "Project": {
      "type": "object",
      "description": "The project",
      "properties": {
        "location": {
          "description": "The consumer users location",
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "postal_code": {
              "type": "string"
            }
          },
          "required": [
            "postal_code"
          ]
        },
        "availability": {
          "description": "The consumer users availability",
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "status": {
              "description": "The status of the availability. Is one of SPECIFIC_DATES, ASAP or FLEXIBLE",
              "type": "string"
            },
            "dates": {
              "description": "The list of dates that the consumer user selected, is empty if status is not SPECIFIC_DATES",
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          "required": [
            "status",
            "dates"
          ]
        },
        "job_names": {
          "description": "The name that identifies the type of job. For a moving business this could be \"In-state moving\" or \"Out-of-state moving\"",
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "survey_answers": {
          "description": "The projects survey questions and answers",
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "question_text": {
                "description": "The survey question text",
                "type": "string"
              },
              "question_identifier": {
                "description": "Optional custom question identifier used instead of the text to uniquely identify a question across text changes",
                "type": "string",
                "x-nullable": true
              },
              "answer_text": {
                "description": "The survey answers. This will contain multiple entries if the consumer user selected multiple answers for e.g. a list of items that need to be moved",
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            },
            "required": [
              "question_text",
              "answer_text"
            ]
          }
        },
        "attachments": {
          "description": "The project attachments (e.g. uploaded photos)",
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "description": "The unique ID for this attachment",
                "type": "string"
              },
              "url": {
                "description": "A url to the attachment content. Accessible for up to 24 hours after querying this endpoint",
                "type": "string"
              },
              "resource_name": {
                "description": "The name of the resource",
                "type": "string",
                "x-nullable": true
              },
              "mime_type": {
                "description": "The mime type of the file",
                "type": "string"
              }
            }
          }
        }
      },
      "required": [
        "location",
        "availability",
        "job_names",
        "survey_answers"
      ]
    },
    "ProjectConsumerUser": {
      "type": "object",
      "description": "The consumer user that created the project",
      "properties": {
        "display_name": {
          "description": "Display name of the user",
          "type": "string"
        }
      },
      "required": [
        "display_name"
      ]
    }
  }
}