REST API, webhooks and integrating iComply with your tech stack — to collect evidence automatically rather than requesting it by email.
Most of the compliance evidence already exists within your systems — in the identity directory, the vulnerability management system, the ticketing system and HR. The API is designed to automatically feed this evidence into the controls, complete with date and source, rather than someone having to take screenshots every quarter.
Access to the API and webhooks is available on the Enterprise plan and as an add-on on the Professional plans. See Pricing.
The API is a REST API over HTTPS and uses service tokens for authentication. Create the token in Administração → API assigning it the minimum required scope (domains and operations). Tokens may have an expiry date and can be revoked at any time.
curl https://api.icomply.pt/v1/controls \
-H "Authorization: Bearer $ICOMPLY_TOKEN" \
-H "Accept: application/json"Never place tokens in version-controlled source code or in the browser. Use your infrastructure’s secret vault. Every use of the token is recorded in the audit log.
/v1/controls — to review and update controls, statuses and responsible persons./v1/requirements — framework requirements and their corresponding mappings./v1/evidence — load, list and replace records./v1/risks — risk registration, scoring and linking to controls./v1/tasks — tasks, deadlines and people responsible./v1/findings — audit findings and CAPA actions./v1/audits — audits, scope and results./v1/vendors — suppliers, assessments and criticality./v1/reports — generation of status reports by framework.The most valuable use case. Upload the file and link it to one or more controls; the platform handles version control and propagation to all mapped requirements.
POST /v1/evidence
Authorization: Bearer $ICOMPLY_TOKEN
Content-Type: multipart/form-data
[email protected]
control_ids[]=ctrl_mfa_enforced
control_ids[]=ctrl_access_review
valid_from=2026-07-01
valid_until=2026-10-01
source=okta-automation
The source field is important: it indicates that the evidence was generated automatically and by which system — information that auditors value, as it eliminates manual intervention from the process.
Instead of querying the API periodically, subscribe to events. Configure endpoints in Administração → Webhooks.
control.status_changed — a control has changed state.evidence.expiring — evidence that is nearing its expiry date.evidence.expired — The evidence has expired.task.assigned / task.overdue — tasks.finding.created — new audit finding.capa.due — CAPA share with a short-term expiry date.risk.escalated — risk has risen above the defined tolerance level.Each delivery is signed using HMAC-SHA256 in the X-iComply-Signature header. Always validate the signature before processing. Failed deliveries are retried using exponential backoff.
Connect your identity provider (Entra ID, Okta, Google Workspace) to provide access audit logs and MFA evidence. Combined with SCIM, this eliminates the most common source of non-compliance: active accounts belonging to former employees.
Submit findings from your vulnerability management tool to the relevant controls, along with a remediation SLA. The evidence for the control is now its actual status, not a declaration.
Integrate Jira, ServiceNow or an equivalent system so that remediation and CAPA tasks are housed where technical teams already work, whilst keeping the status synchronised in iComply.
Track enrolment, completion and exit from compulsory training — providing direct evidence for People Governance and safety awareness checks.
Send notifications about at-risk checks, expired evidence and new findings to Slack or Teams via a webhook.
Export compliance and risk reports to Power BI, Looker or Tableau for executive dashboards alongside other business metrics.
X-RateLimit-Remaining and X-RateLimit-Reset headers indicate the status. Handle 429 with backoff. limit and cursor; follow next_cursor until it reaches a null value.Idempotency-Key in write operations to avoid duplicates on retries./v1/). Incompatible changes only occur in new versions, with a pre-announced overlap period. Error responses follow a consistent format, comprising a machine-readable code and a message for humans:
{
"error": {
"code": "control_not_found",
"message": "No control matches id 'ctrl_xyz'.",
"request_id": "req_01J9F2K7Q"
}
}Always enter request_id — it really speeds up the support process when you need to investigate a specific case with our team.
source and expiry dates in the automated records — otherwise, half the value will be lost during the audit.We design the integrations in collaboration with your technical team and provide the test credentials.