Python SDK

Typed Python client for the Gonos background check API.

Installation

pip install gonos-sdk

Quick start

from gonos_sdk import GonosClient

client = GonosClient(api_key="your-api-key")

# Create a candidate
candidate = client.candidates.create(
    first_name="Jane",
    last_name="Doe",
    email="jane@example.com",
    date_of_birth="1990-06-15",
)
print(f"Created candidate: {candidate.id}")

# Submit a background check
check = client.checks.create(
    candidate_id=candidate.id,
    package="standard",
    permissible_purpose="employment",
)
print(f"Check status: {check.status}")

# Get the report when ready
report = client.reports.get(check.id)
print(f"Disposition: {report.disposition}")

Resources

Error handling

from gonos_sdk import GonosClient, NotFoundError, RateLimitError

try:
    check = client.checks.get("nonexistent-id")
except NotFoundError as e:
    print(f"Not found: {e.detail}")
except RateLimitError as e:
    print(f"Rate limited, retry after {e.retry_after}s")

Exception hierarchy:

• ApiError — base exception for all API errors
• AuthenticationError — invalid or missing API key (401)
• ForbiddenError — insufficient permissions (403)
• NotFoundError — resource not found (404)
• ConflictError — duplicate resource (409)
• ValidationError — invalid request body (400/422)
• RateLimitError — too many requests (429), includes retry_after

Configuration

client = GonosClient(
    api_key="your-key",
    base_url="https://api.gonos.co",  # default
    timeout=30.0,  # seconds
)

Or use environment variables:

export GONOS_API_KEY=your-key
export GONOS_BASE_URL=https://api.gonos.co