@complyforce/api

Complyforce TypeScript/JavaScript SDK

Complyforce is an AI-assisted website compliance auditing service that identifies services, cookies, and data processing, and checks them against your consent setup for GDPR/ePrivacy (and related national) compliance issues. It generates legally evaluable compliance reports (including machine-readable output) that can be triggered and accessed via an API for integration into your product.

The Complyforce TypeScript/JavaScript SDK provides seamless integration with the Complyforce API. This library is designed to simplify API interactions and provide tools for efficient implementation.

Detailed API documentation is available at complyforce.com/api/docs.

Requirements

Node.js 18 or newer

Installation

To install the library, run (with your preferred package manager):

npm install @complyforce/api

Usage

Configuration

Set up the SDK with your Complyforce API key. You can generate an API key in the Complyforce Vendor Dashboard.

ESM (recommended)

import { ComplyforceApi, client } from "@complyforce/api";

const apiKey = "your_api_key_here";

client.setConfig({ auth: apiKey });
const api = new ComplyforceApi();

CommonJS

const { ComplyforceApi, client } = require("@complyforce/api");

const apiKey = "your_api_key_here";

client.setConfig({ auth: apiKey });
const api = new ComplyforceApi();

Private deployments

If you are a large-scale enterprise customer using a private Complyforce deployment, create a custom client with an explicit baseUrl. The major version of this SDK package mirrors the API version. Make sure you use the correct SDK version for the compatible API version.

import { ComplyforceApi, createClient } from "@complyforce/api";

const apiKey = "your_api_key_here";
const apiVersion = "v1";

const api = new ComplyforceApi({
    client: createClient({
        baseUrl: `https://your-instance.complyforce.com/${apiVersion}`,
        auth: apiKey,
    }),
});

Response handling

SDK methods return a RequestResult with data, error, response, and request when responseStyle is fields (default).

If you prefer a success-only result and exception-based error handling, combine responseStyle: "data" with throwOnError: true. You get just the data on success, and you catch errors with try/catch.

Default: responseStyle: "fields"

client.setConfig({
    responseStyle: "fields",
    throwOnError: false,
});

const result = await api.getVendorApiKeyValidate();

if (result.response.ok) {
    // result.data contains the typed response body
    console.log(result.data?.vendorName);
} else {
    // result.error contains the typed error response
    console.error(result.error);
}

Expected shape (success):

{
  data: { /* ... */ },
  error: undefined,
  request: Request,
  response: Response
}

Expected shape (error):

{
  data: undefined,
  error: Array<{ code: string; message?: string; /* ... */ }>,
  request: Request,
  response: Response | undefined
}

Alternative: responseStyle: "data" + throwOnError: true

client.setConfig({
    responseStyle: "data",
    throwOnError: true,
});

try {
    const data = await api.getOrderProgress({
        query: { orderUuid: "your-order-uuid" },
    });
    // `data` is the response body
    console.log(data);
} catch (error) {
    // `error` is thrown on non-2xx responses or network errors
    console.error("Request failed", error);
}

Expected shape:

// On success
{
    /* response body */
}

// On error
// throws, no result object returned

API Methods

Each method below maps directly to an API endpoint. For detailed payloads, see the Complyforce API docs.

getVendorApiKeyValidate()

Validates the API key and returns the vendor name if authorized.

const apiKeyValidate = await api.getVendorApiKeyValidate();

if (apiKeyValidate?.response.ok && apiKeyValidate.data?.vendorName) {
    console.log(`Authenticated as ${apiKeyValidate.data.vendorName}`);
} else {
    console.error("Authentication failed", apiKeyValidate.error);
}

postOrder()

Accepting an order for a website scan with one, several, all, or the most relevant subpages. You can specify scan type, requested URLs, and the channel UUID. You can create a channel in Brand & Channel > [Name of brand] > Create channel in the Complyforce Vendor Dashboard.

const channelUuid = "your-channel-uuid";

const postedOrder = await api.postOrder({
    body: {
        order: {
            scanType: "single",
            scanUrlsRequested: ["https://example.com"],
            channel: {
                uuid: channelUuid,
            },
        },
    },
});

if (postedOrder?.response.ok) {
    console.log("Order created", postedOrder.data?.order);
} else {
    console.error("Create order failed", postedOrder.error);
}

Scan types (details in the API docs)

scanType	What it does	When to use
single	Scans one specific page.	You need a specific or fast overview of data protection issues.
multiple	Scans at least two specific pages.	You want targeted coverage of important known pages and processes (e.g. product page, checkout, company profile).
mostRelevant	Finds and scans up to 10-15 representative subpages.	You need an analysis that can uncover most problems.
all	Scans all pages found via the sitemap.	You need a comprehensive data protection analysis of the entire website.

getOrder()

Retrieve order data, current status and status updates, as well as report link and summary for completed orders.

const orderUuid = "your-order-uuid";

const readOrder = await api.getOrder({
    query: {
        orderUuid: orderUuid,
        statusUpdates: "true",
        report: "false",
    },
});

if (readOrder?.response.ok) {
    console.log("Order data", readOrder.data?.order);
} else {
    console.error("Read order failed", readOrder.error);
}

getOrderProgress()

Fetches scan progress of the order as a percentage.

You can also receive the order progress by a webhook. Configure the webhook at Brand & Channel > [Name of brand] > [Name of channel] > Edit > Webhooks in the Complyforce Vendor Dashboard.

const orderUuid = "your-order-uuid";

const readOrderProgress = await api.getOrderProgress({
    query: {
        orderUuid: orderUuid,
    },
});

if (readOrderProgress?.response.ok) {
    console.log("Order progress", readOrderProgress.data?.progressInPercent);
} else {
    console.error("Read order progress failed", readOrderProgress.error);
}

getOrderReport()

Retrieve full report data and report link for completed orders.

const orderUuid = "your-order-uuid";

const readOrderReport = await api.getOrderReport({
    query: {
        orderUuid: orderUuid,
    },
});

if (readOrderReport?.response.ok) {
    console.log("Order report", readOrderReport.data);
} else if (readOrderReport.error?.[0]?.code === "OrderNotCompletedOrCompletedPartially") {
    console.log("Order not completed yet");
} else {
    console.error("Read order report failed", readOrderReport.error);
}

deleteOrderReport()

Deletes an existing order report prior to its expiry date.

const orderUuid = "your-order-uuid";

const deleteOrderReport = await api.deleteOrderReport({
    body: {
        order: {
            uuid: orderUuid,
        },
    },
});

if (deleteOrderReport?.response.ok) {
    console.log("Order report deleted");
} else {
    console.error("Delete order report failed", deleteOrderReport.error);
}

Support

Need integration support? Our developers can build an individual solution with you. Contact our support team via the Complyforce Vendor Dashboard!