Getting Started

Get your API key

Contact SANNOS to obtain your Partner API key. Keep this key secure — it provides access to your Partner account.

The Partner API uses a two-tier key model. Your Partner Key onboards clients; the Company Key (returned by onboarding) is used for all document operations. See Authentication.

Onboard your partner account

Onboarding creates your company and its default organization unit, of the built-in business_entity type, using your Partner’s configured framework. Authenticate with your Partner Key; the response returns the Company Key used for all document operations.

curl -X POST "https://sandbox-api.sannos.ai/v2/onboard" \
  -H "X-API-Key: $EVE_PARTNER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme Corporation","legalName":"Acme Corporation Inc."}'

const res = await fetch("https://sandbox-api.sannos.ai/v2/onboard", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.EVE_PARTNER_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "Acme Corporation", legalName: "Acme Corporation Inc." }),
});
const data = await res.json();

import os, requests

res = requests.post(
    "https://sandbox-api.sannos.ai/v2/onboard",
    headers={"X-API-Key": os.environ["EVE_PARTNER_KEY"], "Content-Type": "application/json"},
    json={"name": "Acme Corporation", "legalName": "Acme Corporation Inc."},
)
data = res.json()

Response:

{
  "companyId": "01ABC...",
  "organizationUnitId": "01XYZ...",
  "message": "Company onboarded successfully.",
  "companyApiKey": "eve_ck_..."
}

Save these IDs — you’ll need companyId and organizationUnitId (the company’s default business_entity unit) for future operations, and the companyApiKey for every document call. Pass organizationUnitId when you submit documents.

(Recommended) Update your company details

After onboarding, update your company with accurate business information using your Company Key:

curl -X PATCH "https://sandbox-api.sannos.ai/v2/companies/$COMPANY_ID" \
  -H "X-API-Key: $EVE_COMPANY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corporation",
    "legalName": "Acme Corporation Inc.",
    "country": "US",
    "city": "San Francisco",
    "address": "123 Main Street",
    "postalCode": "94102",
    "phone": "+1-555-123-4567",
    "taxId": "12-3456789"
  }'

const res = await fetch(`https://sandbox-api.sannos.ai/v2/companies/${companyId}`, {
  method: "PATCH",
  headers: {
    "X-API-Key": process.env.EVE_COMPANY_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Acme Corporation",
    legalName: "Acme Corporation Inc.",
    country: "US",
    city: "San Francisco",
    address: "123 Main Street",
    postalCode: "94102",
    phone: "+1-555-123-4567",
    taxId: "12-3456789",
  }),
});

import os, requests

res = requests.patch(
    f"https://sandbox-api.sannos.ai/v2/companies/{company_id}",
    headers={"X-API-Key": os.environ["EVE_COMPANY_KEY"], "Content-Type": "application/json"},
    json={
        "name": "Acme Corporation",
        "legalName": "Acme Corporation Inc.",
        "country": "US",
        "city": "San Francisco",
        "address": "123 Main Street",
        "postalCode": "94102",
        "phone": "+1-555-123-4567",
        "taxId": "12-3456789",
    },
)

(Optional) Create additional organization units

Create separate organization units for the parts of the client’s organization that need their own compliance reviews. Every unit has a type: use the built-in business_entity type, or a type code the company defined (list them with GET /v2/organization-unit-types):

curl -X POST "https://sandbox-api.sannos.ai/v2/organization-units" \
  -H "X-API-Key: $EVE_COMPANY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"business_entity","name":"EMEA Operations"}'

const res = await fetch("https://sandbox-api.sannos.ai/v2/organization-units", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.EVE_COMPANY_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ type: "business_entity", name: "EMEA Operations" }),
});

import os, requests

res = requests.post(
    "https://sandbox-api.sannos.ai/v2/organization-units",
    headers={"X-API-Key": os.environ["EVE_COMPANY_KEY"], "Content-Type": "application/json"},
    json={"type": "business_entity", "name": "EMEA Operations"},
)

Response:

{
  "id": "01DEF...",
  "name": "EMEA Operations",
  "type": "business_entity",
  "companyId": "01ABC..."
}

Pass the returned id as organizationUnitId when you submit documents. See Organization Units for listing, reading and updating units, and Migrating to v2 if you still call the v1 API.

Discover compliance frameworks and controls

Before submitting documents, discover which frameworks and controls are available:

curl "https://sandbox-api.sannos.ai/v2/compliance-frameworks" \
  -H "X-API-Key: $EVE_COMPANY_KEY"

const res = await fetch("https://sandbox-api.sannos.ai/v2/compliance-frameworks", {
  headers: { "X-API-Key": process.env.EVE_COMPANY_KEY },
});
const data = await res.json();

import os, requests

res = requests.get(
    "https://sandbox-api.sannos.ai/v2/compliance-frameworks",
    headers={"X-API-Key": os.environ["EVE_COMPANY_KEY"]},
)
data = res.json()

Response:

{
  "frameworks": [
    {
      "id": "01FRM...",
      "name": "ISO 27001:2022",
      "frameworkGroup": "ISO 27001",
      "controls": [
        { "id": "01CTL...", "name": "Access Control", "version": "1.0" }
      ]
    }
  ]
}

Save the frameworkId and controlId — you may need them when submitting documents (optional if your partner has only one whitelisted framework/control).

Submit documents

Document submission uses multipart/form-data (file upload), so these examples use curl -F.Option A: Create new compliance review

curl

curl -X POST "https://sandbox-api.sannos.ai/v2/documents/submit" \
  -H "X-API-Key: $EVE_COMPANY_KEY" \
  -F "[email protected]" \
  -F "organizationUnitId=01BE..." \
  -F "controlId=01CTL..." \
  -F 'selectedControlClusterIds=["01CLU...","01CLU..."]' \
  -F 'selectedControlItemIds=["01CTI..."]' \
  -F "auditLanguageId=01LNG..."
# organizationUnitId  Required (Mode A) — organization unit of any type to create the review for
# controlId         Optional — uses partner's default control if omitted
# selectedControlClusterIds  Optional — JSON array of cluster ULIDs (includes all items in them)
# selectedControlItemIds     Optional — JSON array of specific control item ULIDs
# auditLanguageId   Optional — language for audit output

Option B: Add to existing review

curl

curl -X POST "https://sandbox-api.sannos.ai/v2/documents/submit" \
  -H "X-API-Key: $EVE_COMPANY_KEY" \
  -F "[email protected]" \
  -F "complianceReviewId=01REV..." \
  -F 'selectedControlClusterIds=["01CLU..."]' \
  -F 'selectedControlItemIds=["01CTI...","01CTI..."]' \
  -F "auditLanguageId=01LNG..."
# complianceReviewId  Required (Mode B) — appends to the existing review
# selectedControlClusterIds / selectedControlItemIds  Optional — narrow scope
# auditLanguageId   Optional

Provide either organizationUnitId OR complianceReviewId, not both.

Control item selection (both modes):

Both selectedControlClusterIds + selectedControlItemIds → union of cluster items and individual items
Clusters only → all non-obsolete items within those clusters
Items only → only those specific items
Neither → all non-obsolete items across the entire control (default)

Large files (> 50 MB)? Use the chunked upload flow instead — see Chunked Upload for Large Files.

Response:

{
  "documentId": "01DOC...",
  "complianceReviewId": "01REV...",
  "status": "Pending",
  "files": [
    { "fileName": "policy.pdf", "type": "parent" }
  ],
  "controlItemCount": 42,
  "message": "Documents submitted for processing."
}

Poll for results

# Check status (poll every 3-5 minutes)
curl "https://sandbox-api.sannos.ai/v2/documents/$DOCUMENT_ID/status" \
  -H "X-API-Key: $EVE_COMPANY_KEY"

# Get full results when status is "Processed"
curl "https://sandbox-api.sannos.ai/v2/documents/$DOCUMENT_ID/result" \
  -H "X-API-Key: $EVE_COMPANY_KEY"

const status = await fetch(
  `https://sandbox-api.sannos.ai/v2/documents/${documentId}/status`,
  { headers: { "X-API-Key": process.env.EVE_COMPANY_KEY } },
).then((r) => r.json());

// when status.status === "Processed"
const result = await fetch(
  `https://sandbox-api.sannos.ai/v2/documents/${documentId}/result`,
  { headers: { "X-API-Key": process.env.EVE_COMPANY_KEY } },
).then((r) => r.json());

import os, requests

key = {"X-API-Key": os.environ["EVE_COMPANY_KEY"]}
base = f"https://sandbox-api.sannos.ai/v2/documents/{document_id}"

status = requests.get(f"{base}/status", headers=key).json()
# when status["status"] == "Processed"
result = requests.get(f"{base}/result", headers=key).json()

The /result endpoint accepts optional query parameters:

complianceLevel — filter by score band: Not Compliant, Partially Compliant, Mostly Compliant, Fully Compliant.
fields — return only specific fields (comma-separated dot-notation).

Example filtered result call:

curl

curl "https://sandbox-api.sannos.ai/v2/documents/$DOCUMENT_ID/result?complianceLevel=Not%20Compliant&fields=documentId,complianceItems.controlItemName,complianceItems.result.score" \
  -H "X-API-Key: $EVE_COMPANY_KEY"

Introduction

Guides

Reference