{"openapi":"3.1.0","info":{"title":"Certigence Public API","version":"1.0.0","description":"Read-only programmatic access to ESG company data, ratings, and search. Authenticate with a `cer_...` API key provisioned from your Certigence dashboard. API keys and outbound webhooks require a Professional or Enterprise subscription. Rate limits per key: 100 requests per 15 minutes on Professional, 1,000 on Enterprise; exceeding them returns HTTP 429. There are no write endpoints.","contact":{"name":"Certigence API","url":"https://certigence.eu/en/developers","email":"contact@certigence.eu"},"license":{"name":"Terms of Service","url":"https://certigence.eu/en/terms-of-service"}},"servers":[{"url":"https://app.certigence.eu","description":"Production"}],"components":{"securitySchemes":{"apiKeyBearer":{"type":"http","scheme":"bearer","bearerFormat":"cer_...","description":"Use `Authorization: Bearer cer_...` with the API key from your dashboard."},"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key","description":"Alternate auth: `X-API-Key: cer_...`"}},"schemas":{"Company":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"industry":{"type":"string","nullable":true},"country":{"type":"string","nullable":true},"website":{"type":"string","nullable":true},"scores":{"type":"object","properties":{"environmental":{"type":"number","nullable":true},"social":{"type":"number","nullable":true},"governance":{"type":"number","nullable":true},"overall":{"type":"number","nullable":true},"confidence":{"type":"number","nullable":true}}},"scoringMethod":{"type":"string","nullable":true},"signalCount":{"type":"integer","nullable":true},"summary":{"type":"string","nullable":true},"scoreUpdatedAt":{"type":"string","format":"date-time","nullable":true}}},"Pagination":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"docs":{"type":"string","nullable":true}}}}},"security":[{"apiKeyBearer":[]},{"apiKeyHeader":[]}],"paths":{"/api/v1/companies":{"get":{"summary":"List companies with scores","tags":["Companies"],"parameters":[{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"industry","in":"query","schema":{"type":"string"}},{"name":"country","in":"query","schema":{"type":"string"}},{"name":"search","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Paginated list of companies","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Company"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"description":"API key missing or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/companies/{id}":{"get":{"summary":"Get a single company","tags":["Companies"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Company details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Company"}}}},"404":{"description":"Company not found"}}}},"/api/v1/companies/{id}/score":{"get":{"summary":"Get the current ESG score for a company","tags":["Companies"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Latest ESG score."}}}},"/api/v1/companies/{id}/controversies":{"get":{"summary":"Structured ESG controversies","description":"Curated controversy records (incidents, fines, lawsuits) for the company. Filter by severity, category, status, or since-date. Use for watchlist workflows and due diligence.","tags":["Companies"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}},{"name":"severity","in":"query","schema":{"type":"string"},"description":"low | moderate | severe | catastrophic"},{"name":"category","in":"query","schema":{"type":"string","enum":["environmental","social","governance"]}},{"name":"status","in":"query","schema":{"type":"string"},"description":"alleged | confirmed | resolved | dismissed (etc. — see controversy_status enum)"},{"name":"since","in":"query","schema":{"type":"string","format":"date"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Controversies, newest first"}}}},"/api/v1/companies/{id}/score/history":{"get":{"summary":"Historical ESG score snapshots","description":"Daily snapshots of the company's ESG score, populated by a nightly cron job. Use for YoY / trend analysis.","tags":["Companies"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":3650,"default":365}},{"name":"from","in":"query","schema":{"type":"string","format":"date"},"description":"ISO date, inclusive"},{"name":"to","in":"query","schema":{"type":"string","format":"date"},"description":"ISO date, inclusive"},{"name":"interval","in":"query","schema":{"type":"string","enum":["daily","monthly"],"default":"daily"},"description":"`monthly` returns one row per month (latest snapshot within the month)."}],"responses":{"200":{"description":"Historical scores, newest first","content":{"application/json":{"schema":{"type":"object","properties":{"companyId":{"type":"integer"},"interval":{"type":"string"},"count":{"type":"integer"},"data":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"scores":{"type":"object","properties":{"environmental":{"type":"number","nullable":true},"social":{"type":"number","nullable":true},"governance":{"type":"number","nullable":true},"overall":{"type":"number","nullable":true}}},"signalCount":{"type":"integer","nullable":true}}}}}}}}}}}},"/api/v1/rankings/{sector}":{"get":{"summary":"Sector-level ranking for portfolio screening","description":"Returns companies in the given industry (case-insensitive), sorted by overall ESG score descending. Slug form accepted (e.g. `consumer-discretionary` → `Consumer Discretionary`).","tags":["Rankings"],"parameters":[{"name":"sector","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}],"responses":{"200":{"description":"Ranked companies","content":{"application/json":{"schema":{"type":"object","properties":{"sector":{"type":"string"},"count":{"type":"integer"},"data":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/Company"},{"type":"object","properties":{"rank":{"type":"integer"}}}]}}}}}}}}}},"/api/v1/search":{"get":{"summary":"Search companies by name","tags":["Companies"],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":10}}],"responses":{"200":{"description":"Search hits"},"400":{"description":"Query too short"}}}}},"x-webhooks":{"description":"Outbound webhooks are signed with HMAC-SHA256 using the secret shown once at endpoint creation. The signature is delivered in the `X-Webhook-Signature` header. Verify by computing `hmac_sha256(secret, raw_body)` and comparing in constant time. Event types: company.created, company.updated, company.score_changed, alert.triggered, goal.achieved, goal.at_risk, deadline.upcoming, deadline.overdue, task.completed, action_plan.completed, verification.completed, payment.succeeded, payment.failed."}}