Connect through API
Connect Pearch to your backend over HTTP or with the official Python SDK. Use this path when your product calls Pearch directly.
Building with a coding agent? Start with the full API integration instructions.
Create your API key
Create a key in Platform → API keys. Store it as PEARCH_API_KEY in your backend’s secret configuration. Use the following in a local terminal to try the examples.
export PEARCH_API_KEY="YOUR_API_KEY"Connect your backend
Use Authorization: Bearer <YOUR_API_KEY> from your server.
HTTP requests
Check the connection
GET /v1/user checks the account, available credits, and prices without using credits. Keep the full response out of logs because it includes the API key.
curl --request GET "https://api.pearch.ai/v1/user" \
--header "Authorization: Bearer $PEARCH_API_KEY"Run a small people search
Review the search requirements before running the request. Search uses workspace credits.
curl --request POST "https://api.pearch.ai/v2/search" \
--header "Authorization: Bearer $PEARCH_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"search_requirements": [
{
"search_requirement": "Current or recent experience as a Senior Backend Engineer.",
"must_have": true
},
{
"search_requirement": "Hands-on experience building production applications with Python.",
"must_have": true
},
{
"search_requirement": "Based in London or Berlin.",
"must_have": false
}
],
"type": "pro",
"insights": true,
"limit": 10
}'Python SDK
Install the official Python SDK.
python -m pip install git+https://github.com/Pearch-ai/pearch-clientCheck your account in Python
GET /v1/user checks the account, available credits, and prices without using credits. Keep the full response out of logs because it includes the API key.
from pearch.client import PearchClient
with PearchClient() as client:
account = client.get_user()
print("Connected to Pearch.")
# The account response contains credits and prices, but also an API key.
# Inspect it privately; do not print the complete response to shared logs.Run a people search in Python
Review the search requirements before running the request. Search uses workspace credits.
from pearch.client import PearchClient
from pearch.schema import SearchRequirement, V2SearchRequest
# Set PEARCH_API_KEY in your environment before running.
request = V2SearchRequest(
search_requirements=[
SearchRequirement(
search_requirement="Current or recent experience as a Senior Backend Engineer.",
must_have=True,
),
SearchRequirement(
search_requirement="Hands-on experience building production applications with Python.",
must_have=True,
),
SearchRequirement(
search_requirement="Based in London or Berlin.",
must_have=False, # A preference, not a must-have.
),
],
type="pro",
insights=True, # Include explanations and quotes from profiles; uses insights credits.
limit=10,
)
with PearchClient() as client:
results = client.search(request)
for candidate in results.search_results or []:
if candidate.score not in (3, 4):
continue
print(candidate.docid, candidate.score)
evidence = candidate.insights.query_insights if candidate.insights else None
if not evidence:
print("No supporting evidence was returned; review the profile.")
for item in evidence or []:
print(item.subquery, item.match_level or "Not provided")
print(item.short_rationale or item.rationale or "No explanation returned")
for quote in item.short_quotes or []:
print("Profile quote:", quote)Use search_results to show the matches. Keep the search’s thread_id for pagination. For background requests, follow Asynchronous search.
Resources
Updated about 4 hours ago
