API Reference

API Reference

The CertifiaWeb API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

You can use the CertifiaWeb API in test mode, which doesn't affect your live data or interact with production systems. The API key you use to authenticate the request determines whether the request is live mode or test mode.

The CertifiaWeb API doesn't support bulk updates. You can work on only one object per request.

Just getting started? Check out our development quickstart guide.

Base URL

https://api.certifiaweb.com/v1

Client Libraries

By default, the CertifiaWeb API Docs demonstrate using curl to interact with the API over HTTP. Select one of our official client libraries to see examples in code.

Authentication

The CertifiaWeb API uses API keys to authenticate requests. You can view and manage your API keys in the CertifiaWeb Dashboard.

Test mode secret keys have the prefix sk_test_ and live mode secret keys have the prefix sk_live_. Alternatively, you can use restricted API keys for granular permissions.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Authenticated Request

curl https://api.certifiaweb.com/v1/projects \
  -u sk_test_BQokikJ...2HlWgH4olfQ2:

Your API Key: A sample test API key is included in all the examples here, so you can test any example right away. Do not submit any personally identifiable information in requests made with this key.

Errors

CertifiaWeb uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Codes in the 5xx range indicate an error with CertifiaWeb's servers (these are rare).

Some 4xx errors that could be handled programmatically (e.g., a card is declined) include an error code that briefly explains the error reported.

HTTP Status Code Summary

Code Status Description
200 OK Everything worked as expected.
400 Bad Request The request was unacceptable, often due to missing a required parameter.
401 Unauthorized No valid API key provided.
403 Forbidden The API key doesn't have permissions to perform the request.
404 Not Found The requested resource doesn't exist.
429 Too Many Requests Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502, 503, 504 Server Errors Something went wrong on CertifiaWeb's end. (These are rare.)

Error Response Format

{
  "error": {
    "code": "invalid_request_error",
    "message": "The request is missing required parameters",
    "param": "project_name",
    "type": "invalid_request_error"
  }
}

Expanding Responses

Many objects allow you to request additional information as an expanded response by using the expand request parameter. This parameter is available on all API requests, and applies to the response of that request only.

In many cases, an object contains the ID of a related object in its response properties. For example, a Project might have an associated Category ID. You can expand these objects in line with the expand request parameter.

Basic Expansion

curl https://api.certifiaweb.com/v1/projects/proj_123 \
  -u sk_test_BQokikJ...2HlWgH4olfQ2: \
  -d "expand[]"=category \
  -G

Nested Expansion

You can expand nested relationships using dot notation:

curl https://api.certifiaweb.com/v1/projects/proj_123 \
  -u sk_test_BQokikJ...2HlWgH4olfQ2: \
  -d "expand[]"="certifications.standard" \
  -G

Multiple Expansions

Expand multiple fields at once:

curl https://api.certifiaweb.com/v1/projects/proj_123 \
  -u sk_test_BQokikJ...2HlWgH4olfQ2: \
  -d "expand[]"=category \
  -d "expand[]"=certifications \
  -d "expand[]"="certifications.standard" \
  -G

Expansion Depth

Expansions have a maximum depth of 4 levels. For example:

  • Level 1: category
  • Level 2: category.parent
  • Level 3: category.parent.standards
  • Level 4: category.parent.standards.requirements

Available Expansions

Resource Expandable Fields
Project category, certifications, documents, audits
Certification project, standard, auditor
Document project, uploaded_by
Audit project, auditor, findings

Pagination

Requests that return multiple items will be paginated to 20 items by default. You can specify further pages with the page parameter. You can also set a smaller page size using the limit parameter.

Pagination Parameters

Parameter Type Description
page integer Page number (default: 1)
limit integer Items per page (default: 20, max: 100)

Example Request

curl https://api.certifiaweb.com/v1/projects?limit=10&page=2 \
  -u sk_test_BQokikJ...2HlWgH4olfQ2:

Pagination Response

Paginated responses include pagination metadata:

{
  "data": [...],
  "pagination": {
    "total": 150,
    "per_page": 10,
    "current_page": 2,
    "last_page": 15,
    "from": 11,
    "to": 20
  }
}

Cursor-based Pagination (Advanced)

Some endpoints support cursor-based pagination for better performance with large datasets:

GET /v1/audits?cursor=eyJpZCI6IjEyMyJ9&limit=20

Best Practices

  • Use appropriate page sizes (10-50 items) for better performance
  • Always check last_page to know when to stop
  • Implement retry logic for pagination requests
  • Consider using cursor-based pagination for real-time data

Projects

Projects represent your compliance and certification initiatives. You can create, retrieve, update, and delete projects using the API. Projects are the central organizing unit for all compliance activities.

The Project object

Field Type Description
id string Unique identifier for the project
name string The name of the project (required)
description string A detailed description of the project
category_id string The ID of the category this project belongs to
status enum One of: draft, active, completed, archived
created_at timestamp Time at which the project was created
updated_at timestamp Time at which the project was last updated

List all projects

Returns a list of projects. The projects are returned sorted by creation date, with the most recently created projects appearing first.

GET /v1/projects

# Query Parameters
limit: integer (optional, default: 20, max: 100)
page: integer (optional, default: 1)
status: string (optional) - Filter by status
category_id: string (optional) - Filter by category
search: string (optional) - Search in name and description

Example Request

curl https://api.certifiaweb.com/v1/projects?limit=10&status=active \
  -u sk_test_BQokikJ...2HlWgH4olfQ2:

Example Response

{
  "data": [
    {
      "id": "proj_1234567890",
      "name": "ISO 27001 Compliance",
      "description": "Information security management system",
      "category_id": "cat_123",
      "status": "active",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-20T14:45:00Z"
    }
  ],
  "pagination": {
    "total": 50,
    "per_page": 10,
    "current_page": 1,
    "last_page": 5
  }
}

Retrieve a project

Retrieves the details of an existing project. You need only supply the unique project identifier that was returned upon project creation.

GET /v1/projects/{id}

# Path Parameters
id: string (required) - The ID of the project to retrieve

# Query Parameters
expand: array (optional) - Fields to expand (e.g., ["category", "certifications"])

Example Request

curl https://api.certifiaweb.com/v1/projects/proj_1234567890?expand[]=category \
  -u sk_test_BQokikJ...2HlWgH4olfQ2:

Example Response

{
  "id": "proj_1234567890",
  "name": "ISO 27001 Compliance",
  "description": "Information security management system",
  "category": {
    "id": "cat_123",
    "name": "Information Security"
  },
  "status": "active",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-20T14:45:00Z"
}

Create a project

Creates a new project object. All required parameters must be provided.

POST /v1/projects

# Request Body Parameters
name: string (required) - The name of the project
description: string (optional) - A detailed description
category_id: string (optional) - The category ID
status: string (optional, default: "draft") - Initial status
metadata: object (optional) - Additional metadata

Example Request

curl https://api.certifiaweb.com/v1/projects \
  -u sk_test_BQokikJ...2HlWgH4olfQ2: \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "name": "GDPR Compliance Project",
    "description": "General Data Protection Regulation compliance initiative",
    "category_id": "cat_456",
    "status": "draft",
    "metadata": {
      "department": "Legal",
      "priority": "high"
    }
  }'

Example Response

{
  "id": "proj_new123456",
  "name": "GDPR Compliance Project",
  "description": "General Data Protection Regulation compliance initiative",
  "category_id": "cat_456",
  "status": "draft",
  "metadata": {
    "department": "Legal",
    "priority": "high"
  },
  "created_at": "2024-01-25T09:15:00Z",
  "updated_at": "2024-01-25T09:15:00Z"
}

Update a project

Updates the specified project by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

PUT /v1/projects/{id}

# Path Parameters
id: string (required) - The ID of the project to update

# Request Body Parameters
name: string (optional) - The name of the project
description: string (optional) - A detailed description
category_id: string (optional) - The category ID
status: string (optional) - New status
metadata: object (optional) - Additional metadata

Example Request

curl https://api.certifiaweb.com/v1/projects/proj_1234567890 \
  -u sk_test_BQokikJ...2HlWgH4olfQ2: \
  -X PUT \
  -H "Content-Type: application/json" \
  -d '{
    "status": "active",
    "description": "Updated description"
  }'

Delete a project

Permanently deletes a project. This cannot be undone. All associated resources (certifications, documents, audits) will also be deleted.

DELETE /v1/projects/{id}

# Path Parameters
id: string (required) - The ID of the project to delete

Example Request

curl https://api.certifiaweb.com/v1/projects/proj_1234567890 \
  -u sk_test_BQokikJ...2HlWgH4olfQ2: \
  -X DELETE

Example Response

{
  "id": "proj_1234567890",
  "deleted": true
}

Archive a project

Archives a project instead of deleting it. Archived projects can be restored later.

POST /v1/projects/{id}/archive

Restore a project

Restores a previously archived project.

POST /v1/projects/{id}/restore

Compliance Status

Retrieve comprehensive compliance status information for your projects. Track compliance scores, requirements, and assessments across different standards.

The Compliance Status object

Field Type Description
project_id string The ID of the project
overall_score integer Overall compliance score (0-100)
status enum One of: non_compliant, partially_compliant, compliant, certified
requirements_total integer Total number of requirements
requirements_met integer Number of requirements met
last_assessment timestamp Date of last compliance assessment
next_assessment timestamp Date of next scheduled assessment

Get compliance status

Retrieves the current compliance status for a specific project.

GET /v1/compliance/status?project_id={id}

# Query Parameters
project_id: string (required) - The ID of the project
include_details: boolean (optional, default: false) - Include detailed breakdown

Example Request

curl https://api.certifiaweb.com/v1/compliance/status?project_id=proj_123&include_details=true \
  -u sk_test_BQokikJ...2HlWgH4olfQ2:

Example Response

{
  "project_id": "proj_123",
  "overall_score": 87,
  "status": "compliant",
  "requirements_total": 150,
  "requirements_met": 131,
  "requirements_pending": 15,
  "requirements_failed": 4,
  "last_assessment": "2024-01-20T10:00:00Z",
  "next_assessment": "2024-04-20T10:00:00Z",
  "standards": [
    {
      "standard_id": "std_iso27001",
      "name": "ISO 27001",
      "score": 92,
      "status": "compliant"
    }
  ]
}

Get compliance history

Retrieves historical compliance data for trend analysis.

GET /v1/compliance/history?project_id={id}

# Query Parameters
project_id: string (required)
start_date: date (optional)
end_date: date (optional)
limit: integer (optional, default: 30)

Trigger compliance assessment

Manually triggers a new compliance assessment for a project.

POST /v1/compliance/assess

# Request Body
{
  "project_id": "proj_123",
  "assessment_type": "full" | "partial",
  "standards": ["std_iso27001"] (optional)
}

Certifications

Manage certification requests, track certification status, and handle certification renewals. Certifications are awarded when projects meet all compliance requirements for a specific standard.

The Certification object

Field Type Description
id string Unique identifier for the certification
project_id string The project this certification belongs to
standard_id string The standard being certified against
status enum One of: pending, in_review, approved, rejected, expired, revoked
issued_date date Date when certification was issued
expiry_date date Date when certification expires
certificate_number string Official certificate number

List certifications

Returns a list of all certifications, optionally filtered by project, standard, or status.

GET /v1/certifications

# Query Parameters
project_id: string (optional) - Filter by project
standard_id: string (optional) - Filter by standard
status: string (optional) - Filter by status
limit: integer (optional, default: 20)
page: integer (optional, default: 1)

Example Request

curl https://api.certifiaweb.com/v1/certifications?project_id=proj_123&status=approved \
  -u sk_test_BQokikJ...2HlWgH4olfQ2:

Retrieve a certification

Gets detailed information about a specific certification.

GET /v1/certifications/{id}

Request a certification

Submits a certification request for a project against a specific standard.

POST /v1/certifications/request

# Request Body
{
  "project_id": "proj_123",
  "standard_id": "std_iso27001",
  "notes": "Optional notes for the certification request"
}

Example Request

curl https://api.certifiaweb.com/v1/certifications/request \
  -u sk_test_BQokikJ...2HlWgH4olfQ2: \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "proj_123",
    "standard_id": "std_iso27001",
    "notes": "Ready for certification review"
  }'

Renew a certification

Initiates the renewal process for an expiring certification.

POST /v1/certifications/{id}/renew

Download certificate

Downloads the official certificate document as a PDF.

GET /v1/certifications/{id}/download

Documents

Upload, manage, and retrieve compliance documents. Documents can be policies, procedures, evidence, audit reports, or any file related to compliance activities.

The Document object

Field Type Description
id string Unique identifier
project_id string Associated project
name string Document name
type enum One of: policy, procedure, evidence, report, other
file_size integer File size in bytes
mime_type string MIME type of the file
uploaded_at timestamp Upload timestamp

List documents

Returns a list of documents, optionally filtered by project or type.

GET /v1/documents

# Query Parameters
project_id: string (optional)
type: string (optional)
limit: integer (optional, default: 20)
page: integer (optional, default: 1)

Retrieve a document

Gets metadata about a specific document.

GET /v1/documents/{id}

Upload a document

Uploads a new document. Supports multipart/form-data for file uploads.

POST /v1/documents/upload

# Request Body (multipart/form-data)
file: file (required) - The file to upload
project_id: string (required)
name: string (required)
type: string (required)
description: string (optional)
tags: array (optional)

Example Request (cURL)

curl https://api.certifiaweb.com/v1/documents/upload \
  -u sk_test_BQokikJ...2HlWgH4olfQ2: \
  -F "file=@/path/to/document.pdf" \
  -F "project_id=proj_123" \
  -F "name=Security Policy v2.0" \
  -F "type=policy" \
  -F "description=Updated information security policy"

Download a document

Downloads the document file.

GET /v1/documents/{id}/download

Delete a document

Permanently deletes a document.

DELETE /v1/documents/{id}

Audits

Retrieve audit records, create new audits, and track audit history. Audits are comprehensive reviews of compliance status against standards.

The Audit object

Field Type Description
id string Unique identifier
project_id string Project being audited
audit_type enum One of: internal, external, self_assessment
status enum One of: scheduled, in_progress, completed, cancelled
start_date date Audit start date
end_date date Audit end date
auditor string Name of the auditor
findings_count integer Number of findings

List audits

Returns a list of audits, with optional filtering.

GET /v1/audits

# Query Parameters
project_id: string (optional)
status: string (optional)
audit_type: string (optional)
start_date: date (optional)
end_date: date (optional)
limit: integer (optional, default: 20)
page: integer (optional, default: 1)

Example Request

curl https://api.certifiaweb.com/v1/audits?project_id=proj_123&status=completed \
  -u sk_test_BQokikJ...2HlWgH4olfQ2:

Retrieve an audit

Gets detailed information about a specific audit.

GET /v1/audits/{id}

Create an audit

Creates a new audit record.

POST /v1/audits

# Request Body
{
  "project_id": "proj_123",
  "audit_type": "internal",
  "start_date": "2024-02-01",
  "end_date": "2024-02-05",
  "auditor": "John Doe",
  "scope": "ISO 27001 compliance review"
}

Get audit report

Retrieves the full audit report with findings and recommendations.

GET /v1/audits/{id}/report

Categories

Manage project categories. Categories help organize projects by compliance domain (e.g., Information Security, Data Protection, Quality Management).

List categories

GET /v1/categories

Retrieve a category

GET /v1/categories/{id}

Create a category

POST /v1/categories

# Request Body
{
  "name": "Information Security",
  "description": "Cybersecurity and information protection"
}

Standards

Retrieve information about compliance standards (ISO 27001, GDPR, SOC 2, etc.) and their requirements.

List standards

GET /v1/standards

# Query Parameters
category_id: string (optional)
search: string (optional)

Retrieve a standard

GET /v1/standards/{id}

Get standard requirements

GET /v1/standards/{id}/requirements

Users & Teams

Manage team members, assign roles, and control access to projects and resources.

List users

GET /v1/users

Invite user

POST /v1/users/invite

# Request Body
{
  "email": "user@example.com",
  "role": "viewer" | "editor" | "admin",
  "project_ids": ["proj_123"] (optional)
}

Assign user to project

POST /v1/projects/{project_id}/users

# Request Body
{
  "user_id": "user_123",
  "role": "viewer" | "editor" | "admin"
}

Notifications

Retrieve and manage notifications about important events in your account.

List notifications

GET /v1/notifications

# Query Parameters
unread_only: boolean (optional)
type: string (optional)
limit: integer (optional, default: 20)

Mark as read

POST /v1/notifications/{id}/read

Mark all as read

POST /v1/notifications/mark-all-read

Reports

Generate and retrieve compliance reports for projects, certifications, and audits.

Generate compliance report

POST /v1/reports/compliance

# Request Body
{
  "project_id": "proj_123",
  "report_type": "summary" | "detailed" | "executive",
  "format": "pdf" | "json" | "csv",
  "include_charts": true
}

Get report

GET /v1/reports/{id}

List reports

GET /v1/reports

Webhooks

Webhooks allow you to receive real-time notifications when events occur in your CertifiaWeb account. Configure webhook endpoints in your dashboard to receive events such as project updates, certification status changes, and audit completions.

The Webhook object

Field Type Description
id string Unique identifier
url string The URL where webhooks will be sent
events array List of events to subscribe to
active boolean Whether the webhook is active
secret string Secret for verifying webhook signatures

List webhooks

GET /v1/webhooks

Create a webhook

POST /v1/webhooks

# Request Body
{
  "url": "https://example.com/webhooks/certifiaweb",
  "events": [
    "project.updated",
    "certification.approved",
    "audit.completed"
  ],
  "description": "Production webhook"
}

Webhook events

Available webhook events include:

  • project.created - New project created
  • project.updated - Project updated
  • project.deleted - Project deleted
  • certification.requested - Certification requested
  • certification.approved - Certification approved
  • certification.rejected - Certification rejected
  • certification.expiring - Certification expiring soon
  • audit.scheduled - Audit scheduled
  • audit.completed - Audit completed
  • compliance.status_changed - Compliance status changed
  • document.uploaded - Document uploaded

Webhook signature verification

All webhook requests include a signature in the X-Webhook-Signature header. Verify the signature using HMAC-SHA256:

# Example verification (Node.js)
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

Update a webhook

PUT /v1/webhooks/{id}

Delete a webhook

DELETE /v1/webhooks/{id}

Test a webhook

POST /v1/webhooks/{id}/test

Rate Limits

API requests are rate-limited to prevent abuse and ensure fair usage across all users. Rate limits vary by subscription plan and are applied per API key.

Rate Limit Headers

Every API response includes rate limit information in the response headers:

Header Description
X-RateLimit-Limit Maximum number of requests allowed per window
X-RateLimit-Remaining Number of requests remaining in current window
X-RateLimit-Reset Unix timestamp when the rate limit window resets

Rate Limits by Plan

Plan Requests/Hour Requests/Day Burst Limit
Free 1,000 10,000 100
Professional 10,000 100,000 500
Enterprise Unlimited Unlimited Unlimited

Rate Limit Exceeded

When you exceed the rate limit, the API returns a 429 Too Many Requests status code. The response includes a Retry-After header indicating how many seconds to wait before retrying.

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1609459200
Retry-After: 3600

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please retry after 3600 seconds."
  }
}

Best Practices

  • Implement exponential backoff when receiving 429 responses
  • Cache responses when possible to reduce API calls
  • Monitor rate limit headers to avoid hitting limits
  • Use webhooks for real-time updates instead of polling
  • Batch operations when available to reduce request count

Example: Exponential Backoff

# Python example
import time
import requests

def make_request_with_backoff(url, max_retries=5):
    for attempt in range(max_retries):
        response = requests.get(url)

        if response.status_code == 429:
            retry_after = int(response.headers.get('Retry-After', 2 ** attempt))
            time.sleep(retry_after)
            continue

        return response

    raise Exception("Max retries exceeded")

Versioning

The CertifiaWeb API uses versioning to ensure backward compatibility. The current API version is v1. When we make backward-incompatible changes, we release a new version.

API Version in URL

The version is specified in the URL path. All requests should include the version:

https://api.certifiaweb.com/v1/projects

Version Header (Alternative)

You can also specify the version using the API-Version header:

curl https://api.certifiaweb.com/projects \
  -H "API-Version: 2024-01-15"

Version Lifecycle

  • Current: The latest stable version (v1)
  • Deprecated: Versions that will be retired within 6 months
  • Retired: Versions that are no longer supported

Migration Guide

When migrating to a new version, check the migration guide for breaking changes. We provide at least 6 months notice before deprecating a version.

Best Practice: Always specify the version explicitly in your API calls. This ensures your integration continues to work even when new versions are released.

Idempotency

Idempotency keys allow you to safely retry API requests without accidentally performing the same operation twice. This is especially useful for POST, PUT, and DELETE requests.

How It Works

Include an Idempotency-Key header in your request with a unique value. If you retry the request with the same key within 24 hours, the API will return the original response instead of processing the request again.

curl https://api.certifiaweb.com/v1/projects \
  -u sk_test_BQokikJ...2HlWgH4olfQ2: \
  -X POST \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{"name": "New Project"}'

Best Practices

  • Generate unique keys using UUIDs or similar unique identifiers
  • Use the same key for retries of the same request
  • Keys are valid for 24 hours after the first request
  • Each key can only be used once per endpoint and parameters

Idempotency-Key Header

Header Type Description
Idempotency-Key string Unique identifier for the request (max 255 characters)

Metadata

Many API resources support custom metadata, which allows you to store additional key-value pairs for your own use. Metadata is useful for storing custom tags, internal IDs, or any other custom data.

Using Metadata

Include a metadata object in create or update requests:

{
  "name": "My Project",
  "metadata": {
    "department": "Engineering",
    "cost_center": "CC-12345",
    "internal_id": "INT-789"
  }
}

Metadata Guidelines

  • Keys can be up to 40 characters long
  • Values can be up to 500 characters long
  • You can store up to 50 metadata keys per object
  • Metadata keys are case-sensitive
  • Metadata is returned in all API responses

Filtering by Metadata

You can filter resources by metadata using query parameters:

GET /v1/projects?metadata[department]=Engineering

Filtering & Sorting

Most list endpoints support filtering and sorting to help you find the exact data you need.

Filtering

Filter results by any field using query parameters:

# Filter by status
GET /v1/projects?status=active

# Filter by multiple values
GET /v1/projects?status=active&category_id=cat_123

# Date range filtering
GET /v1/audits?start_date=2024-01-01&end_date=2024-12-31

Search

Many endpoints support full-text search:

GET /v1/projects?search=GDPR

Sorting

Sort results using the sort parameter:

# Sort by name ascending
GET /v1/projects?sort=name

# Sort by created_at descending
GET /v1/projects?sort=-created_at

# Multiple sort fields
GET /v1/projects?sort=status,-created_at

Available Sort Fields

Common sort fields include:

  • created_at - Creation timestamp
  • updated_at - Last update timestamp
  • name - Name (alphabetical)
  • status - Status

Prefix with - for descending order.

Client Libraries

Official client libraries are available for popular programming languages. These libraries handle authentication, request formatting, and error handling automatically.

Available Libraries

Language Package Manager Installation
Node.js npm npm install @certifiaweb/api
Python pip pip install certifiaweb
PHP Composer composer require certifiaweb/api
Ruby gem gem install certifiaweb
Java Maven <dependency>com.certifiaweb:api</dependency>
Go go get go get github.com/certifiaweb/api-go

Usage Example (Node.js)

const CertifiaWeb = require('@certifiaweb/api');

const client = new CertifiaWeb('sk_test_BQokikJ...2HlWgH4olfQ2');

// List projects
const projects = await client.projects.list({
  status: 'active',
  limit: 10
});

// Create a project
const project = await client.projects.create({
  name: 'New Project',
  description: 'Project description'
});

Usage Example (Python)

import certifiaweb

client = certifiaweb.Client(api_key='sk_test_BQokikJ...2HlWgH4olfQ2')

# List projects
projects = client.projects.list(status='active', limit=10)

# Create a project
project = client.projects.create(
    name='New Project',
    description='Project description'
)

Testing

Test mode allows you to experiment with the API without affecting live data or incurring charges. All test mode requests use test API keys (prefixed with sk_test_).

Test Mode vs Live Mode

Feature Test Mode Live Mode
API Key Prefix sk_test_ sk_live_
Data Persistence Temporary (resets periodically) Permanent
Certifications Simulated Real
Webhooks Test endpoints only All endpoints

Test Cards & Data

In test mode, you can use special test values:

  • Test project IDs: proj_test_*
  • Test certification IDs: cert_test_*
  • All operations succeed instantly
  • No real compliance checks are performed

Sandbox Environment

Use our sandbox environment for integration testing:

https://sandbox.api.certifiaweb.com/v1

Code Examples

Complete code examples for common use cases.

Create Project and Request Certification

# Node.js
const CertifiaWeb = require('@certifiaweb/api');
const client = new CertifiaWeb(process.env.CERTIFIAWEB_API_KEY);

async function setupCompliance() {
  // Create project
  const project = await client.projects.create({
    name: 'ISO 27001 Compliance',
    category_id: 'cat_info_sec',
    status: 'draft'
  });

  // Request certification
  const certification = await client.certifications.request({
    project_id: project.id,
    standard_id: 'std_iso27001'
  });

  return { project, certification };
}

Upload Document and Check Compliance

# Python
import certifiaweb

client = certifiaweb.Client(api_key=os.environ['CERTIFIAWEB_API_KEY'])

# Upload document
with open('security_policy.pdf', 'rb') as f:
    document = client.documents.upload(
        file=f,
        project_id='proj_123',
        name='Security Policy',
        type='policy'
    )

# Check compliance status
status = client.compliance.get_status(
    project_id='proj_123',
    include_details=True
)

print(f"Compliance Score: {status.overall_score}%")

Handle Webhooks

# Express.js webhook handler
const express = require('express');
const crypto = require('crypto');

const app = express();

app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const secret = process.env.WEBHOOK_SECRET;

  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(req.body)
    .digest('hex');

  if (signature !== expectedSignature) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(req.body);

  if (event.type === 'certification.approved') {
    console.log(`Certification approved: ${event.data.id}`);
    // Handle certification approval
  }

  res.json({ received: true });
});