The Handbook APIthehandbook.com ↗
Search The Handbook database of celebrities, influencers, and industry professionals. Retrieve agent, manager, and publicist contact details via 3 endpoints.
What is the The Handbook API?
The Handbook API exposes 3 endpoints for searching and extracting profile and contact data from The Handbook's directory of celebrities, influencers, and industry professionals. The search_profiles endpoint returns name, type, social handles, social reach, and tags for matching results, while get_profile_details and get_team_contacts surface agent, manager, and publicist contact records including role, company, and variable contact details.
curl -X GET 'https://api.parse.bot/scraper/a327a0b6-ab56-4a97-8b96-60ae104eed57/search_profiles?limit=5&query=Taylor+Swift' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace thehandbook-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: The Handbook Celebrity & Influencer API — bounded, re-runnable."""
from parse_apis.the_handbook_celebrity___influencer_api import (
Handbook, ProfileSummary, Profile, Contact, ProfileNotFound,
)
client = Handbook()
# Search for celebrities — limit= caps total items fetched.
for summary in client.profilesummaries.search(query="Taylor Swift", limit=3):
print(summary.name, summary.type, summary.social_reach)
# Drill down: take one result and fetch full profile details.
hit = client.profilesummaries.search(query="Dua Lipa", limit=1).first()
if hit:
profile = hit.details()
print(profile.name, profile.industry)
for contact in profile.contacts:
print(contact.contact_name, contact.role, contact.company)
# Convenience: find a profile's team by name in one call.
beyonce = client.profiles.find_by_name(query="Beyonce")
print(beyonce.name, beyonce.industry)
for c in beyonce.contacts:
print(c.contact_name, c.role, c.company)
# Typed error handling: catch a missing profile.
try:
detail = client.profiles.get(url="https://www.thehandbook.com/celebrity/nonexistent-person/")
print(detail.name)
except ProfileNotFound as exc:
print(f"Profile not found: {exc.url}")
print("exercised: profilesummaries.search / details / profiles.get / profiles.find_by_name")
Full-text search over The Handbook's database of celebrities, influencers, and industry professionals. Returns basic profile info including name, type, social handles, reach, and profile URL. Powered by Typesense; matches against profile_name and social_handles fields. Returns a single page of results per call.
| Param | Type | Description |
|---|---|---|
| limit | integer | Maximum number of results to return. |
| queryrequired | string | Search keyword such as a celebrity or influencer name. |
{
"type": "object",
"fields": {
"page": "integer current page number",
"profiles": "array of profile summary objects with keys: id, name, type, url, thumbnail, social_handles, social_reach, tags",
"total_found": "integer total number of matching profiles"
},
"sample": {
"data": {
"page": 1,
"profiles": [
{
"id": 63414,
"url": "https://www.thehandbook.com/celebrity/taylor-swift/",
"name": "Taylor Swift",
"tags": [
"Music",
"Singers",
"Songwriters"
],
"type": "thb_celebrity",
"thumbnail": "https://files.thehandbook.com/uploads/2014/10/taylor-swift_416x416.jpg",
"social_reach": 432530798,
"social_handles": [
"@taylorswift"
]
}
],
"total_found": 2
},
"status": "success"
}
}About the The Handbook API
Search and Profile Data
The search_profiles endpoint accepts a query string and an optional limit integer. Results come back as an array of profile objects, each containing id, name, type, url, thumbnail, social_handles, social_reach, and tags. The response also includes total_found and the current page number, useful for understanding result volume even when paginating.
Detailed Profile and Contact Extraction
get_profile_details takes a full profile url (for example, https://www.thehandbook.com/celebrity/taylor-swift/) and returns the profile's name, industry, and a contacts array. Each contact object carries contact_name, role, company, and a details object whose keys vary by record — common keys include Address, Website, and similar fields. Note that some profiles carry no public contacts, and email or phone data is often gated.
One-Step Team Lookup
get_team_contacts combines search and extraction into a single call. Supply a query name and the endpoint selects the best-matching celebrity profile, then returns the same structure as get_profile_details: url, name, industry, and the contacts array. This avoids the need to parse a search result and construct a URL manually when you already know who you're looking for.
Coverage and Limitations
The Handbook focuses on celebrities, influencers, and entertainment-adjacent professionals. Contact depth varies by profile — some entries have multiple verified representatives across different roles; others have none. The details object within each contact is intentionally flexible, so field names beyond Address and Website should be treated as variable when parsing responses.
The The Handbook API is a managed, monitored endpoint for thehandbook.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when thehandbook.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official thehandbook.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Identify the talent agent or manager for a celebrity before pitching a brand collaboration using
get_team_contacts - Build an influencer outreach list by searching social handles and
social_reachfigures fromsearch_profiles - Enrich a CRM with publicist and company details for entertainment professionals via
get_profile_details - Filter profiles by
typeandtagsfrom search results to segment entertainment contacts by category - Automate lookup of representative contact records for a list of celebrity names using
get_team_contactsin batch - Cross-reference
industryfields from profile details to map talent to specific entertainment sectors
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does The Handbook offer an official developer API?+
What does the `contacts` array in `get_profile_details` actually contain?+
contact_name, role (such as agent, manager, or publicist), company, and a details object. The keys inside details are variable — Address and Website appear frequently, but other fields depend on what the profile has listed. Some profiles return an empty contacts array if no representative information is publicly available.Does `search_profiles` support pagination?+
page integer and a total_found integer, indicating how many profiles match the query. The limit parameter controls how many results are returned per call. There is no explicit page input parameter in the current endpoint, so navigating deep result sets beyond the first page is not directly supported. You can fork the API on Parse and revise it to add an offset or page input parameter.Does the API return email addresses or phone numbers for contacts?+
details object within each contact may include such fields where they are publicly listed, but coverage is inconsistent and many profiles will not expose this information. The API covers what is publicly accessible on the profile pages.Can the API retrieve profiles for non-celebrity professionals like PR executives or casting directors?+
type and tags fields in search results and the industry field in profile details indicate the category of each entry, and The Handbook's database does include industry professionals beyond celebrities. However, the endpoints do not currently support filtering searches by type or industry directly. You can fork the API on Parse and revise it to add a type or industry filter parameter to search_profiles.