Custom Packages

Define exactly which searches run in a background check by creating custom packages.

What are packages?

A package is a named collection of searches that run together when you create a background check. Instead of specifying individual search types on every API call, you reference a package slug and Gonos resolves it to the configured searches.

Default packages

Gonos ships with three system-wide packages available to all organizations:

System packages cannot be modified or deleted. To customize, create an org-specific package with the same slug to override a system default, or use a new slug.

SSN trace requirement

Every package should include an ssn_trace search. The SSN trace is the foundation of identity verification and is required to resolve addresses for county-level criminal searches. Packages without an SSN trace may produce incomplete results.

Creating a custom package via API

# Create a custom package
curl -X POST https://api.gonos.co/api/v1/admin/packages \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "gig-driver",
    "name": "Gig Driver Package",
    "description": "Tailored for rideshare and delivery drivers",
    "searches": [
      {"item_type": "ssn_trace", "data_source": "wholesale_provider"},
      {"item_type": "federal_criminal", "data_source": "pacer"},
      {"item_type": "state_criminal", "data_source": "wholesale_provider"},
      {"item_type": "sex_offender", "data_source": "nsopw"},
      {"item_type": "ofac", "data_source": "ofac_sdn"}
    ]
  }'

Using the Python SDK

from gonos_sdk import GonosClient

client = GonosClient(api_key="gn_live_your_key_here")

# Create a custom package
package = client.packages.create(
    slug="gig-driver",
    name="Gig Driver Package",
    description="Tailored for rideshare and delivery drivers",
    searches=[
        {"item_type": "ssn_trace", "data_source": "wholesale_provider"},
        {"item_type": "federal_criminal", "data_source": "pacer"},
        {"item_type": "state_criminal", "data_source": "wholesale_provider"},
        {"item_type": "sex_offender", "data_source": "nsopw"},
        {"item_type": "ofac", "data_source": "ofac_sdn"},
    ],
)

# Use it when creating a check
check = client.checks.create(
    candidate_id=candidate.id,
    package="gig-driver",
    permissible_purpose="employment",
)

Updating a package

You can update the name, description, searches, or active status of custom packages. System packages cannot be modified. If active checks are using a package, you cannot change its searches until those checks complete.

# Update a custom package
curl -X PATCH https://api.gonos.co/api/v1/admin/packages/<package_id> \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Gig Driver Package v2",
    "searches": [
      {"item_type": "ssn_trace", "data_source": "wholesale_provider"},
      {"item_type": "federal_criminal", "data_source": "pacer"},
      {"item_type": "state_criminal", "data_source": "wholesale_provider"},
      {"item_type": "county_criminal", "data_source": "wholesale_provider"},
      {"item_type": "sex_offender", "data_source": "nsopw"},
      {"item_type": "ofac", "data_source": "ofac_sdn"}
    ]
  }'

Package snapshots

When a check is created, Gonos saves a package snapshot — the exact list of searches that were resolved at creation time. Even if the package is later modified, the check record preserves exactly what searches were run. This is critical for FCRA audit compliance.

Available search types

Next steps

• Quickstart — run your first background check
• Webhooks — get notified when checks complete
• Interactive API docs — try package endpoints in your browser