Skip to main content

Quickstart

Run your first background check in 5 minutes.

1. Get your API key

Sign up at gonos.co/register or contact us to get your API key. Keys start with td_live_ for production or td_test_ for sandbox.

2. Install the SDK

pip install gonos-sdk

3. Create a candidate

from gonos_sdk import GonosClient

client = GonosClient(api_key="td_live_your_key_here")

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

4. Obtain consent

FCRA requires consumer consent before any background check. Create a hosted consent session — the candidate receives a link to sign.

session = client.consent.create(candidate_id=candidate.id)
print(f"Send this URL to the candidate: {session.consent_url}")

5. Initiate the check

check = client.checks.create(
    candidate_id=candidate.id,
    package="standard",           # essential | standard | complete
    permissible_purpose="employment",
)
print(f"Check status: {check.status}")  # "pending"

6. Get the report

# Poll until completed, or use webhooks for real-time notifications
report = client.reports.get(check.id)
print(f"Disposition: {report.disposition}")  # clear | consider | review

7. Set up webhooks (recommended)

Instead of polling, register a webhook to receive real-time notifications:

webhook = client.webhooks.create(
    url="https://your-app.com/webhooks/gonos",
    events=["check.completed", "report.ready", "dispute.filed"],
)
print(f"Webhook secret: {webhook.secret}")  # Save this for signature verification

Using cURL instead

# Create a candidate
curl -X POST https://api.gonos.co/api/v1/candidates \
  -H "X-API-Key: td_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"first_name": "Jane", "last_name": "Doe", "email": "jane@example.com"}'

# Create a check
curl -X POST https://api.gonos.co/api/v1/checks \
  -H "X-API-Key: td_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"candidate_id": "CANDIDATE_ID", "package": "standard", "permissible_purpose": "employment"}'

Next steps