openapi: 3.1.0
info:
  version: ''
  contact:
    email: apisupport@spokeo.com
tags:
  - name: Name Search
    description: >
      **Endpoint name**: `https://api.spokeo.com/v5/names`


      {% partial file="/_partials/descriptions/name/name_intro.md" /%}


      <h2>Required Parameters</h2>


      Provide at least one name and an additional identifying field.


      - `first_name` (string) - The person's first name. _(Conditionally
      Required)_

      - `last_name` (string) - The person's last name. _(Conditionally
      Required)_


      {% partial file="/_partials/descriptions/name/name_response_and_usage.md"
      /%}
  - name: Person ID Search
    description: |
      **Endpoint name**: `https://api.spokeo.com/v5/person_id/{id}`

      {% partial file="/_partials/descriptions/person-id.md" /%}
  - name: Phone Search
    description: |
      **Endpoint name**: `https://api.spokeo.com/v5/phones`

      {% partial file="/_partials/descriptions/phone.md" /%}
  - name: Address Search
    description: |
      **Endpoint name**: `https://api.spokeo.com/v5/addresses`

      {% partial file="/_partials/descriptions/address.md" /%}
  - name: Email Search
    description: |
      **Endpoint name**: `https://api.spokeo.com/v5/emails`

      {% partial file="/_partials/descriptions/email.md" /%}
  - name: Username Search
    description: |
      **Endpoint name**: `https://api.spokeo.com/v5/usernames`

      {% partial file="/_partials/descriptions/username.md" /%}
servers:
  - url: https://api.spokeo.com/v5
paths:
  /names:
    get:
      tags:
        - Name Search
      summary: Search for a Person by Name
      operationId: names
      description: |
        #### Supported Query Combinations

        ##### Queries must satisfy the following conditions:
          1. Provide at least one name:
              - `first_name` or
              - `last_name`

          2. Provide at least one of the following additional fields:
              - the other name (`first_name` or `last_name`, whichever wasn't used in the condition above)
              - `middle_name`
              - `phone`
              - `email`
              - `street`
              - `city`
              - `state`
              - `relative_first_name`
              - `relative_last_name`
              - `age_min`
              - `age_max`
        <br /><br />
        ##### Valid Examples
        - `first_name` + `last_name`
        - `first_name` + `email`
        - `last_name` + `phone`
        - `first_name` + `state`
        - `first_name` + `city`
        - `first_name` + `relative_last_name`
        - `last_name` + `middle_name` + `state`
        - `first_name` + `city` + `distance`
        - `first_name` + `street` + `unit`
        - `first_name` + `age_min`
        - `last_name` + `age_max`
        - `first_name` + `age_min` + `age_max`
        <br /><br />
        ##### Invalid Examples
        - `first_name` only
        - `last_name` only
      security:
        - api_key: []
      parameters:
        - in: query
          name: first_name
          description: >
            The first name of the person you are searching for.


            <span style="color: red;">Conditionally required.</span> Either
            provide both `first_name` and `last_name`, or provide this field
            with additional identifying fields.
          schema:
            type: string
          required: false
        - in: query
          name: middle_name
          description: The middle name of the person you are searching for.
          schema:
            type: string
          required: false
        - in: query
          name: last_name
          description: >
            The last name of the person you are searching for.


            <span style="color: red;">Conditionally required.</span> Either
            provide both `first_name` and `last_name`, or provide this field
            with additional identifying fields.
          schema:
            type: string
          required: false
        - in: query
          name: street
          description: A street address associated with the person you are searching for.
          schema:
            type: string
          required: false
        - in: query
          name: unit
          description: >
            A unit or suite number associated with the person you are searching
            for.

            <span style="color: red;">Must be paired with `street`</span>.
          schema:
            type: string
          required: false
        - in: query
          name: city
          description: A city associated with the person you are searching for.
          schema:
            type: string
          required: false
        - in: query
          name: state
          description: A state associated with the person you are searching for.
          schema:
            type: string
          required: false
        - in: query
          name: distance
          description: >
            Restricts results to people associated with addresses located within
            the specified distance (in miles) of the city provided in the city
            parameter.  The maximum accepted value is 999.

            <span style="color: red;">Must be paired with the `city`</span>.
          schema:
            type: number
          required: false
        - in: query
          name: email
          description: An email address associated with the person you are searching for.
          schema:
            type: string
          required: false
        - in: query
          name: phone
          description: >-
            A 10-digit US phone number associated with the person you are
            searching for.
          schema:
            type: string
          required: false
        - in: query
          name: relative_first_name
          description: >-
            The first name of a relative associated with the person you are
            searching for.
          schema:
            type: string
          required: false
        - in: query
          name: relative_last_name
          description: >-
            The last name of a relative associated with the person you are
            searching for.
          schema:
            type: string
          required: false
        - in: query
          name: age_min
          description: The minimum age of the searched name.
          schema:
            type: integer
          required: false
        - in: query
          name: age_max
          description: The maximum age of the searched name.
          schema:
            type: integer
          required: false
        - in: query
          name: start_index
          description: >-
            The starting index from which results should be fetched. This is a
            1-based index. For example, if there are 10 total results and
            start_index is set to 3, results from the third item (index 3)
            through to the tenth item (index 10) will be returned.
          schema:
            type: string
          required: false
        - in: query
          name: end_index
          description: >-
            The ending index up to which results should be fetched. This is a
            1-based index. For example, if there are 10 total results and
            end_index is set to 7, results from the first item (index 1) through
            to the seventh item (index 7) will be returned.
          schema:
            type: string
          required: false
        - in: query
          name: position_token
          description: >-
            This method facilitates continuous data retrieval in a sequenced
            manner. If the response has position_token set, use the token
            obtained from the initial Name Search response as a parameter in the
            search URL to access the next set of results. Each response is
            limited to returning a maximum of 50 results.
          schema:
            type: string
          required: false
      responses:
        '200':
          description: OK - A successful Name Search returns an array of people.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Name'
        '404':
          description: Not Found
      x-codeSamples:
        - lang: cURL
          label: CLI
          source: |
            curl --header "X-api-key: [YOUR API KEY]" \
              -X GET 'https://api.spokeo.com/v5/names?first_name=john&last_name=smith&state=california'
        - lang: Ruby
          label: Ruby
          source: |
            connection = Faraday.new('https://api.spokeo.com/v5') do |faraday|
              faraday.headers['X-api-key'] = 'YOUR API KEY'
            end
            params = {
              last_name: 'smith',
              first_name: 'john',
              state: 'CA'
            }
            connection.get('/names', params)
        - lang: Python
          label: Python
          source: |
            import requests

            url = "https://api.spokeo.com/v5/names"

            query = {
                "first_name": "string",
                "middle_name": "string",
                "last_name": "string",
                "city": "string",
                "state": "string",
                "email": "string",
                "start_index": "string",
                "end_index": "string",
                "position_token": "string"
            }

            headers = {
                "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36",
                "X-api-key": "YOUR_API_KEY_HERE"
            }

            response = requests.get(url, headers=headers, params=query)

            data = response.json()
            print(data)
  /phones:
    get:
      tags:
        - Phone Search
      summary: Search for Information on a Phone Number
      operationId: phones
      security:
        - api_key: []
      parameters:
        - in: query
          name: phone
          description: The 10-digit US phone number you are using in your search.
          schema:
            type: string
          required: true
      responses:
        '200':
          description: >-
            OK - A successful Phone Search returns an array of people associated
            with a phone number, as well as metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Phone'
        '400':
          description: Bad Request
      x-codeSamples:
        - lang: cURL
          label: CLI
          source: |
            curl --header "X-api-key: [YOUR API KEY]" \
              -X GET 'https://api.spokeo.com/v5/phones?phone=1234567890'
        - lang: Ruby
          label: Ruby
          source: |
            connection = Faraday.new('https://api.spokeo.com/v5') do |faraday|
              faraday.headers['X-api-key'] = 'YOUR API KEY'
            end
            params = {
              phone: 1234567890
            }
            connection.get('/phones', params)
        - lang: Python
          label: Python
          source: |
            import requests

            url = "https://api.spokeo.com/v5/phones"

            query = {
              "phone": "string"
            }

            headers = {
              "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36",
              "X-api-key": "YOUR_API_KEY_HERE"
            }
              
            response = requests.get(url, headers=headers, params=query)
              
            data = response.json()
            print(data)
  /addresses:
    get:
      tags:
        - Address Search
      summary: Search for Information on an Address
      operationId: addresses
      security:
        - api_key: []
      parameters:
        - in: query
          name: street
          description: street and address
          schema:
            type: string
          required: true
        - in: query
          name: city
          description: city name
          schema:
            type: string
          required: true
        - in: query
          name: state
          description: US state; can be abbreviated
          schema:
            type: string
          required: true
        - in: query
          name: unit
          description: unit number or letter
          schema:
            type: string
          required: false
        - in: query
          name: position_token
          description: page/position token of the address response
          schema:
            type: integer
          required: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Address'
        '400':
          description: Bad Request
      x-codeSamples:
        - lang: cURL
          label: CLI
          source: |
            curl --header "X-api-key: [YOUR API KEY]" \
              -X GET 'https://api.spokeo.com/v5/addresses?street=301-Standiford-Ave&city=Modesto&state=CA'
        - lang: Ruby
          label: Ruby
          source: |
            connection = Faraday.new('https://api.spokeo.com/v5') do |faraday|
              faraday.headers['X-api-key'] = 'YOUR API KEY'
            end
            params = {
              street: '301-Standiford-Ave',
              city: 'Modesto',
              state: 'CA' 
            }
            connection.get('/addresses', params)
        - lang: Python
          label: Python
          source: |
            import requests

            url = "https://api.spokeo.com/v5/addresses"

            query = {
              "street": "string",
              "city": "string",
              "state": "string",
              "unit": "string",
              "position_token": "0"
            }

             headers = {
                "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36",
                "X-api-key": "YOUR_API_KEY_HERE"
            }

            response = requests.get(url, headers=headers, params=query)

            data = response.json()
            print(data)
  /person_id/{id}:
    get:
      tags:
        - Person ID Search
      summary: Search for a Person by Person ID
      operationId: pids
      security:
        - api_key: []
      parameters:
        - in: path
          name: id
          description: unique person identifier
          schema:
            type: number
          required: true
      responses:
        '200':
          description: OK - A successful Person ID Search returns a Spokeo profile.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Person'
        '400':
          description: Bad Request
      x-codeSamples:
        - lang: cURL
          label: CLI
          source: |
            curl --header "X-api-key: [YOUR API KEY]" \
              -X GET 'https://api.spokeo.com/v5/person_id/1234567890'
        - lang: Ruby
          label: Ruby
          source: |
            connection = Faraday.new('https://api.spokeo.com/v5') do |faraday|
              faraday.headers['X-api-key'] = 'YOUR API KEY'
            end
            connection.get('/person_id/1234567890')
        - lang: Python
          label: Python
          source: |
            import requests

            id = "YOUR_ID_PARAMETER"
            url = "https://api.spokeo.com/v5/person_id/" + id

            headers = {
              "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36",
              "X-api-key": "YOUR_API_KEY_HERE"
            }

            response = requests.get(url, headers=headers)

            data = response.json()
            print(data)
  /emails:
    get:
      tags:
        - Email Search
      summary: Search for Information on an Email Address
      operationId: emails
      security:
        - api_key: []
      parameters:
        - in: query
          name: email
          description: The email address you are using in your search.
          schema:
            type: string
          required: true
      responses:
        '200':
          description: >-
            OK - A successful Email Search returns an array of people and social
            profiles associated with an email address, as well as metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Email'
        '400':
          description: Bad Request
      x-codeSamples:
        - lang: cURL
          label: CLI
          source: |
            curl --header "X-api-key: [YOUR API KEY]" \
              -X GET 'https://api.spokeo.com/v5/emails?email=email@mail.com'
        - lang: Ruby
          label: Ruby
          source: |
            connection = Faraday.new('https://api.spokeo.com/v5') do |faraday|
              faraday.headers['X-api-key'] = 'YOUR API KEY'
            end
            params = {
              email: 'email=email@mail.com'
            }
            connection.get('/emails', params)
        - lang: Python
          label: Python
          source: |
            import requests

            url = "https://api.spokeo.com/v5/emails"
              
            query = {
              "email": "string"
            }
              
            headers = {
              "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36",
              "X-api-key": "YOUR_API_KEY_HERE"
            }

            response = requests.get(url, headers=headers, params=query)
              
            data = response.json()
            print(data)
  /usernames:
    get:
      tags:
        - Username Search
      summary: Search for Information on a Username
      operationId: usernames
      security:
        - api_key: []
      parameters:
        - in: query
          name: username
          description: username to search for social profiles
          schema:
            type: string
          required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Username'
        '412':
          description: Precondition Failed
      x-codeSamples:
        - lang: cURL
          label: CLI
          source: |
            curl --header "X-api-key: [YOUR API KEY]" \
              -X GET 'https://api.spokeo.com/v5/usernames?username=tangtalks'
        - lang: Ruby
          label: Ruby
          source: |
            connection = Faraday.new('https://api.spokeo.com/v5') do |faraday|
              faraday.headers['X-api-key'] = 'YOUR API KEY'
            end
            params = {
              username: "tangtalks"
            }
            connection.get('/usernames', params)
components:
  securitySchemes:
    api_key:
      type: apiKey
      in: header
      name: X-api-key
      description: |
        To properly authenticate, you must provide your API key.
        This API key must be provided in the `X-api-key` request header.
  schemas:
    Name:
      type: object
      properties:
        data:
          type: object
          properties:
            people:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                    description: >
                      A unique Spokeo identifier associated with the person.
                      Input this ID into **[Person ID
                      Search](/apis/openapi/person-id-search)** to retrieve
                      person data, including contact information.
                    example: 1234567890
                  names:
                    type: array
                    description: Names associated with the person.
                    items:
                      type: object
                      properties:
                        first_name:
                          type: string
                          description: The person’s first name.
                          example: John
                        last_name:
                          type: string
                          description: The person’s last name.
                          example: Doe
                        middle_name:
                          type: string
                          description: The person’s middle name.
                          example: U
                        full_name:
                          type: string
                          description: The person’s full name.
                          example: John U Doe Jr.
                        suffix:
                          type: string
                          description: The person’s name suffix.
                          example: Jr.
                        name_type:
                          type: string
                          description: The name type of this record.
                          example: main
                  age:
                    type: number
                    description: The person’s current age or age at death.
                    example: 30
                  dob_month:
                    type: number
                    description: The person’s dob month as a number.
                    example: 12
                  dob_year:
                    type: number
                    description: The person’s dob year as a number.
                    example: 1990
                  is_deceased:
                    type: boolean
                    description: >-
                      A value of "true" signifies that the person is deceased,
                      while "false" signifies that the person is alive.
                    example: false
                  phones:
                    type: array
                    description: Phone numbers associated with the person.
                    items:
                      type: object
                      properties:
                        phone:
                          type: string
                          description: Phone Number associated with the person.
                          example: 5551234567
                        phone_is_new:
                          type: boolean
                          description: Indicates if the phone is new in the data.
                          example: true
                        phone_is_new_rank_one:
                          type: boolean
                          description: >-
                            Indicates that the phone has newly become rank 1
                            (i.e. the current rank is 1 and the previous rank
                            was not 1). Otherwise, this value is null.
                          example: true
                  emails:
                    type: array
                    description: Email addresses associated with the person.
                    items:
                      type: object
                      properties:
                        email:
                          type: string
                          description: Email associated with the person.
                          example: username@email.com
                        email_is_new:
                          type: boolean
                          description: Indicates if the email is new in the data.
                          example: true
                        email_is_new_rank_one:
                          type: boolean
                          description: >-
                            Indicates that the email has newly become rank 1
                            (i.e. the current rank is 1 and the previous rank
                            was not 1). Otherwise, this value is null.
                          example: true
                  addresses:
                    type: array
                    description: Addresses associated with the person.
                    items:
                      type: object
                      properties:
                        city:
                          type: string
                          description: The city associated with the person.
                          example: Anytown
                        state:
                          type: string
                          description: The state associated with the person.
                          example: CA
                        street_address:
                          type: string
                          description: The street address associated with the person.
                          example: 123 Main St
                        zip:
                          type: string
                          example: 12345
                        latitude:
                          type: number
                          description: >-
                            The latitude of the address associated with the
                            person.
                          example: 40.689247
                        longitude:
                          type: number
                          description: >-
                            The longitude of the address associated with the
                            person.
                          example: -74.0451471
                        address_is_new:
                          type: boolean
                          description: Indicates if the address is new in the data.
                          example: true
                        address_is_new_rank_one:
                          type: boolean
                          description: >-
                            Indicates that the address has newly become rank 1
                            (i.e. the current rank is 1 and the previous rank
                            was not 1). Otherwise, this value is null.
                          example: true
                  relatives:
                    type: array
                    description: Relatives associated with the person.
                    items:
                      type: object
                      properties:
                        names:
                          type: array
                          description: Names associated with the relative.
                          items:
                            type: object
                            properties:
                              first_name:
                                type: string
                                description: The relative's first name.
                                example: John
                              last_name:
                                type: string
                                description: The relative's last name.
                                example: Doe
                              full_name:
                                type: string
                                description: The relative's full name.
                                example: John Doe
                  usernames:
                    type: array
                    description: Usernames associated with the person.
                    items:
                      type: string
                      example: johndoe123
                  work_history:
                    type: array
                    description: Work history associated with the person.
                    items:
                      type: object
                      properties:
                        company_name:
                          type: string
                          description: The name of the company.
                          example: Example Corp
                        title:
                          type: string
                          description: The job title at the company.
                          example: Software Engineer
                        location:
                          type: string
                          description: The location of the company.
                          example: New York, NY
                  schools:
                    type: array
                    description: Schools associated with the person.
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                          description: The name of the school.
                          example: Example University
                        type:
                          type: string
                          description: The type of school.
                          example: Post-Secondary Institution
                        location:
                          type: string
                          description: The location of the school.
                          example: Boston, MA
                  phone_record_count:
                    type: number
                    description: >-
                      The total number of phone records associated with the
                      person.
                    example: 5
                  phone_record_delta_count:
                    type: number
                    description: >-
                      The total change in the number of phone records associated
                      with the person.
                    example: 1
                  email_record_count:
                    type: number
                    description: >-
                      The total number of email records associated with the
                      person.
                    example: 5
                  email_record_delta_count:
                    type: number
                    description: >-
                      The total change in the number of email records associated
                      with the person.
                    example: 2
                  address_count:
                    type: number
                    description: The total number of addresses associated with the person.
                    example: 10
                  address_record_delta_count:
                    type: number
                    description: >-
                      The total change in the number of address records
                      associated with the person.
                    example: 0
                  relative_count:
                    type: number
                    description: The total number of relatives associated with the person.
                    example: 10
                  username_count:
                    type: number
                    description: The total number of usernames associated with the person.
                    example: 10
        metadata:
          type: object
          properties:
            total_people_count:
              type: number
              description: >-
                The total count in the array of people returned based on your
                search inputs.
              example: 200
        position_token:
          type: string
          description: >-
            A token indicating that there are additional results beyond those
            initially returned. Use the token obtained from the initial Name
            Search response as a parameter in the search URL to access the next
            set of results.
          example: Mg==
    Phone:
      type: object
      properties:
        data:
          type: object
          properties:
            owners:
              type: array
              items:
                type: object
                description: Owners associated with the phone number.
                properties:
                  is_current_owner:
                    type: boolean
                    description: >-
                      A value of "true" signifies that the person is the current
                      owner of the phone number, while "false" signifies that
                      the person is either a possible current owner or a
                      previous owner.
                  age:
                    type: number
                    description: The person’s current age or age at death.
                    example: 62
                  additional_phones:
                    type: array
                    description: Additional phone numbers associated with the person.
                    items:
                      type: object
                      properties:
                        phone:
                          type: string
                          description: Phone Number associated with the person.
                          example: 5551234567
                  addresses:
                    type: array
                    description: Addresses associated with the person.
                    items:
                      type: object
                      properties:
                        address_id:
                          type: string
                          description: The address id associated with the person.
                          example: 123a2bf|October Ln|47||
                        street_address:
                          type: string
                          description: The street address associated with the person.
                          example: 123 Main St
                        city:
                          type: string
                          description: The city associated with the person.
                          example: Anytown
                        country:
                          type: string
                          description: The country associated with the person.
                          example: United States
                        latitude:
                          type: number
                          description: >-
                            The latitude of the address associated with the
                            person.
                          example: 40.689247
                        longitude:
                          type: number
                          description: >-
                            The longitude of the address associated with the
                            person.
                          example: -74.0451471
                        state:
                          type: string
                          description: The state associated with the person.
                          example: MN
                        zip:
                          type: string
                          description: The ZIP code associated with the person.
                          example: 55555
                        start_date:
                          type: string
                          description: >-
                            The date the phone owner started owning this
                            property.
                          example: '1996-01-12'
                        end_date:
                          type: string
                          description: >-
                            The date the phone owner stopped owning this
                            property.
                          example: '2025-01-31'
                  schools:
                    type: array
                    description: Schools the person attended.
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                          description: The name of the school the person attended.
                          example: Anytown University
                        type:
                          type: string
                          description: >-
                            The type of school the person attended. (e.g.
                            "University")
                          example: University
                        location:
                          type: string
                          description: The location of the school the person attended.
                          example: Anytown, CA
                        linkedin:
                          type: string
                          description: >-
                            The social profile of the school the person
                            attended.
                          example: linkedin.com/school/anytown-university
                        facebook:
                          type: string
                          description: >-
                            The social profile of the school the person
                            attended.
                          example: facebook.com/anytownuniversity
                        twitter:
                          type: string
                          description: >-
                            The social profile of the school the person
                            attended.
                          example: twitter.com/anytownuniversity
                        website:
                          type: string
                          description: The website of the school the person attended.
                          example: anytownuniversity.edu
                        start_date:
                          type: string
                          description: >-
                            The date the phone owner started attending this
                            school.
                          example: 2010
                        end_date:
                          type: string
                          description: >-
                            The date the phone owner stopped attending this
                            school.
                          example: 2012
                        degrees:
                          type: array
                          description: Degrees the person received.
                          items:
                            type: object
                            properties:
                              name:
                                type: string
                                description: The name of the degree the person received.
                                example: computer science
                  emails:
                    type: array
                    description: Email addresses associated with the person.
                    items:
                      type: object
                      properties:
                        email:
                          type: string
                          description: Email associated with the person.
                          example: username@email.com
                  names:
                    type: array
                    description: Names associated with the person.
                    items:
                      type: object
                      properties:
                        full_name:
                          type: string
                          description: Full Name associated with the person.
                          example: John Smith
                        first_name:
                          type: string
                          description: First Name associated with the person.
                          example: John
                        last_name:
                          type: string
                          description: Last Name associated with the person.
                          example: Smith
                        name_type:
                          type: string
                          description: The name type of this record.
                          example: main
                  id:
                    type: string
                    description: >
                      A unique Spokeo identifier associated with the person.
                      Input this ID into **[Person ID
                      Search](/apis/openapi/person-id-search)** to retrieve
                      person data, including contact information.
                    example: 1234567890
                  relatives:
                    type: array
                    description: Relatives associated with the person.
                    items:
                      type: object
                      properties:
                        full_name:
                          type: string
                          description: Full Name associated with the person.
                          example: Jane Smith
                        first_name:
                          type: string
                          description: First Name associated with the person.
                          example: Jane
                        last_name:
                          type: string
                          description: Last Name associated with the person.
                          example: Smith
                  social_profiles:
                    type: array
                    description: Social profiles associated with the person.
                    items:
                      type: object
                      properties:
                        profile_photo_url:
                          type: string
                          description: The social profile photo url.
                          example: >-
                            https://graph.facebook.com/123/picture?type=large&redirect=true
                        profile_url:
                          type: string
                          description: The social profile url.
                          example: https://www.facebook.com/jsmith
                  work_history:
                    type: array
                    description: Jobs the person held.
                    items:
                      type: object
                      properties:
                        title:
                          type: string
                          description: The job title of the phone owner.
                          example: Product Manager
                        company_name:
                          type: string
                          description: The company name of the workplace.
                          example: Spokeo
                  confidence_score:
                    type: number
                    description: The confidence level of the phone owner.
                    example: 34.53
                  is_company:
                    type: boolean
                    description: Indicates whether the owner is a person or company.
                    example: false
                  is_deceased:
                    type: boolean
                    description: Indicates whether the owner is deceased.
                    example: false
                  death_month:
                    type: number
                    description: Owner's death month as a number.
                    example: 11
                  death_year:
                    type: number
                    description: Owner's death year as a number.
                    example: 2010
                  dob_month:
                    type: number
                    description: The person’s dob month as a number.
                    example: 3
                  dob_year:
                    type: number
                    description: The person’s dob year as a number.
                    example: 1943
                  start_date:
                    type: date
                    description: The start date of this phone owner.
                    example: '1996-01-12'
                  end_date:
                    type: date
                    description: The end date of this phone owner.
                    example: '2025-01-31'
            area_code_locations:
              type: array
              items:
                type: object
                properties:
                  city:
                    type: string
                    description: The city associated with the person.
                    example: Anytown
                  latitude:
                    type: number
                    description: The latitude of the address associated with the person.
                    example: 40.689247
                  longitude:
                    type: number
                    description: The longitude of the address associated with the person.
                    example: -74.0451471
                  state:
                    type: string
                    description: The state associated with the phone number's area code.
                    example: CA
            phone_info:
              type: object
              properties:
                activity_status:
                  type: string
                  description: Returns whether the phone line is “Active” or “Inactive”.
                  example: Active
                activity_status_confidence:
                  type: string
                  description: The confidence level of the activity status.
                  example: High
                line_type:
                  type: string
                  description: >-
                    Returns whether the phone line is “Landline”, “Wireless”, or
                    “VOIP”.
                  example: Wireless
                listing_type:
                  type: string
                  description: >-
                    Returns whether the phone service is "Residential",
                    "Business", or "Special Services".
                  example: Unknown
                special_service_type:
                  type: string
                  description: >-
                    The type of special service associated with the phone number
                    (e.g. “Information Provider”).
                  example: null
                carrier:
                  type: string
                  description: The company providing the phone service.
                  example: Verizon Wireless
                carrier_type:
                  type: string
                  description: The type of business for the carrier (e.g. “Wireless”).
                  example: Wireless
                is_valid:
                  type: boolean
                  description: >-
                    A value of "true" signifies that the phone number is
                    properly formed and assigned to a carrier.
                is_portable:
                  type: boolean
                  description: >-
                    A value of "true" signifies that the phone number can switch
                    carriers.
                time_zone:
                  type: string
                  description: The time zone associated with the phone number's area code.
                  example: America/Anytown
            reputation:
              type: object
              properties:
                risk_level:
                  type: string
                  description: The risk level of the phone number.
                  example: High
                recent_search_count:
                  type: number
                  description: The number of recent searches of this phone number.
                  example: 5
                last_comment_date:
                  type: date
                  description: The date of the last comment reported for this phone number.
                  example: '2023-09-04'
                is_toll_free_or_erc:
                  type: boolean
                  description: >-
                    Flag to indicate whether the phone number is toll free or
                    ERC.
                  example: false
                score:
                  type: number
                  description: The reputation score of the phone number.
                  example: 1
        metadata:
          type: object
          properties:
            total_owner_count:
              type: number
              description: >-
                The total count in the array of owners returned based on your
                search inputs.
              example: 1
    Address:
      type: object
      properties:
        data:
          type: object
          properties:
            address:
              type: object
              properties:
                street_address:
                  type: string
                  example: 123 Main St
                city:
                  type: string
                  example: Anytown
                zip:
                  type: string
                  example: 11111
                county:
                  type: string
                  example: Los Angeles
                state:
                  type: string
                  example: CA
                latitude:
                  type: number
                  example: 40.689247
                longitude:
                  type: number
                  example: -74.0451471
                nearby_schools:
                  type: array
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                        example: MP Montessori School
                      address:
                        type: object
                        properties:
                          street_address:
                            type: string
                            example: 123 Main St Ave
                          city:
                            type: string
                            example: Anytown
                          state:
                            type: string
                            example: CA
                      grades_served:
                        type: string
                        example: PK-KG
                      type:
                        type: string
                        example: Private
                      enrollment_count:
                        type: number
                        example: 34
                      rating:
                        type: string
                        example: B-
                      district_name:
                        type: string
                        example: Los Angeles Unified
                properties:
                  type: array
                  items:
                    type: object
                    properties:
                      valuations:
                        type: array
                        items:
                          type: object
                          properties:
                            confidence_score:
                              type: number
                              example: 95
                            date:
                              type: string
                              example: '2021-11-24'
                            forecast_standard_deviation:
                              type: number
                              example: 5
                            market_value:
                              type: number
                              example: 1327500
                            market_value_max:
                              type: number
                              example: 1393875
                            market_value_min:
                              type: number
                              example: 1261125
                      residents:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              description: >
                                A unique Spokeo identifier associated with the
                                person. Input this ID into **[Person ID
                                Search](/apis/openapi/person-id-search)** to
                                retrieve person data, including contact
                                information.
                              example: 1234567890
                            is_deceased:
                              type: boolean
                              example: false
                            names:
                              type: array
                              items:
                                type: object
                                properties:
                                  full_name:
                                    type: string
                                    example: John James Smith
                                  first_name:
                                    type: string
                                    example: John
                                  middle_name:
                                    type: string
                                    example: James
                                  last_name:
                                    type: string
                                    example: Smith
                                  name_type:
                                    type: string
                                    example: main
                            age:
                              type: number
                              example: 51
                            dob_month:
                              type: number
                              example: 8
                            dob_year:
                              type: number
                              example: 2023
                            lives_at_property:
                              type: boolean
                              example: true
                            addresses:
                              type: array
                              items:
                                type: object
                                properties:
                                  city:
                                    type: string
                                    example: Anytown
                                  latitude:
                                    type: number
                                    example: 40.689247
                                  longitude:
                                    type: number
                                    example: -74.0451471
                                  street_address:
                                    type: string
                                    example: 123 Main St Apt 8
                                  country:
                                    type: string
                                    example: US
                                  zip:
                                    type: string
                                    example: 11111
                                  state:
                                    type: string
                                    example: CA
                                  url_path:
                                    type: string
                                    example: /CA/Anytown/123-Anytown-St
                                  is_current:
                                    type: boolean
                                    example: false
                            relatives:
                              type: array
                              items:
                                type: object
                                properties:
                                  names:
                                    type: array
                                    items:
                                      type: object
                                      properties:
                                        full_name:
                                          type: string
                                          example: Jane Doe
                            phones:
                              type: array
                              items:
                                type: object
                                properties:
                                  phones:
                                    type: object
                                    properties:
                                      phone:
                                        type: string
                                        example: 2521425485
                                      is_best:
                                        type: boolean
                                        example: true
                            emails:
                              type: array
                              items:
                                type: object
                                properties:
                                  emails:
                                    type: object
                                    properties:
                                      email:
                                        type: string
                                        example: jdoe@email.com
                                      is_best:
                                        type: boolean
                                        example: true
                            phone_record_count:
                              type: number
                              example: 3
                            address_count:
                              type: number
                              example: 2
                            email_record_count:
                              type: number
                              example: 1
                            start_date:
                              type: string
                              example: '2024-05-05'
                            end_date:
                              type: string
                              example: '2024-05-05'
                            first_processed:
                              type: string
                              example: '2024-05-05'
                            last_processed:
                              type: string
                              example: '2024-05-05'
                            confidence_score:
                              type: number
                              example: 1.8
                      owners:
                        type: array
                        items:
                          type: object
                          properties:
                            names:
                              type: array
                              items:
                                type: object
                                properties:
                                  first_name:
                                    type: string
                                    example: John
                                  last_name:
                                    type: string
                                    example: Doe
                                  middle_name:
                                    type: string
                                    example: James
                                  full_name:
                                    type: string
                                    example: John James Doe
                                  name_type:
                                    type: string
                                    example: main
                            id:
                              type: string
                              description: >
                                A unique Spokeo identifier associated with the
                                person. Input this ID into **[Person ID
                                Search](/apis/openapi/person-id-search)** to
                                retrieve person data, including contact
                                information.
                              example: 1234567890
                            ownership_type:
                              type: string
                              example: Individual
                            is_trust:
                              type: boolean
                              example: false
                            is_company:
                              type: boolean
                              example: false
                            lives_at_property:
                              type: boolean
                              example: false
                            ownership_start_date:
                              type: string
                              example: '1999-02-25'
                            ownership_end_date:
                              type: string
                              example: '1999-02-25'
                            phones:
                              type: array
                              items:
                                type: object
                                properties:
                                  phones:
                                    type: object
                                    properties:
                                      phone:
                                        type: string
                                        example: 2521452154
                                      is_best:
                                        type: boolean
                                        example: true
                            emails:
                              type: array
                              items:
                                type: object
                                properties:
                                  emails:
                                    type: object
                                    properties:
                                      email:
                                        type: string
                                        example: jdoe@email.com
                                      is_best:
                                        type: boolean
                                        example: true
                            addresses:
                              type: array
                              items:
                                type: object
                                properties:
                                  city:
                                    type: string
                                    example: Anytown
                                  latitude:
                                    type: number
                                    example: 40.689247
                                  longitude:
                                    type: number
                                    example: -74.0451471
                                  street_address:
                                    type: string
                                    example: 123 Main St Apt 8
                                  country:
                                    type: string
                                    example: US
                                  zip:
                                    type: string
                                    example: 11111
                                  state:
                                    type: string
                                    example: CA
                                  url_path:
                                    type: string
                                    example: CA/Anytown/123-Anytown-St
                                  is_current:
                                    type: boolean
                                    example: false
                      property_info:
                        type: object
                        properties:
                          zoned_use:
                            type: string
                            example: Single Family Residence
                          living_area_sqft:
                            type: number
                            example: 2652
                          bath_count:
                            type: number
                            example: 4.5
                          bed_count:
                            type: number
                            example: 3
                          heating_type:
                            type: string
                            example: Central
                          cooling_type:
                            type: string
                            example: Central
                          garage_type:
                            type: string
                            example: Detached
                          story_count:
                            type: number
                            example: 2
                          structure_style:
                            type: string
                            example: Bungalow
                          view_type:
                            type: string
                            example: Beach
                          pool_type:
                            type: string
                            example: Square
                          fireplace:
                            type: string
                            example: None
                          year_built:
                            type: number
                            example: 1904
                          lot_sqft:
                            type: number
                            example: 15120
                          unit_count:
                            type: number
                            example: 1
                          garage_sqft:
                            type: number
                            example: 360
                          type:
                            type: string
                            example: single_family
                          has_carport:
                            type: boolean
                            example: false
                          carport_sqft:
                            type: number
                            example: 280
                          parking_space_count:
                            type: number
                            example: 2
                          use_type:
                            type: string
                            example: Residential
                          legal_subdivision:
                            type: string
                            example: 9038
                          foundation_type:
                            type: string
                            example: Concrete
                          attic_sqft:
                            type: number
                            example: 380
                          has_attic:
                            type: boolean
                            example: true
                          basement_sqft:
                            type: number
                            example: 280
                          basement_sqft_finished:
                            type: number
                            example: 280
                          basement_sqft_unfinished:
                            type: number
                            example: 0
                          porch_type:
                            type: string
                            example: None
                          roof_construction:
                            type: string
                            example: Pitched
                          roof_material:
                            type: string
                            example: Shingles
                          floor_material:
                            type: string
                            example: Concrete
                          sewage_type:
                            type: string
                            example: Underground
                          is_multi_floor:
                            type: boolean
                            example: true
                          parcel_number:
                            type: number
                            example: 3254125856
                          zoned_use_jurisdiction_code:
                            type: string
                            example: LAR1
                          fence_type:
                            type: string
                            example: Picket
                          area_fence:
                            type: number
                            example: 280
                          flood_zone_description:
                            type: string
                            example: >-
                              This property is located in a minimal flood risk
                              area
                      tax:
                        type: object
                        properties:
                          assessor:
                            type: object
                            properties:
                              last_sold_date:
                                type: string
                                example: '1997-06-25'
                              last_sold_price:
                                type: number
                                example: 192500
                              last_sold_price_per_sqft:
                                type: number
                                example: 72
                              parties:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    names:
                                      type: array
                                      items:
                                        type: object
                                        properties:
                                          full_name:
                                            type: string
                                            example: John Doe
                                          suffix:
                                            type: string
                                            example: Jr.
                          history:
                            type: array
                            items:
                              type: object
                              properties:
                                year:
                                  type: number
                                  example: 2020
                                billed_amount:
                                  type: number
                                  example: 4525
                                total_assessed_value:
                                  type: number
                                  example: 371709
                                improvement_value:
                                  type: number
                                  example: 170674
                                land_value:
                                  type: number
                                  example: 201035
                          delinquent_first_year:
                            type: string
                            example: 2020
                          delinquent_last_year:
                            type: string
                            example: 2021
                          district_code:
                            type: string
                            example: 7500
                          exemptions:
                            type: object
                            properties:
                              is_homeowner:
                                type: boolean
                                example: false
                              is_disabled:
                                type: boolean
                                example: false
                              is_senior:
                                type: boolean
                                example: false
                              is_veteran:
                                type: boolean
                                example: false
                              is_widow:
                                type: boolean
                                example: false
                              is_additional:
                                type: string
                                example: true
                      deed:
                        type: object
                        properties:
                          buyers:
                            type: array
                            items:
                              type: object
                              properties:
                                names:
                                  type: array
                                  items:
                                    type: object
                                    properties:
                                      full_name:
                                        type: string
                                        example: John Doe
                                      suffix:
                                        type: string
                                        example: Jr.
                          last_sale:
                            type: object
                            properties:
                              book_number:
                                type: string
                                example: 10
                              page_number:
                                type: string
                                example: 25
                              document_number:
                                type: string
                                example: 123456
                              price:
                                type: number
                                example: 192500
                              date:
                                type: string
                                example: '1997-06-25'
                              price_per_sqft:
                                type: number
                                example: 72
                      financial_insight:
                        type: object
                        properties:
                          estimated_loan_to_value:
                            type: number
                            example: 0
                          loans_total:
                            type: number
                            example: 0
                          is_free_and_clear:
                            type: boolean
                            example: false
                          is_absentee_owned:
                            type: boolean
                            example: false
                          is_out_of_state_owner:
                            type: boolean
                            example: false
                          is_upside_down:
                            type: boolean
                            example: false
                          is_long_time_owner:
                            type: boolean
                            example: false
                          is_bored_investor:
                            type: boolean
                            example: false
                          is_potentially_inherited:
                            type: boolean
                            example: false
                          is_potentially_distressed:
                            type: boolean
                            example: false
                          known_preforeclosure_date:
                            type: boolean
                            example: false
                      sellability:
                        type: object
                        properties:
                          retail_score:
                            type: number
                            example: 461
                          retail_score_date:
                            type: string
                            example: '2021-10-29'
                          wholesale_score:
                            type: number
                            example: 10
                          wholesale_score_date:
                            type: string
                            example: '2021-10-29'
                          investor_score:
                            type: number
                            example: 504
                          investor_score_date:
                            type: string
                            example: '2021-10-29'
                      units:
                        type: array
                        items:
                          type: object
                          properties:
                            designator:
                              type: string
                              example: 5A
                            bath_count:
                              type: number
                              example: 2
                            bed_count:
                              type: number
                              example: 3
                            zoned_use:
                              type: string
                              example: Residential
                            living_sqft:
                              type: number
                              example: 2000
                            year_built:
                              type: number
                              example: 1973
                            residents:
                              type: array
                              items:
                                type: object
                                properties:
                                  names:
                                    type: array
                                    items:
                                      type: object
                                      properties:
                                        full_name:
                                          type: string
                                          example: John M Doe
                                  id:
                                    type: string
                                    description: >
                                      A unique Spokeo identifier associated with
                                      the person. Input this ID into **[Person
                                      ID
                                      Search](/apis/openapi/person-id-search)**
                                      to retrieve person data, including contact
                                      information.
                                    example: 1234567890
                      addresses:
                        type: array
                        items:
                          type: object
                          properties:
                            city:
                              type: string
                              example: Anytown
                            latitude:
                              type: number
                              example: 40.689247
                            longitude:
                              type: number
                              example: -74.0445
                            street_address:
                              type: string
                              example: 123 Main St
                            zip:
                              type: string
                              example: '10001'
                            state:
                              type: string
                              example: CA
                            county:
                              type: string
                              example: New York
                            url_path:
                              type: string
                              example: /CA/Anytown/123-Main-St
        position_token:
          type: string
          example: Mg==
    Person:
      type: object
      properties:
        data:
          type: object
          properties:
            person:
              type: object
              properties:
                id:
                  type: string
                  description: A unique person identifier.
                  example: 1234567890
                names:
                  type: array
                  items:
                    type: object
                    properties:
                      full_name:
                        type: string
                        description: The person's full name.
                        example: John James Doe Jr.
                      first_name:
                        type: string
                        description: The person's first name.
                        example: John
                      middle_name:
                        type: string
                        description: The person's middle name.
                        example: James
                      last_name:
                        type: string
                        description: The person's last name.
                        example: Doe
                      suffix:
                        type: string
                        description: The person's suffix.
                        example: Jr.
                      name_type:
                        type: string
                        description: The name type of this record.
                        example: main
                gender:
                  type: string
                  description: The person's gender.
                  example: Male
                birth:
                  type: object
                  properties:
                    dob_month:
                      type: number
                      description: The month of the person's birth.
                      example: 3
                    dob_year:
                      type: number
                      description: The year of the person's birth.
                      example: 2000
                death:
                  type: object
                  properties:
                    is_deceased:
                      type: boolean
                      description: >-
                        A value of "true" signifies that the person is deceased,
                        while "false" signifies that the person is alive.
                    death_month:
                      type: number
                      description: The month of the person's death.
                      example: 11
                    death_year:
                      type: number
                      description: The year of the person's death.
                      example: 2010
                    death_age:
                      type: number
                      description: The age of the person at death.
                      example: 58
                divorce:
                  type: object
                  properties:
                    divorce_month:
                      type: number
                      description: The person's divorce month.
                      example: 3
                    divorce_year:
                      type: number
                      description: The person's divorce year.
                      example: 2025
                marital_status:
                  type: string
                  description: The person's marital status.
                  example: Married
                marriage:
                  type: object
                  properties:
                    marriage_month:
                      type: number
                      description: The person's marriage month.
                      example: 3
                    marriage_year:
                      type: number
                      description: The person's marriage year.
                      example: 2020
                addresses:
                  type: array
                  description: Addresses associated with the person.
                  items:
                    type: object
                    properties:
                      is_current:
                        type: boolean
                        description: >-
                          A value of "true" signifies that this is the person’s
                          current address, while “false” signifies that it is
                          not.
                      state:
                        type: string
                        description: The state associated with the person.
                        example: PA
                      street_address:
                        type: string
                        description: The street address associated with the person.
                        example: 123 Main St
                      city:
                        type: string
                        description: The city associated with the person.
                        example: Anytown
                      county:
                        type: string
                        description: The county associated with the person.
                        example: Allegheny
                      latitude:
                        type: number
                        description: >-
                          The latitude of the address associated with the
                          person.
                        example: 40.689247
                      longitude:
                        type: number
                        description: >-
                          The longitude of the address associated with the
                          person.
                        example: -74.0451471
                      zip:
                        type: string
                        description: The ZIP code associated with the person.
                        example: 11111
                      is_new:
                        type: boolean
                        description: Indicates if this address is newly added.
                        example: true
                      is_new_rank_one:
                        type: boolean
                        description: Indicates if this address is newly ranked as rank one.
                        example: true
                      street_url_path:
                        type: string
                        description: The URL path for the street address.
                        example: /Main+St+Anytown+CA+addresses
                      url_path:
                        type: string
                        description: The URL path for the person.
                        example: /CA/Anytown/123-Main-St
                      property:
                        type: object
                        properties:
                          zoned_use:
                            type: string
                            example: Single Family Residence
                          use_type:
                            type: string
                            example: Residential
                          market_value:
                            type: number
                            example: 1776000
                          last_sold_date:
                            type: string
                            example: '2023-09-04'
                          living_area:
                            type: number
                            example: 742
                          bath_total_count:
                            type: number
                            example: 2
                          bath_partial_count:
                            type: number
                            example: 1
                          bed_count:
                            type: number
                            example: 3
                          area_lot:
                            type: number
                            example: 742
                          year_built:
                            type: number
                            example: 1952
                          ownership_start_date:
                            type: string
                            example: '2000-01-03'
                          last_sold_price:
                            type: number
                            example: 156000
                          sellability:
                            type: object
                            properties:
                              retail_score:
                                type: number
                                example: 982
                          source_count:
                            type: number
                            example: 2
                          source_date:
                            type: string
                            example: '1996-01-12'
                          owners_count:
                            type: number
                            example: 1
                          valuations:
                            type: array
                            items:
                              type: object
                              properties:
                                date:
                                  type: string
                                  example: '2021-11-24'
                                market_value:
                                  type: number
                                  example: 1776000
                address_delta_count:
                  type: number
                  description: Number of address changes for this person.
                  example: 2
                emails:
                  type: array
                  description: Email addresses associated with the person.
                  items:
                    type: object
                    properties:
                      email:
                        type: string
                        description: Email associated with the person.
                        example: username@email.com
                      type:
                        type: string
                        description: Returns whether the email is Personal or Commercial.
                        example: Commercial
                      domain_name:
                        type: string
                        description: >-
                          The organization or individual associated with the
                          email.
                        example: gmail
                      source_count:
                        type: number
                        description: >-
                          The number of data sources used to generate the email
                          information.
                        example: 1
                      source_date:
                        type: string
                        description: The date when the email information was sourced.
                        example: '2023-01-15'
                      confidence_score:
                        type: number
                        description: The confidence score of the email information.
                        example: 64.25
                      is_new:
                        type: boolean
                        description: Indicates if the email is new.
                        example: true
                      is_new_rank_one:
                        type: boolean
                        description: Indicates if the email is newly ranked as rank one.
                        example: false
                email_record_delta_count:
                  type: number
                  description: Number of email record changes for this person.
                  example: 1
                social_profiles:
                  type: array
                  description: Social profiles associated with the person.
                  items:
                    type: object
                    properties:
                      network_name:
                        type: string
                        description: >-
                          The name of a social network associated with the
                          person.
                        example: Twitter
                      url:
                        type: string
                        description: >-
                          The URL of a social profile associated with the
                          person.
                        example: http://twitter.com/
                      photo_url:
                        type: string
                        description: >-
                          The URL of a social profile photo associated with the
                          person.
                        example: >-
                          https://graph.facebook.com/123/picture?type=large&redirect=true
                      display_name:
                        type: string
                        description: The display name of the social profile.
                        example: John Doe
                      last_seen_date:
                        type: string
                        description: The last seen date of the social profile.
                        example: '2023-01-15'
                      source_count:
                        type: number
                        description: >-
                          The number of data sources used to generate the social
                          profile information.
                        example: 1
                phones:
                  type: array
                  description: Phone numbers associated with the person.
                  items:
                    type: object
                    properties:
                      phone:
                        type: string
                        description: Phone Number associated with the person.
                        example: 5551234567
                      activity_status:
                        type: string
                        description: >-
                          Returns whether the phone line is “Active” or
                          “Inactive”.
                        example: Active
                      line_type:
                        type: string
                        description: >-
                          Returns whether the phone line is “Landline”,
                          “Wireless”, or “VOIP”.
                        example: Wireless
                      city:
                        type: string
                        description: The city associated with the phone number's area code.
                        example: Anytown
                      state:
                        type: string
                        description: >-
                          The state associated with the phone number's area
                          code.
                        example: PA
                      listing_type:
                        type: string
                        description: >-
                          Returns whether the phone service is “Residential”,
                          “Business”, or “Special Services”.
                        example: Unknown
                      carrier:
                        type: string
                        description: The company providing the phone service.
                        example: AT&T Mobility
                      source_count:
                        type: number
                        description: >-
                          The number of data sources used to generate the phone
                          information.
                        example: 1
                      is_valid:
                        type: boolean
                        description: >-
                          A value of "true" signifies that the phone number is
                          properly formed and assigned to a carrier.
                        example: true
                      reputation:
                        type: object
                        properties:
                          risk_level:
                            type: string
                            description: The risk level associated with the phone number.
                            example: Low
                      source_date:
                        type: string
                        description: The date when the phone information was sourced.
                        example: '2023-01-15'
                      time_zone_name:
                        type: string
                        description: The time zone name associated with the phone number.
                        example: America/New_York
                      confidence_score:
                        type: number
                        description: >-
                          A score indicating the confidence level of the phone
                          information.
                        example: 58.36
                      is_new:
                        type: boolean
                        description: Indicates if the phone number is new.
                        example: true
                      is_new_rank_one:
                        type: boolean
                        description: >-
                          Indicates if the phone number is newly ranked as rank
                          one.
                        example: false
                      start_date:
                        type: string
                        description: The start date of the phone number association.
                        example: '2020-01-01'
                      end_date:
                        type: string
                        description: The end date of the phone number association.
                        example: '2023-12-31'
                phone_record_delta_count:
                  type: number
                  description: The number of changes made to the phone record.
                  example: 2
                relatives:
                  type: array
                  description: Relatives associated with the person.
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                        description: >-
                          A unique Spokeo identifier associated with the
                          relative. Input this ID into Person ID Search to
                          retrieve person data, including contact information.
                        example: 1234567890
                      names:
                        type: array
                        items:
                          type: object
                          properties:
                            full_name:
                              type: string
                              description: The relative’s full name.
                              example: Jane Joan Doe Jr.
                            first_name:
                              type: string
                              description: The relative’s first name.
                              example: Jane
                            middle_name:
                              type: string
                              description: The relative’s middle name.
                              example: Joan
                            last_name:
                              type: string
                              description: The relative’s last name.
                              example: Doe
                            suffix:
                              type: string
                              description: The relative’s suffix.
                              example: Jr.
                            name_type:
                              type: string
                              description: The name type of this record.
                              example: main
                      dob_month:
                        type: number
                        description: The month of the relative's date of birth.
                        example: 5
                      dob_year:
                        type: number
                        description: The year of the relative's date of birth.
                        example: 1950
                      is_deceased:
                        type: boolean
                        description: >-
                          A value of "true" signifies that the relative is
                          deceased, while "false" signifies that the relative is
                          alive.
                      death_year:
                        type: number
                        description: The year of the relative’s death.
                        example: 2010
                      death_month:
                        type: number
                        description: The month of the relative’s death.
                        example: 11
                      gender:
                        type: string
                        description: The relative’s gender.
                        example: Female
                      marital_status:
                        type: string
                        description: The relative's marital status.
                        example: Married
                      addresses:
                        type: array
                        items:
                          type: object
                          properties:
                            street_address:
                              type: string
                              description: The street address associated with the relative.
                              example: 123 Main St
                            city:
                              type: string
                              description: The city associated with the relative.
                              example: Anytown
                            state:
                              type: string
                              description: The state associated with the relative.
                              example: SC
                            start_year:
                              type: number
                              description: >-
                                The year the relative started living at this
                                address.
                              example: 2000
                            start_month:
                              type: number
                              description: >-
                                The month the relative started living at this
                                address.
                              example: 6
                            end_year:
                              type: number
                              description: >-
                                The year the relative stopped living at this
                                address.
                              example: 2010
                            end_month:
                              type: number
                              description: >-
                                The month the relative stopped living at this
                                address.
                              example: 12
                            coresidence_start_year:
                              type: number
                              description: >-
                                The year the relative started living with the
                                person.
                              example: 2005
                            coresidence_start_month:
                              type: number
                              description: >-
                                The month the relative started living with the
                                person.
                              example: 3
                            coresidence_end_year:
                              type: number
                              description: >-
                                The year the relative stopped living with the
                                person.
                              example: 2015
                            coresidence_end_month:
                              type: number
                              description: >-
                                The month the relative stopped living with the
                                person.
                              example: 8
                work_history:
                  type: array
                  description: Jobs the person held.
                  items:
                    type: object
                    properties:
                      is_current:
                        type: boolean
                        description: >-
                          A value of "true" signifies that the person is still
                          employed in the job, while "false" signifies that the
                          person is not.
                      start_date:
                        type: string
                        description: The date the person started working at the job.
                        example: '2003-04-28'
                      end_date:
                        type: string
                        description: The date the person finished working at the job.
                        example: '2003-04-28'
                      company_name:
                        type: string
                        description: The name of the company.
                        example: Company Name Inc
                      title:
                        type: string
                        description: The job title of the person.
                        example: Software Engineer
                schools:
                  type: array
                  description: Schools the person attended.
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                        description: The school the person attended.
                        example: Anytown University
                      start_date:
                        type: string
                        description: The date the person starting attending the school.
                        example: 2025
                      type:
                        type: string
                        description: The type of school the person attended.
                        example: post-secondary institution
                      location:
                        type: string
                        description: The location of the school the person attended
                        example: Anytown, CA
                      majors:
                        type: array
                        description: The major(s) the person studied at the school
                        items:
                          type: object
                          properties:
                            name:
                              type: string
                              example: business
                certifications:
                  type: array
                  description: Certifications the person received.
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                        description: Name of certification the person attained.
                        example: certified software engineer
                      organization:
                        type: string
                        description: >-
                          The name of organation the person attained
                          certication.
                        example: some coding school
                      start_date:
                        type: string
                        description: The date the person started the certification program.
                        example: 2020-06
                      end_date:
                        type: string
                        description: The date the person ended the certication program.
                        example: 2022-08
                languages:
                  type: array
                  description: Languages the person speaks.
                  items:
                    type: object
                    properties:
                      language:
                        type: string
                        description: The name of the language.
                        example: English
                      proficiency:
                        type: string
                        description: The proficiency level in the language.
                        example: fluent
                historical_records:
                  type: array
                  description: Historical records of the person.
                  items:
                    type: object
                    properties:
                      record_type:
                        type: string
                        description: The type of historical record.
                        example: census
                      event_year:
                        type: number
                        description: The year of the historical record.
                        example: 1996
                      event_month:
                        type: number
                        description: The month of the historical record.
                        example: 3
                      relatives:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              description: A unique person identifier.
                              example: 1234567890
                            relation_type:
                              type: string
                              description: The type of relationship to the person.
                              example: spouse
                            names:
                              type: array
                              items:
                                type: object
                                properties:
                                  full_name:
                                    type: string
                                    description: The person's full name.
                                    example: Jane Joan Doe
                                  first_name:
                                    type: string
                                    description: The person's first name.
                                    example: Jane
                                  middle_name:
                                    type: string
                                    description: The person's middle name.
                                    example: Joan
                                  last_name:
                                    type: string
                                    description: The person's last name.
                                    example: Doe
                                  maiden_name:
                                    type: string
                                    description: The person's maiden name.
                                    example: Smith
                      names:
                        type: array
                        items:
                          type: object
                          properties:
                            full_name:
                              type: string
                              description: The person's full name.
                              example: John James Doe
                            first_name:
                              type: string
                              description: The person's first name.
                              example: John
                            middle_name:
                              type: string
                              description: The person's middle name.
                              example: James
                            last_name:
                              type: string
                              description: The person's last name.
                              example: Doe
                            maiden_name:
                              type: string
                              description: The person's maiden name.
                              example: Smith
                      birth:
                        type: object
                        properties:
                          dob_month:
                            type: number
                            description: The month of birth.
                            example: 12
                          dob_year:
                            type: number
                            description: The year of birth.
                            example: 1980
                          dob_zodiac:
                            type: string
                            description: The zodiac sign of the person.
                            example: Sagittarius
                      death:
                        type: object
                        properties:
                          is_deceased:
                            type: boolean
                            description: Indicates if the person is deceased.
                            example: true
                      address:
                        type: object
                        properties:
                          city:
                            type: string
                            description: The city of the person's address.
                            example: Anytown
                          location:
                            type: string
                            description: The location of the person's address.
                            example: Greater Anytown
                          state:
                            type: string
                            description: The state of the person's address.
                            example: CA
        metadata:
          type: object
    Email:
      type: object
      properties:
        data:
          type: object
          properties:
            owners:
              type: array
              items:
                type: object
                properties:
                  first_name:
                    type: string
                    description: The person's first name.
                    example: John
                  last_name:
                    type: string
                    description: The person's last name.
                    example: Smith
                  id:
                    type: string
                    description: >
                      A unique Spokeo identifier associated with the person.
                      Input this ID into **[Person ID
                      Search](/apis/openapi/person-id-search)** to retrieve
                      person data, including contact information.
                    example: 1234567890
                  phones:
                    type: array
                    description: Phone numbers associated with the person.
                    items:
                      example: 555-555-1234
                  age:
                    type: number
                    description: The person’s current age or age at death.
                    example: 62
                  dob_month:
                    type: number
                    description: The person's birth month.
                    example: 3
                  dob_year:
                    type: number
                    description: The person's birth year.
                    example: 1960
                  current_address:
                    type: object
                    description: Address associated with the person.
                    properties:
                      street_address:
                        type: string
                        description: The street address associated with the person.
                        example: 123 Main St
                      city:
                        type: string
                        description: The city associated with the person.
                        example: Anytown
                      latitude:
                        type: number
                        description: >-
                          The latitude of the address associated with the
                          person.
                        example: 40.689247
                      longitude:
                        type: number
                        description: >-
                          The longitude of the address associated with the
                          person.
                        example: -74.0451471
                      state:
                        type: string
                        description: The state associated with the person.
                        example: AN
                      zip:
                        type: string
                        description: The ZIP code associated with the person.
                        example: 12345
                  emails:
                    type: array
                    description: Other email addresses associated with the person.
                    items:
                      type: object
                      properties:
                        email:
                          type: string
                          description: The email address associated with the person.
                          example: someone@gmail.com
                        chronology_rank:
                          type: number
                          description: >-
                            The rank of the email address associated with the
                            person.
                          example: 1
                  social_profiles:
                    type: array
                    description: Social profiles associated with the person.
                    items:
                      type: object
                      properties:
                        profile_url:
                          type: string
                          description: >-
                            The URL of a social media profile associated with
                            the person.
                          example: https://www.facebook.com/tangtalks
                        profile_photo_url:
                          type: string
                          description: >-
                            The URL of a social media profile photo associated
                            with the person.
                          example: >-
                            https://graph.facebook.com/123/picture?type=large&redirect=true
                        network:
                          type: string
                          description: The social media network associated with the person.
                          example: facebook
                        username:
                          type: string
                          description: The username associated with the person.
                          example: tangtalks
                        display_name:
                          type: string
                          description: The display name associated with the person.
                          example: TangTalks
                  work_history:
                    type: array
                    description: Jobs the person held.
                    items:
                      type: object
                      properties:
                        title:
                          type: string
                          description: The person’s job title.
                          example: Product Manager
                        company_name:
                          type: string
                          description: The name of the company.
                          example: Spokeo
                        is_current:
                          type: boolean
                          description: >-
                            A value of "true" signifies that the person is still
                            employed in the job, while "false" signifies that
                            the person is not.
                        start_date:
                          type: string
                          description: The date the person started working at the job.
                          example: 2010
                        end_date:
                          type: string
                          description: The date the person finished working at the job.
                          example: 2012
                  schools:
                    type: array
                    description: Schools the person attended.
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                          description: The school the person attended.
                          example: California State University
                        start_date:
                          type: string
                          description: The date the person started attending the school.
                          example: 2010
                        end_date:
                          type: string
                          description: The date the person finished attending the school.
                          example: 2012
                        degrees:
                          type: array
                          description: >-
                            The type of degree(s) the person obtained from the
                            school.
                          example: master of science
            social_profiles:
              type: array
              items:
                type: object
                properties:
                  profile_url:
                    type: string
                    description: >-
                      The URL of a social media profile associated with the
                      social profile
                    example: https://www.facebook.com/tangtalks
                  profile_photo_url:
                    type: string
                    description: >-
                      The URL of a social media profile photo associated with
                      the social profile
                    example: >-
                      https://graph.facebook.com/123/picture?type=large&redirect=true
                  network:
                    type: string
                    description: >-
                      The social media network associated with the social
                      profile
                    example: facebook
                  username:
                    type: string
                    description: The username associated with the social profile
                    example: tangtalks
                  display_name:
                    type: string
                    description: The display name associated with the social profile
                    example: TangTalks
                  search_term:
                    type: string
                    description: >-
                      The matching search term. It can be either a username or
                      email.
                    example: someone@gmail.com
                  is_primary_match:
                    type: boolean
                    description: >-
                      A value of "true" signifies that the social profile was
                      matched by the search query.
                    example: true
                  match_type:
                    type: string
                    description: >-
                      This indicates whether the match type is by email or
                      username
                    example: email
        metadata:
          type: object
          properties:
            total_owner_count:
              type: number
              description: >-
                The total count in the array of owners returned based on your
                search inputs.
              example: 1
            total_social_profiles:
              type: number
              description: >-
                The total count in the array of social profiles returned based
                on your search inputs.
              example: 1
    Username:
      type: object
      properties:
        data:
          type: object
          properties:
            social_profiles:
              type: array
              items:
                type: object
                properties:
                  profile_url:
                    type: string
                    example: https://www.facebook.com/tangtalks
                    description: >-
                      The URL of a social media profile associated with the
                      social profile
                  profile_photo_url:
                    type: string
                    example: >-
                      https://graph.facebook.com/123/picture?type=large&redirect=true
                    description: >-
                      The URL of a social media profile photo associated with
                      the social profile
                  network:
                    type: string
                    example: facebook
                    description: >-
                      The social media network associated with the social
                      profile
                  username:
                    type: string
                    example: tangtalks
                    description: The username associated with the social profile
                  display_name:
                    type: string
                    example: TangTalks
                    description: The display name associated with the social profile
                  search_term:
                    type: string
                    example: tangtalks
                    description: >-
                      The matching search term. It can be either a username or
                      email.
                  is_primary_match:
                    type: boolean
                    example: true
                    description: >-
                      A value of "true" signifies that the social profile was
                      matched by the search query.
                  match_type:
                    type: string
                    example: username
                    description: >-
                      This indicates whether the match type is by email or
                      username
        metadata:
          type: object
          properties:
            total_social_profiles:
              type: number
              description: >-
                The total count in the array of social profiles returned based
                on your search inputs.
              example: 1
