Tools reference

• lookup_contact: Look up a contact
• lookup_contacts: Look up a contact list
• get_list_result: Get a list result
• get_account: Show account
• search_knowledge: Search help articles
• report_wrong_number: Report a wrong number

lookup_contact · Look up a contact

One lookup, answered at once. Give exactly one of the forms below. The kind field picks a lookup at an address other than contacts: one of "contacts", "property", "owner_check", "phone_check", "nearby", "business".

Contacts at an address keep owners and residents apart: the result lists the owner names on record in owners and marks each person with is_owner. When an owner is on record and none of the residents is that owner, the reply says so in one line, for example "Owner on record: Morgan Lee, not among the residents.". Wherever owners appear (contacts at an address and the owner check), the result carries owner_mailing_address and owner_occupied, and the reply adds "Owner mailing address: 77 Lake Drive, Dallas, TX 75201." only when the owner gets mail somewhere else.

An owner check with an address alone gives the owner names on record. A phone check answers one of three ways: "Yes: (512) 555-0142 is on record for Taylor Brooks at 1200 Oak Street, Austin, TX 78704.", "No: this number is not on record for anyone at 1200 Oak Street, Austin, TX 78704.", or "The number is on record at 1200 Oak Street, Austin, TX 78704, but for Taylor Brooks, not Morgan Lee.".

Forms

• Contacts at an address: address, optionally with a full name. 1 credit when found. The result also lists the owners on record, marks each person who is an owner, and gives the owner mailing address when it differs from the home.
• Owner of a phone number: phone. 1 credit when found.
• Owner of an email address: email. 1 credit when found.
• A person by name: first_name and last_name with a city and state, or a ZIP code. 1 credit when exactly one person matches.
• Property attributes (type, year built, square footage, beds, baths, lot size, value, last sale): kind "property" with an address. 1 credit when the property is on record.
• Owner check: kind "owner_check" with an address. With a name it answers yes or no (is this person an owner) and lists the owner names on record; without a name it lists the owner names on record. It also gives the owner mailing address when it differs from the home. 1 credit per answer; free when no owner is on record.
• Phone check (is this number on record for someone at this address): kind "phone_check" with an address and a phone, optionally with a full name. Answers yes with the person, no, or that the number belongs to another person than the name given. 1 credit per answer; free when nobody is on record at the address.
• Nearby homes with their contacts, nearest first: kind "nearby" with an address and an optional limit (default 10, at most 25). 1 credit per home returned with contacts.
• Business: kind "business" with an address, or with business_name and a city and state or a ZIP code. Returns the business listed at the address (name, category, phone, website), the owners on record, whether an owner is a company, and the officers on file with the state business registry. 1 credit when a business or a company owner is found; free otherwise. Set contacts to true to also look up the officers' contacts (up to limit officers, default 2), 1 credit per person found.

Options

• limit: the most results to return (1 to 25).
• active_phones_only: true keeps only numbers our records mark as active in the last 12 months; it is a usage signal, not a live line test.
• match: "relaxed" (default) accepts a close spelling of the name; "exact" needs the full first and last name on the record.
• People carry age, gender and job when the record has them; a missing field means it is not on record.

Business lookup

Set kind to "business" and give an address, or a business_name with a city and state or a zip. The answer has the business listed at this address (name, category, phone, website), the owner on record with owner_is_entity (true when the owner is a company), the owner mailing address, whether the owner occupies the building, and the officers of the owner company on file with the state business registry.

With contacts: true, Scout Data also looks up the officers as people and fills people with their phones and emails; limit sets the most officers to look up (default 2). Without it, people stays empty. The reply then adds one line, "Contacts found for: Jane Doe (Manager), John Roe (President).", or, when none are found, "No contacts were found for the officers."

Credits: 1 credit when a business or a company owner is found, once per property. Each officer looked up with contacts: true costs 1 credit per match. Free when no business is listed and no company owns the property.

• "What business is at 700 Harness Lane, Austin, TX 78701 and who owns it?"
• "Reach the owner of the business at 700 Harness Lane, Austin, TX 78701."
• "Find Harnessbake Cafe in Austin, TX and tell me who owns the building."

When no business is listed and a person owns the property:

When the state business registry is not in our records:

Inputs

• addresstext · optionalStreet address with city, state and ZIP in one line.
• nametext · optionalFull name. With an address alone: the person to find there. With an owner check or a phone check: the name to check.
• phonetext · optionalA US phone number with 10 digits.
• emailtext · email · optionalAn email address.
• first_nametext · optionalFirst name, for a person lookup by name, or the name to check.
• last_nametext · optionalLast name, together with first_name.
• citytext · optionalCity of the person or the business, together with state.
• statetext · optionalState of the person or the business, together with city.
• ziptext · zip · optionalZIP code of the person or the business, five digits or ZIP+4. Can replace city and state.
• kindone of · contacts, property, owner_check, phone_check, nearby, business · optionalWhat to look up at an address. Leave it out for contacts.
• limitnumber · 1 to 25 · optionalThe most results to return. For nearby homes, the number of homes. For a business with contacts, the most officers to look up.
• active_phones_onlytrue or false · optionalTrue keeps only numbers our records mark as active in the last 12 months.
• matchone of · exact, relaxed · optionalHow close the name must be: relaxed (the default) accepts a close spelling, exact needs the full first and last name.
• known_phoneslist of text · up to 5 items · optionalLists with fill_missing only: phones you already have for this row.
• known_emailslist of text · email · up to 5 items · optionalLists with fill_missing only: emails you already have for this row.
• business_nametext · optionalFor kind business: the name of the business, with a city and state or a ZIP code.
• contactstrue or false · optionalFor kind business: true also looks up the officers as people, with their phones and emails.

What comes back

• statusone of · ok, no_match, ambiguous, unsupported, insufficient_credits, error, keptThe outcome. kept marks a list row that kept its own values.
• peoplelist of objectsThe people found, each with phones and emails. For a business, filled only when contacts ran.
  • nametextFull name.
  • phoneslist of objectsPhone numbers of the person.
    • numbertextThe phone number.
    • typetext · can be missingThe line type, such as mobile, when known.
    • dnctrue or false · can be missingTrue when the number is on a do-not-call registry.
    • activetrue or false · can be missingTrue when our records show the number in use in the last 12 months.
  • emailslist of textEmail addresses of the person.
  • addresstext · can be missingThe address on record for the person.
  • agenumber · can be missingAge, when on record.
  • gendertext · can be missingGender, when on record.
  • jobtext · can be missingJob, when on record.
  • is_ownertrue or false · can be missingTrue when the person is an owner of the home on record, false when not.
• candidateslist of objects · can be missingFor an ambiguous name only: the people who match, with name and location and no contacts. Nothing is charged.
  • nametextName of the candidate.
  • locationtextCity and state of the candidate.
• propertynamed values · can be missingFor kind property: the home facts, such as property type, year built, square footage, beds, baths, lot size, value and last sale.
• owner_checkobject · can be missingFor kind owner_check: the answer and the owner names on record.
  • is_ownertrue or false · can be missingYes or no for the name given. Missing when no name was given.
  • owner_nameslist of textThe owner names on record.
• ownerslist of text · can be missingFor contacts at an address and for a business: the owner names on record. Can be empty.
• owner_mailing_addresstext · can be missingWhere the owner gets mail, when it differs from the home. Empty when it is the home or not on record.
• owner_occupiedtrue or false · can be missingTrue when the owner lives in the home, false when not, empty when unknown.
• phone_checkobject · can be missingFor kind phone_check: whether the number is on record at the address, and for whom.
  • on_recordtrue or falseTrue when the number is on record for someone at the address.
  • persontext · can be missingThe person the number is on record for. Empty when not on record.
  • name_matchestrue or false · can be missingWith a name given: whether it is that person. Empty without a name.
• businessobject · can be missingFor kind business: the business listed at this address. Empty when none is listed.
  • nametextName of the business.
  • categorytext · can be missingWhat kind of business it is, when known.
  • phonetext · can be missingPhone number of the business, when listed.
  • websitetext · can be missingWebsite of the business, when listed.
  • addresstext · can be missingAddress of the business.
• owner_is_entitytrue or false · can be missingFor a business: true when the owner on record is a company, false when it is a person, empty when unknown.
• officerslist of objects · can be missingFor a business: the officers of the owner company on file with the state business registry.
  • nametextName of the officer.
  • titletext · can be missingTitle on file, such as Manager or President.
  • citytext · can be missingCity on file for the officer.
  • statetext · can be missingState on file for the officer.
• registryobject · can be missingFor a business: the filing of the owner company in the state business registry. Empty when none is found.
  • entity_idtext · can be missingThe filing number in that state.
  • statetextThe state of the filing.
• homeslist of objects · can be missingFor kind nearby: the homes near the address, nearest first.
  • addresstextAddress of the home.
  • distance_feetnumberDistance from the address you gave, in feet.
  • peoplelist of objectsThe people at the home, each shaped like the people above.
    • nametext
    • phoneslist of objects
      • numbertext
      • typetext · can be missing
      • dnctrue or false · can be missing
      • activetrue or false · can be missing
    • emailslist of text
    • addresstext · can be missing
    • agenumber · can be missing
    • gendertext · can be missing
    • jobtext · can be missing
    • is_ownertrue or false · can be missing
• lookup_idtext · can be missingThe id of this lookup. Give it when you report a wrong number.
• chargednumberCredits charged for this lookup.
• balancenumberCredits left on the account.
• account_urltext · urlLink to your Scout Data account page.
• messagetextThe reply in plain words, ending with the credits used and left.

Credits

Each form above names its price. A lookup with no match is free. You pay once per property: when you already paid for a home, its result comes back in full and free with one notice, "You unlocked this record earlier, so no credit was charged.". Owners, the owner mailing address and the owner-occupied answer cost nothing extra.

Example prompts

• "Who lives at 1200 Oak Street, Austin, TX 78704? Show the owner and the residents separately."
• "Where can I contact the owner of 1200 Oak Street, Austin, TX 78704 if they live elsewhere?"
• "Does (512) 555-0142 belong to the person at 1200 Oak Street, Austin, TX 78704?"

Example reply

lookup_contacts · Look up a contact list

A list of 1 to 1,000 rows, started at once with no confirmation step. Each row is one lookup_contact form with its options, and a list can mix forms. The first reply states the most the list can cost and your credits left. A short list finishes in the same reply; a longer one keeps running, and get_list_result fetches it.

With fill_missing set to true, a row can carry known_phones and known_emails (up to 5 each) beside an address, an address and a name, or a name with a location. A row that already has a phone and an email is kept as it is and is free. Every other row is looked up: your values come first, the found ones are added after, and duplicates are removed. Details are on the Lists page.

Inputs

• rowslist of objects · 1 to 1,000 items · requiredThe rows. Each row is one lookup_contact form with its options.
• labeltext · optionalYour name for the list.
• fill_missingtrue or false · optionalTrue to fill only what is missing: rows can then carry known_phones and known_emails.

What comes back

• statusone of · done, running, insufficient_credits, errorThe state of the list. With insufficient_credits nothing ran and nothing was charged.
• list_idtext · can be missingThe id of the list. Give it to get_list_result or with a wrong-number report.
• download_urltext · url · can be missingLink to the full result as a CSV file, valid for 24 hours.
• summaryobjectThe counts of the list.
  • rowsnumberRows in the list.
  • matchednumberRows that found a match.
  • no_matchnumberRows with no match. They are free.
  • keptnumber · can be missingRows that kept their own values in a fill_missing list. They are free.
  • max_costnumber · can be missingThe most the list can cost, stated when it starts.
  • chargednumberCredits charged for the list.
  • balancenumberCredits left on the account.
• previewlist of objects · up to 20 itemsThe first 20 rows, each shaped like a lookup_contact result.
• account_urltext · urlLink to your Scout Data account page.
• messagetext · can be missingThe reply in plain words.

Credits

The maximum cost is the sum of the row prices. Rows with no match are free, kept rows are free, and rows for a home you already paid for are free. You are charged only for the rows that match.

Example prompts

• "Look up the contacts at these 3 addresses and give me a file."
• "Add missing phones and emails to this list. Keep existing values."
• "Check these 200 addresses against the phone numbers I have and flag the mismatches."

Example reply

get_list_result · Get a list result

Fetches a list started with lookup_contacts: its status, the summary, the first 20 rows and a new download link. Use it for a list that is still running, or to get a fresh link to the file.

Inputs

• list_idtext · requiredThe list id from lookup_contacts.

What comes back

• statusone of · done, running, insufficient_credits, errorThe state of the list. With insufficient_credits nothing ran and nothing was charged.
• list_idtext · can be missingThe id of the list. Give it to get_list_result or with a wrong-number report.
• download_urltext · url · can be missingLink to the full result as a CSV file, valid for 24 hours.
• summaryobjectThe counts of the list.
  • rowsnumberRows in the list.
  • matchednumberRows that found a match.
  • no_matchnumberRows with no match. They are free.
  • keptnumber · can be missingRows that kept their own values in a fill_missing list. They are free.
  • max_costnumber · can be missingThe most the list can cost, stated when it starts.
  • chargednumberCredits charged for the list.
  • balancenumberCredits left on the account.
• previewlist of objects · up to 20 itemsThe first 20 rows, each shaped like a lookup_contact result.
• account_urltext · urlLink to your Scout Data account page.
• messagetext · can be missingThe reply in plain words.

Credits

Free. Asking again never charges the list again.

Example prompts

• "Is my list done?"
• "Give me a new link to the file of my last list."

Example reply

get_account · Show account

Shows your Scout Data account: the credits left, the free credits you received, the credits used, the link to your account page and what you can ask for.

Inputs

No inputs.

What comes back

• team_nametextThe name of your Scout Data account.
• balancenumberCredits left.
• free_credits_grantednumberFree credits the account received.
• credits_usednumberCredits used so far.
• signup_sourcetext · can be missingWhere the account was created.
• account_urltext · urlLink to your Scout Data account page.
• messagetextThe account reply in plain words, with what you can ask for.

Credits

Free.

Example prompts

• "How many Scout Data credits do I have?"
• "What can Scout Data do?"

Example reply

search_knowledge · Search help articles

Searches the Scout Data help articles and returns up to 4 passages. The assistant answers questions about the service only from these passages.

Inputs

• querytext · requiredYour question in plain words.

What comes back

• passageslist of objects · up to 4 itemsPassages from the help articles that answer the question.
  • titletextTitle of the article.
  • texttextThe passage.
  • urltext · url · can be missingLink to the article, when it has one.

Credits

Free.

Example prompts

• "How does Scout Data charge for a list?"
• "What does active phones only mean?"

Example reply

report_wrong_number · Report a wrong number

Reports phone numbers from your lookups that turned out to be wrong, 1 to 50 at a time, and gives another number for the same person when one is known. It stores the report, so the same number is never replaced twice. Details are on the Wrong numbers page.

Inputs

• rowslist of objects · 1 to 50 items · requiredThe numbers to report.
  • phonetext · requiredThe wrong phone number.
  • lookup_idtext · optionalThe lookup id the number came from, when known.
  • list_idtext · optionalThe list id the number came from, when known.
  • nametext · optionalThe person the number was for, when you know it.

What comes back

• resultslist of objects · up to 50 itemsOne answer per number reported.
  • phonetextThe number reported.
  • statusone of · replaced, no_other_number, not_from_your_lookups, already_reported, over_limitWhat happened to the report.
  • replacement_phoneslist of objectsOther numbers for the same person, when one is known.
    • numbertextThe phone number.
    • typetext · can be missingThe line type, such as mobile, when known.
    • dnctrue or false · can be missingTrue when the number is on a do-not-call registry.
  • messagetextThe answer in plain words.
• account_urltext · urlLink to your Scout Data account page.

Credits

Free.

Example prompts

• "The number (512) 555-0142 from that lookup was wrong."
• "Two numbers in my last list were wrong: (512) 555-0142 and (512) 555-0187."

Example reply

Next: Lists

Get help: write to [email protected], or ask the assistant a question about Scout Data and it answers from the help articles.