@intellicompli/sdk
v0.3.2
Published
Official SDK for IntelliCompli AML/CTF Compliance API
Readme
IntelliCompli SDK
TypeScript/JavaScript SDK for the IntelliCompli AML/CTF compliance API.
Installation
npm install @intellicompli/sdk
# or
pnpm add @intellicompli/sdk
# or
yarn add @intellicompli/sdkQuick start
import { IntelliCompli } from '@intellicompli/sdk';
const client = new IntelliCompli({
apiKey: 'sk_live_...',
});
// List customers
const customers = await client.customers.list();
// Create a customer
const customer = await client.customers.create({
email: '[email protected]',
firstName: 'John',
lastName: 'Doe',
});
// Screen against sanctions
const result = await client.sanctions.screen({
firstName: 'John',
lastName: 'Doe',
dateOfBirth: '1990-01-01',
});Base URL
The only supported override is baseUrl. By default the client talks to https://api.intellicompli.com.au/v1; point it elsewhere (a local API server, a proxy) by passing baseUrl explicitly:
const client = new IntelliCompli({
apiKey: 'sk_test_...',
baseUrl: 'http://localhost:3001/api/v1',
});There is no separate staging host — a test-mode key (sk_test_... / pk_test_...) talks to the same production API and marks requests as test mode.
A trailing slash on baseUrl (.../v1/) is tolerated, as is a base with an extra path segment (e.g. http://localhost:3001/api/v1) — every request joins the base and the resource path itself rather than resolving the path as an absolute URL, so the base's own path segment is never dropped.
Available resources
Each resource is a property on the client (client.<resource>.<method>()). Resource and method names below match the SDK exactly.
| Resource | Methods |
|---|---|
| customers | create, createBatch, updateBatch, retrieve, update, delete, list, getComplianceStatus, upsert, linkOwnershipEntity, rederiveOwners, reviewEddRecommendation, unlinkOwnershipEntity, getRiskExplanation, getRiskHistory, import, importTemplate, createFromVerification, enrichFromVerification, downloadKycDocument |
| transactions | create, createBatch, retrieve, update, delete, list, importFile, downloadTemplate, getReview, submitReview, getRiskExplanation |
| sanctions | screen, batchScreen, history |
| pep | screen, batchScreen, history |
| risk | assess |
| kyc | startVerification, getStatus, uploadDocument, listDocuments, retrieveDocument, deleteDocument |
| identityVerifications | retrieve, list, review |
| kyb | create, retrieve, list, update, review, uploadDocument, listDocuments |
| business | register |
| beneficialOwners | create, retrieve, update, delete, list |
| clientGroups | list, create, retrieve, update, delete, addMember, removeMember, listTransactions, reviewExtraction, createDocumentUploadUrl, completeDocumentUpload, uploadDocument, listDocuments, deleteDocument, downloadDocument, listOwnerLinkSuggestions, addOwnerLink, removeOwnerLink, listSuggestions, approveSuggestion, dismissSuggestion, listSuggestionDismissals, clearSuggestionDismissal |
| alerts | create, retrieve, update, list, resolve, dismiss, acknowledge |
| alertRules | list, create |
| cases (deprecated) | create, retrieve, update, delete, list — cases are no longer shown in the dashboard; use alerts and edd |
| edd | list, retrieve, create, requestInformation, escalate, complete, updateStatus, update, delete |
| reviews | list, create, retrieve, update, createRemediationItem, updateRemediationItem |
| ocdd | listSchedules, updateSchedule |
| reports | listCompliance, createCompliance, getCompliance, updateCompliance, generateTTR, generateSMR, listSMR, generateIFTI, history, retrieveSmr, updateSmr, retrieveIfti |
| programs | list, create, retrieve, update, changeStatus, listVersions, retrieveVersion, delete, promote, exportPdf |
| programTemplates | list, retrieve |
| analytics | getOverview, getRiskMonitoring, getShadowScores |
| auditLogs | list |
| webhooks | create, retrieve, update, delete, list, listEvents |
| training | create, list, update, delete, uploadDocument, listDocuments, downloadDocument, deleteDocument |
| trainingModules | list, retrieve |
| trainingProgress | list, assign, update, submitQuiz, summary, sendReminder |
| staff | list, create, retrieve, update, delete |
| typologies | list, coverage |
| designatedServiceTypes | list |
| controls | list |
| compliance | calendar |
| export | status, all, byType |
| config | getRegions |
| health | check |
| address | autocomplete, details |
| abnLookup | lookupByAbn, lookupByAcn |
| apiKeys | rotate |
| tenant | getSettings, updateSettings, getOnboardingStatus, getRiskConfig, updateRiskConfig, getStripeUsage, getReadiness, getAustracConfig, updateAustracConfig, getRetentionPolicy, updateRetentionPolicy, getRiskConfigPresets, getRiskConfigHistory, getTransitionTimeline |
| stripe | getUsage |
| integrations | per-provider sub-resources (see below) |
| partner | account, practices, usage, invoices, webhooks, forPractice() — partner keys only, see below |
| tenants | list, create, retrieve, update, delete — platform-operator only |
| cron | runOcdd, checkDeadlines — platform-operator only |
Some methods worth calling out:
customers.getComplianceStatus(id)— the customer's compliance-status snapshot, including any live EDD-recommendation action item (seereviewEddRecommendation).transactions.getReview/submitReview— review/approve/escalate a flagged transaction;getRiskExplanation(on bothcustomersandtransactions) returns a plain-English narrative for the current risk score.clientGroupsgained document upload/list/delete/download (the small-file path — reusecreateDocumentUploadUrl/completeDocumentUploadfor large files), owner-link suggestions/linking, and the group-suggestion review surface (listSuggestions/approveSuggestion/dismissSuggestion/listSuggestionDismissals/clearSuggestionDismissal).reports.history/retrieveSmr/updateSmr/retrieveIftiround out the reporting surface alongside the existinggenerateTTR/generateSMR/generateIFTI.SMRReportInput'sgroundsForSuspicionfield was renamed tosuspicionGrounds, matching both the handler and the public spec — the old name never actually worked (everygenerateSMRcall 400'd).generateTTR/generateSMR/generateIFTI/retrieveSmr/retrieveIftiwithformat: 'xml'/'csv'now correctly return the raw file text instead of throwing (they were parsing an XML/CSV response body as JSON).alertRules.retrieve/update/delete,cases.createTask/updateTask/listTasks/deleteTask, andtraining.retrievewere removed — the routes they called never existed server-side, so every call 404'd.alerts.createandedd.create/.requestInformation/.escalate/.complete/.updateStatuscover the two multi-purpose endpoints POST /v1/alerts and POST /v1/edd (theeddones are dispatched byaction, typed from the generated spec union).edd.update()(PATCH /v1/edd/{id}) is a separate, similarly multi-action route — its return type was corrected from the full investigation to the small{success: true, ...}result the route actually sends.transactions.listsent unmapped camelCase filters (customerId,flaggedForReview,requiresTtr,requiresIfti,startingAfter) until a wire-level check caught it after the initial camelCase→snake_case sweep — every filter was silently ignored server-side. Fixed, along with the same bug ontraining.listDocumentsandtrainingProgress.list(startingAfter). The query-key test suite (__tests__/query-params.test.ts) now includes a structural check that scans every resource file forhttp.get/rawFetchcall sites and fails if any one hitting a query-param spec operation has no test case, specifically so a method can't go uncovered by not being remembered.customers.retrieve(id, { expand: ['compliance_status'] })inlines the compliance-status snapshot on the response.reports.listSMRnow sends the documentedactivity_type/customer_id(was sendingactivityType/customerId, which only worked because the route happens to dual-accept both).
integrations groups one sub-resource per connected provider (client.integrations.xero, .leap, .propertyme, .rex, .airwallex, .chainalysis, .frankieone, .monoova); OAuth providers expose connect, disconnect, status, sync, syncHistory, and Xero additionally exposes updateConfig. API-key providers (Airwallex, Chainalysis, FrankieOne, Monoova) expose connect(credentials) plus the same disconnect/status/sync/syncHistory set.
Partner keys
Practice-management software vendors integrate as partners rather than tenants. Partner credentials are prefixed pk_live_ / pk_test_ — distinct from a tenant's sk_live_ / sk_test_ key — and carry one of two scopes:
partner:manage— operates on your own billing account: provisioning practices, viewing usage, managing billing. No extra header needed.practice:act— acts on behalf of one linked practice per request. Every request must also carryX-Practice-Id: prc_..., the id of the practice you're acting for.
const partnerClient = new IntelliCompli({ apiKey: 'pk_live_...' });
// partner:manage — your own account
await partnerClient.partner.account();
await partnerClient.partner.practices.create({ /* ... */ });
await partnerClient.partner.usage.list();
await partnerClient.partner.invoices.list();
// practice:act — scope a request to one practice
const practice = partnerClient.partner.forPractice('prc_abc123');
await practice.customers.list();
await practice.transactions.create({ /* ... */ });forPractice() returns a scoped set of the same customers, transactions, kyc, identityVerifications, sanctions, pep, beneficialOwners, clientGroups, and webhooks resources used elsewhere in the SDK, with X-Practice-Id attached automatically. Only the routes the practice:act allowlist permits are reachable this way — alerts, cases, EDD, reports, audit logs, and billing are denied server-side regardless of scope, by design (this is the tipping-off boundary between a partner and their practices' compliance data). A practice can revoke practice:act access to their data at any time without affecting billing.
See https://www.intellicompli.com.au/guides/partner-api for the full request/response reference.
Errors
Every API error is a JSON body of the shape:
{
"error": {
"type": "invalid_request_error",
"code": "validation_error",
"message": "email is required",
"param": "email",
"requestId": "req_..."
}
}type is one of:
| Type | HTTP status | Meaning |
|---|---|---|
| authentication_error | 401 | Missing or invalid API key |
| authorization_error | 403 | Key valid, but not permitted for this operation |
| invalid_request_error | 400 | Malformed or invalid request (see param for the offending field) |
| rate_limit_error | 429 | Too many requests |
| not_found_error | 404 | Resource does not exist (or isn't visible to this key) |
| api_error | 500 | Unexpected server error — safe to retry, include requestId when reporting it |
The SDK throws an error carrying these same fields on any non-2xx response; catch and inspect error.type/error.code to branch on specific failure cases rather than parsing message.
Type generation
This SDK's request/response types are generated from the API's OpenAPI specification, so they stay in sync with the server by construction.
Workflow
- API routes register their Zod schemas in
apps/api/src/lib/openapi/schemas/. cd apps/api && pnpm generate-openapiregeneratesapps/api/openapi.jsonfrom those schemas.cd packages/sdk && pnpm generateregeneratessrc/generated/api-types.tsfrom the spec.- Resource classes in
src/resources/use the generated types.
Development
# Generate types from the OpenAPI spec
pnpm generate
# Build the SDK
pnpm build
# Watch mode for development
pnpm devGenerated vs. hand-written code
Generated (src/generated/):
api-types.ts— types produced from the OpenAPI specadapters.ts— utilities for extracting types from the generated typesindex.ts— re-exports
Hand-written:
src/resources/— the 43 resource classes and their methodssrc/types/— additional types not represented in the OpenAPI specsrc/client.ts,src/utils/— theIntelliCompliclient and HTTP layer
The generated types intentionally exclude /v1/tenant/* and /v1/public/* paths (see scripts/generate-types.ts); the tenant resource's types are hand-written in src/resources/tenant.ts instead.
Type utilities
import type { ExtractResponse, ExtractRequestBody, ExtractListItem } from '@intellicompli/sdk';
type CustomerResponse = ExtractResponse<'/v1/customers', 'get'>;
type CreateCustomerBody = ExtractRequestBody<'/v1/customers', 'post'>;
type Customer = ExtractListItem<'/v1/customers', 'get'>;Contributing
When adding a new endpoint:
- Register it in the appropriate schema file under
apps/api/src/lib/openapi/schemas/. - Regenerate the OpenAPI spec:
cd apps/api && pnpm generate-openapi. - Regenerate SDK types:
cd packages/sdk && pnpm generate. - Add or update the method on the matching resource class in
src/resources/. - Export any new types from
src/index.ts. - Run
pnpm buildto confirm everything compiles.
CI integration
pnpm check-sdk-typesFails if the generated types are out of sync with the OpenAPI spec — part of pnpm validate:all. Note it only covers the generated src/generated/ types; the hand-written interfaces in src/resources/*.ts are not checked automatically, so keep them in sync with their route's actual response shape by hand.
License
MIT
