sanctionskit

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 4, 2026 License: MIT Imports: 16 Imported by: 0

README

SanctionsKit for Go

A server-side Go client for the SanctionsKit API. It screens a subject against selected coverage, retrieves retained results and evidence, and checks source availability. Requires Go 1.26 or newer. The client uses only the Go standard library.

Install version 0.1.0:

go get github.com/SanctionsKit/sanctionskit-go@v0.1.0

Start with synthetic records

Create a free developer workspace and a sandbox key with screenings:write and results:read. The sandbox needs no card and uses fictional records. Production screening requires a plan and payment method. Keep API keys on the server.

client, err := sanctionskit.New(os.Getenv("SANCTIONSKIT_API_KEY"), nil)
if err != nil {
    return err
}

// Save this key with the business operation before sending the request.
// A retry of that operation must keep the same key and body.
requestKey := os.Getenv("REQUEST_KEY")
result, err := client.CreateScreening(ctx, sanctionskit.ScreeningRequest{
    Subject: sanctionskit.Subject{
        Name: "Alex Morgan", EntityType: "person", BirthDate: "1984",
    },
    Package: "sandbox@1", Retention: "standard",
    Reference: "example-customer-001",
}, requestKey)
if err != nil {
    return err
}
evidence, err := client.GetEvidence(ctx, result.Data.ID)
if err != nil {
    return err
}
// evidence.RawJSON contains the exact downloaded JSON bytes.
// Store evidence only in your application's authorized storage.
_ = evidence

The complete runnable program is in examples/screen. From this checkout, set SANCTIONSKIT_API_KEY and a saved REQUEST_KEY, then run go run ./examples/screen. This makes hosted sandbox requests using your key. The tests described below use local fixtures instead.

potential_match calls for review. no_match means no candidates under the selected coverage and matching rules. Neither approves a customer or provides legal clearance. An error is an incomplete request, never a no-match result. Preserve the result's coverage, versions and interpretation limits.

Methods and response shapes

Method Scope Response
CreateScreening(ctx, input, requestKey) screenings:write Response[ScreeningResult], decoded from data
GetResult(ctx, id) results:read Response[RetainedResult], decoded from data
GetEvidence(ctx, id) results:read EvidenceResponse, the direct evidence document
ListSources(ctx) sources:read Response[[]Source], decoded from data

Each response includes RequestID and the original RawJSON. Raw JSON preserves fields added by the service and publisher-specific records. Retained subject, reference and request fields can be nil when inputs were not retained. The client never reconstructs them. Evidence is not a signed attestation.

Supply exactly one coverage selector: Package or Sources. The synthetic sandbox uses sandbox@1. For production, check source availability and supported entity types with ListSources; a catalog entry alone does not establish usable coverage. An approved policy is &sanctionskit.PolicyReference{ID: id, Version: version}. Organization policies and retention requirements remain enforced by the server. This client does not include policy management, batch orchestration or monitoring.

Transport and errors

All methods accept context.Context. The default timeout is 30 seconds and the default response limit is 16 MiB. Options can set a timeout up to 120 seconds, a response limit up to 64 MiB, and a custom HTTP client. The client copies supplied HTTP settings and always refuses redirects, including redirects on the same host. Custom transports are under your control; do not add credential or body logging.

The default base is https://www.sanctionskit.com/api/v1. HTTPS is required for other hosts; plain HTTP is accepted only for loopback development. Base URLs with credentials, queries, fragments or traversal paths are rejected.

There are no application-level automatic retries. Go's standard HTTP transport may recover certain connection failures. If your application retries a screening, keep its original key and body. Do not generate a new key just because a response was lost. Non-success HTTP responses return *APIError, with StatusCode, Code, RequestID and RetryAfter. Arbitrary server messages and bodies are omitted from errors. Use errors.As to inspect the type.

Validation, transport and malformed-success failures return *ClientError. Context cancellation and deadlines remain recognizable with errors.Is. An expired retained result is an API error, commonly HTTP 410. A redirected, oversized or malformed response is never returned as successful evidence.

Local checks

go test ./...
go test -race ./...
go vet ./...

The transport tests use httptest on loopback with an invented key. Public OpenAPI examples provide synthetic screening and evidence fixtures. These tests do not use a hosted account, live sanctions records, real credentials or customer data. Local test success is separate from a hosted sandbox run and package publication.

API quickstart | Screening requests | Evidence | Idempotency

MIT licensed. Maintained by SanctionsKit. Contact support@sanctionskit.com.

Documentation

Overview

Package sanctionskit provides a server-side client for the SanctionsKit API. It screens subjects against selected coverage and retrieves retained results, evidence, and source availability. A screening result supports human review; it does not approve onboarding or provide legal clearance.

The free sandbox uses synthetic records. Production screening requires paid access. See https://www.sanctionskit.com/docs/quickstart for account and key setup.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type APIError 

type APIError struct {
	StatusCode int
	Code       string
	RequestID  string
	RetryAfter string
}

APIError describes a non-success HTTP response. It intentionally excludes arbitrary server messages and bodies, which can contain submitted information.

func (*APIError) Error 

func (e *APIError) Error() string

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is safe for concurrent use after construction. It does not log requests or responses and adds no application-level automatic retries.

func New 

func New(apiKey string, options *Options) (*Client, error)

New constructs a client. A zero timeout uses 30 seconds; a zero response limit uses 16 MiB. Limits above 120 seconds or 64 MiB are rejected.

func (*Client) CreateScreening 

func (c *Client) CreateScreening(ctx context.Context, input ScreeningRequest, idempotencyKey string) (*Response[ScreeningResult], error)

CreateScreening screens one subject. Persist idempotencyKey before sending; retries of the same business operation must keep its key and body unchanged. Requires screenings:write. The server remains authoritative on policy/access.

func (*Client) GetEvidence 

func (c *Client) GetEvidence(ctx context.Context, id string) (*EvidenceResponse, error)

GetEvidence retrieves the direct JSON evidence document and its exact bytes. Requires results:read. It checks the format and result ID before returning it.

func (*Client) GetResult 

func (c *Client) GetResult(ctx context.Context, id string) (*Response[RetainedResult], error)

GetResult retrieves a retained result, including nullable retained inputs. Requires results:read. Expired results return an APIError, often HTTP 410.

func (*Client) ListSources 

func (c *Client) ListSources(ctx context.Context) (*Response[[]Source], error)

ListSources retrieves current source capabilities and availability. Requires sources:read. The catalog alone does not authorize using a source.

type ClientError 

type ClientError struct {
	Code       string
	StatusCode int
	// contains filtered or unexported fields
}

ClientError reports validation, transport, or response-format failures without embedding the key, request URL, submitted subject, or response body.

func (*ClientError) Error 

func (e *ClientError) Error() string

func (*ClientError) Unwrap 

func (e *ClientError) Unwrap() error

Unwrap exposes only context cancellation or deadline errors, never a raw transport error containing a URL or user data.

type Coverage 

type Coverage struct {
	SourceID    string `json:"sourceId"`
	Version     string `json:"version"`
	RetrievedAt string `json:"retrievedAt"`
	Fresh       bool   `json:"fresh"`
	// PublishedAt can be a date or a timestamp. Preserve its original precision.
	PublishedAt  *string         `json:"publishedAt,omitempty"`
	SourceNotice json.RawMessage `json:"sourceNotice,omitempty"`
}

Coverage preserves exact source versions and freshness. The complete original object, including additional publisher notices, remains in Response.RawJSON.

type Evidence 

type Evidence struct {
	Format         string            `json:"format"`
	Result         ScreeningResult   `json:"result"`
	Retention      string            `json:"retention"`
	ExpiresAt      *string           `json:"expires_at"`
	Subject        *Subject          `json:"subject"`
	Reference      *string           `json:"reference"`
	Request        *ScreeningRequest `json:"request"`
	RetainedInputs bool              `json:"retainedInputs"`
	ReplayLimit    *string           `json:"replayLimit"`
}

Evidence is the raw evidence document's typed view. Nullable fields remain nil. The document is not a signed attestation or compliance certification.

type EvidenceResponse 

type EvidenceResponse struct {
	Evidence  Evidence
	RequestID string
	RawJSON   json.RawMessage
}

EvidenceResponse keeps the direct evidence document separate from ordinary API data envelopes. RawJSON contains the unchanged downloaded document.

type Identifier 

type Identifier struct {
	Type   string `json:"type"`
	Value  string `json:"value"`
	Issuer string `json:"issuer,omitempty"`
}

Identifier is an original identifier and its scheme, with an optional issuer.

type Match 

type Match struct {
	Score      float64         `json:"score"`
	Record     json.RawMessage `json:"record"`
	Evidence   json.RawMessage `json:"evidence"`
	Conflicts  []string        `json:"conflicts"`
	Assessment json.RawMessage `json:"assessment,omitempty"`
}

Match contains a candidate and its supporting evidence. Raw nested objects preserve varying publisher fields without inventing a common record schema.

type Options 

type Options struct {
	BaseURL          string
	HTTPClient       *http.Client
	Timeout          time.Duration
	MaxResponseBytes int64
}

Options customizes transport limits. BaseURL defaults to the canonical hosted API. Plain HTTP is allowed only for literal loopback hosts or localhost. HTTPClient is copied; its redirect policy is always replaced with refusal.

type PolicyReference 

type PolicyReference struct {
	ID      string `json:"id"`
	Version int64  `json:"version"`
}

PolicyReference identifies one exact approved organization policy version.

type Response 

type Response[T any] struct {
	Data      T
	RequestID string
	RawJSON   json.RawMessage
}

Response contains parsed data, a correlation ID when supplied, and the exact original JSON response bytes. Keep RawJSON in access-controlled storage.

type RetainedResult 

type RetainedResult struct {
	ScreeningResult
	Subject   *Subject `json:"subject"`
	Reference *string  `json:"reference"`
}

RetainedResult adds retained inputs. Subject and Reference are nil when absent under the retention policy. They are not reconstructed by the client.

type ScreeningRequest 

type ScreeningRequest struct {
	Subject        Subject          `json:"subject"`
	CounterpartyID string           `json:"counterpartyId,omitempty"`
	Policy         *PolicyReference `json:"policy,omitempty"`
	Reference      string           `json:"reference,omitempty"`
	Sources        []string         `json:"sources,omitempty"`
	Package        string           `json:"package,omitempty"`
	Retention      string           `json:"retention,omitempty"`
}

ScreeningRequest selects exactly one of Package or Sources. Policies and organization controls may require standard retention or restrict coverage.

type ScreeningResult 

type ScreeningResult struct {
	ID             string          `json:"id"`
	Environment    string          `json:"environment"`
	Status         string          `json:"status"`
	CreatedAt      string          `json:"createdAt"`
	Matches        []Match         `json:"matches"`
	Coverage       []Coverage      `json:"coverage"`
	Versions       Versions        `json:"versions"`
	Disclaimer     string          `json:"disclaimer"`
	PolicySnapshot json.RawMessage `json:"policySnapshot,omitempty"`
	Matching       json.RawMessage `json:"matching,omitempty"`
}

ScreeningResult is the original screening outcome. Status is potential_match or no_match. Neither status is an approval decision.

type Source 

type Source struct {
	ID             string          `json:"id"`
	Name           string          `json:"name"`
	Authority      string          `json:"authority"`
	Availability   string          `json:"availability"`
	Capabilities   []string        `json:"capabilities"`
	RightsStatus   string          `json:"rightsStatus"`
	Category       string          `json:"category"`
	Jurisdiction   string          `json:"jurisdiction,omitempty"`
	Homepage       string          `json:"homepage,omitempty"`
	DisabledReason string          `json:"disabledReason,omitempty"`
	Fresh          *bool           `json:"fresh,omitempty"`
	Qualification  json.RawMessage `json:"qualification,omitempty"`
	CurrentVersion json.RawMessage `json:"currentVersion,omitempty"`
	LastImport     json.RawMessage `json:"lastImport,omitempty"`
}

Source describes current availability and supported entity types. Presence in the catalog alone does not mean a source can be used for a screening.

type Subject 

type Subject struct {
	Name        string       `json:"name"`
	EntityType  string       `json:"entityType,omitempty"`
	Identifiers []Identifier `json:"identifiers,omitempty"`
	BirthDate   string       `json:"birthDate,omitempty"`
	Country     string       `json:"country,omitempty"`
}

Subject contains known identity information. BirthDate preserves the supplied precision: YYYY, YYYY-MM, or YYYY-MM-DD. Omit unknown optional fields.

type Versions 

type Versions struct {
	Dataset        string `json:"dataset"`
	MatchingEngine string `json:"matchingEngine"`
	Policy         string `json:"policy"`
	Package        string `json:"package,omitempty"`
}

Versions identifies the data and matching rules used for a result.

Source Files

View all Source files

Directories

Path Synopsis
examples
screen command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.