Getting Started - SANNOS Partner API

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 default business entity 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://partner-api.sannos.ai/v1/onboard" \
  -H "X-API-Key: $EVE_PARTNER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme Corporation","legalName":"Acme Corporation Inc."}'

Response:

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

Save these IDs — you’ll need companyId and businessEntityId for future operations, and the companyApiKey for every document call.

(Recommended) Update your company details

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

curl -X PATCH "https://partner-api.sannos.ai/v1/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"
  }'

(Optional) Create additional business entities

Create separate business entities for different organizational units:

curl -X POST "https://partner-api.sannos.ai/v1/business-entities" \
  -H "X-API-Key: $EVE_COMPANY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"EMEA Operations"}'

Response:

{
  "id": "01BE...",
  "name": "EMEA Operations"
}

Discover compliance frameworks and controls

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

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

Response:

{
  "frameworks": [
    {
      "id": "01FRM...",
      "name": "ISO 27001:2022",
      "frameworkType": "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://partner-api.sannos.ai/v1/documents/submit" \
  -H "X-API-Key: $EVE_COMPANY_KEY" \
  -F "files[]=@policy.pdf" \
  -F "businessEntityId=01BE..." \
  -F "controlId=01CTL..." \
  -F 'selectedControlClusterIds=["01CLU...","01CLU..."]' \
  -F 'selectedControlItemIds=["01CTI..."]' \
  -F "auditLanguageId=01LNG..."
# businessEntityId  Required (Mode A) — business entity 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://partner-api.sannos.ai/v1/documents/submit" \
  -H "X-API-Key: $EVE_COMPANY_KEY" \
  -F "files[]=@additional-doc.pdf" \
  -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 businessEntityId 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://partner-api.sannos.ai/v1/documents/$DOCUMENT_ID/status" \
  -H "X-API-Key: $EVE_COMPANY_KEY"

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

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://partner-api.sannos.ai/v1/documents/$DOCUMENT_ID/result?complianceLevel=Not%20Compliant&fields=documentId,complianceItems.controlItemName,complianceItems.result.score" \
  -H "X-API-Key: $EVE_COMPANY_KEY"