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 · Python SDK

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-client

Check 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


Did this page help you?