PolicyShift API documentation

Use the PolicyShift v1 API to create policies, trigger compliance review, request redlines, produce audit evidence, and show organisation-level policy compliance scores inside partner products.

Base URL

https://app.policyshift.io

Version

/api/v1

Format

JSON

Authentication

API access uses Laravel Sanctum bearer tokens. Tokens are scoped to a PolicyShift user and company. Send the token in the Authorization header and include the matching company context as company_id. The API also accepts org_id and organisation_id as aliases.

bash

curl https://app.policyshift.io/api/v1/organisation/compliance-score?company_id=42 \
  -H "Authorization: Bearer ps_live_xxxxxxxxx" \
  -H "Accept: application/json"

Endpoints

Endpoints are grouped by resource. AI review operations can be asynchronous: submit the trigger, use returned status fields to update the UI, then request redlines or reports after review completes.

Policies

POST/api/v1/trigger/policy-uploaded

Create a policy from text or a PDF/DOCX upload, optionally queue AI review, and return the initial compliance assessment.

Request

json

{
  "company_id": 42,
  "title": "Remote Working Policy",
  "content": "Employees may work remotely where...",
  "country": "United Kingdom",
  "jurisdiction": "England and Wales",
  "policy_type": "hr",
  "category": "hr",
  "tag": "mandatory",
  "run_ai_review": true
}

Response

json

{
  "event": "policy.uploaded",
  "status": "At Risk",
  "score": 70,
  "policy": {
    "id": 133,
    "company_id": 42,
    "status": {
      "value": "ai_review",
      "label": "AI Review"
    },
    "category": "hr",
    "tag": "mandatory",
    "latest_version": {
      "version_number": 1,
      "title": "Remote Working Policy",
      "ai_review": {
        "error": null,
        "started_at": "2026-04-28T10:12:00+00:00",
        "completed_at": null,
        "sources": []
      }
    }
  },
  "critical_issues": [],
  "gaps": [],
  "analysis": {
    "policyshift_status": "AI Review",
    "latest_version_number": 1,
    "ai_review_pending": true,
    "mapped_legislation_count": 0
  },
  "generated_at": "2026-04-28T10:12:01+00:00"
}

POST/api/v1/policies/{policy}/trigger/updated

Create a new policy version after partner-side edits and optionally requeue AI review.

Request

json

{
  "company_id": 42,
  "title": "Remote Working Policy",
  "content": "Updated policy text...",
  "summary": "Clarifies approval rules for overseas remote work.",
  "category": "hr",
  "tag": "mandatory",
  "run_ai_review": true
}

Response

json

{
  "event": "policy.updated",
  "status": "At Risk",
  "score": 70,
  "policy": {
    "id": 133,
    "company_id": 42,
    "latest_version": {
      "version_number": 2,
      "title": "Remote Working Policy"
    }
  },
  "analysis": {
    "previous_status": "Up To Date",
    "previous_version_number": 1,
    "current_version_number": 2,
    "ai_review": {
      "queued": true
    }
  },
  "generated_at": "2026-04-28T10:20:18+00:00"
}

POST/api/v1/policies/{policy}/trigger/distributed

Check whether a specific policy version is safe to distribute for acknowledgement.

Request

json

{
  "company_id": 42,
  "version": 2,
  "distribution_reference": "qualee-campaign-8841",
  "recipient_count": 118
}

Response

json

{
  "event": "policy.distributed",
  "distribution_status": "Warning",
  "reasoning": [
    "AI review is still running for this policy."
  ],
  "policy": {
    "id": 133,
    "company_id": 42
  },
  "version": {
    "id": 205,
    "policy_id": 133,
    "version_number": 2,
    "status": {
      "value": "accepted",
      "label": "Accepted"
    }
  },
  "acknowledgements": {
    "total": 118,
    "acknowledged": 0,
    "pending": 118,
    "rate": 0
  },
  "last_checked_at": "2026-04-28T10:22:05+00:00"
}

POST/api/v1/policies/{policy}/redline

Return actionable redline suggestions when available, or queue review when requested.

Request

json

{
  "company_id": 42,
  "jurisdiction": "England and Wales",
  "run_ai_review": true
}

Response

json

{
  "event": "policy.redline_requested",
  "policy": {
    "id": 133,
    "company_id": 42
  },
  "jurisdiction": "England and Wales",
  "generation_status": "available",
  "redlines": [
    {
      "id": 9001,
      "original_text": "Employees may work abroad without approval.",
      "proposed_text": "Employees must obtain written approval before working outside the UK.",
      "approved_by_viewer": false,
      "approved_by_admin": false
    }
  ],
  "replacement_clauses": [
    "Employees must obtain written approval before working outside the UK."
  ],
  "compliance_uplift": "1 actionable redline suggestion available.",
  "generated_at": "2026-04-28T10:24:36+00:00"
}

POST/api/v1/policies/{policy}/trigger/review-due

Requeue compliance review for a policy because a periodic review date or external trigger is due.

Request

json

{
  "company_id": 42,
  "review_reason": "Quarterly HR compliance check",
  "run_ai_review": true
}

Response

json

{
  "event": "policy.review_due",
  "status": "At Risk",
  "score": 70,
  "policy": {
    "id": 133,
    "company_id": 42,
    "status": {
      "value": "ai_review",
      "label": "AI Review"
    }
  },
  "analysis": {
    "review_reason": "Quarterly HR compliance check",
    "ai_review": {
      "queued": true
    }
  },
  "generated_at": "2026-04-28T10:28:10+00:00"
}

GET/api/v1/policies/{policy}/report?company_id=42&format=json&include_content=false

Fetch audit-ready policy evidence, versions, mapped sources, redlines, and acknowledgement data.

Response

json

{
  "report": {
    "format": "json",
    "generated_at": "2026-04-28T10:30:44+00:00",
    "pdf_available": false
  },
  "policy": {
    "id": 133,
    "company_id": 42,
    "latest_version": {
      "version_number": 2,
      "title": "Remote Working Policy"
    }
  },
  "compliance": {
    "status": "At Risk",
    "score": 70,
    "summary": "Remote working controls require review."
  },
  "audit_history": [
    {
      "version_number": 1,
      "status": "Accepted",
      "change_summary": "Initial import"
    }
  ],
  "version_history": [
    {
      "version_number": 2,
      "title": "Remote Working Policy",
      "content": null,
      "redline_count": 1
    }
  ],
  "legislation_sources": [],
  "acknowledgements": []
}

Legislation

POST/api/v1/legislation.changed

Notify PolicyShift of a legal or regulatory change and retrieve impacted policies.

Request

json

{
  "company_id": 42,
  "jurisdiction": "United Kingdom",
  "change_summary": "Employment rights changes affect flexible working requests.",
  "law_title": "Employment Rights Act 2025",
  "law_url": "https://example.gov.uk/employment-rights-act-2025",
  "effective_date": "2026-10-01",
  "severity": "high",
  "affected_policy_ids": [133, 144]
}

Response

json

{
  "event": "legislation.changed",
  "jurisdiction": "United Kingdom",
  "change_summary": "Employment rights changes affect flexible working requests.",
  "severity": "high",
  "affected_policies_count": 2,
  "affected_policies": [
    {
      "policy": {
        "id": 133,
        "company_id": 42,
        "category": "hr"
      },
      "impact_status": "requires_review",
      "severity": "high",
      "redline_available": true,
      "latest_version": 2
    }
  ],
  "generated_at": "2026-04-28T10:33:08+00:00"
}

Organisation

GET/api/v1/organisation/compliance-score?company_id=42&include_history=true

Return the organisation-level Unified Compliance Score, risk distribution, and priority actions.

Response

json

{
  "company": {
    "id": 42,
    "name": "Acme Ltd",
    "industry": "Technology"
  },
  "score": {
    "value": 82,
    "max": 100,
    "policy_currency": 76,
    "acknowledgement_rate": 91.4,
    "component_breakdown": {
      "policy_currency": 76,
      "acknowledgements": 8,
      "gap_penalties": -2
    }
  },
  "risk_distribution": {
    "draft": 1,
    "ai_review": 3,
    "outdated": 2,
    "human_review": 1,
    "up_to_date": 24
  },
  "priority_actions": [
    {
      "type": "high_risk_policies",
      "priority": "high",
      "message": "Review high-risk missing, outdated, or legally incorrect policies."
    }
  ],
  "history": [],
  "generated_at": "2026-04-28T10:35:52+00:00"
}

Error codes

HTTP	Code	Meaning
400	bad_request	Malformed JSON or unsupported input.
401	unauthenticated	Missing, expired, or invalid bearer token.
403	forbidden	Token owner cannot access the policy or company.
422	validation_failed	Required fields failed validation.
429	rate_limited	Too many requests in the current window.

json

{
  "error": {
    "code": "validation_failed",
    "message": "The given data was invalid.",
    "details": {
      "company_id": [
        "The company_id must match the authenticated API token owner."
      ]
    }
  }
}

Rate limits

Partner tokens are protected by application rate limiting. Treat AI review, redline generation, and legislation-change notifications as queueable operations: retry with backoff after a 429, avoid duplicate triggers for the same policy version, and poll reports or redlines only after status fields indicate review progress.