Node.js / TypeScript SDK

The official Creatorlayer Node.js SDK (creatorlayer) provides typed wrappers around the REST API with automatic retries, webhook signature verification, and full TypeScript support.

Requirements: Node.js ≥ 18, TypeScript ≥ 5.0 (optional but recommended)

---

Installation

npm install creatorlayer
# or
yarn add creatorlayer

---

Initialisation

import { Creatorlayer } from 'creatorlayer';

const cl = new Creatorlayer({
  apiKey: process.env.CREATORLAYER_API_KEY!,
});

Sandbox mode

const cl = new Creatorlayer({
  apiKey: process.env.CREATORLAYER_API_KEY!,
  sandbox: true, // points to https://api-sandbox.creatorlayer.eu
});

Configuration options

Option	Type	Default	Description
apiKey	string	required	Bearer API key issued during onboarding
sandbox	boolean	false	Use sandbox endpoint
baseUrl	string	production URL	Override the base URL (advanced)
maxRetries	number	2	Max automatic retries on 429 / 503
timeout	number	30000	Request timeout in milliseconds

---

Verifications

Create a verification

const { verification_id, consent_url } = await cl.verifications.create({
  obligor_reference: 'creator-abc-123',    // your internal creator ID
  creator_platforms: ['youtube', 'stripe'],
  lender_name: 'Acme Finance',
  product_type: 'rbf',                     // 'rbf' | 'term_loan' | 'securitization_pool'
});

// Send consent_url to the creator — they authorise data sharing through it.
console.log('Consent URL:', consent_url);

An Idempotency-Key is generated automatically. To retry safely with the same key:

const key = Creatorlayer.generateIdempotencyKey();
const result = await cl.verifications.create(params, key);

Poll verification status

const { status } = await cl.verifications.retrieve(verification_id);
// status: 'pending_consent' | 'consent_given' | 'processing' | 'completed' | 'failed'

Retrieve the Risk Tape

Once status === 'completed', fetch the full Risk Tape:

const tape = await cl.verifications.retrieveTape(verification_id);

console.log(tape.risk_profile.volatility_cv_12m);
console.log(tape.eligibility[0].risk_tier);     // 'prime' | 'standard' | 'subprime' | 'ineligible'
console.log(tape.eligibility[0].max_advance_amount);

---

Webhooks

Register an endpoint

const webhook = await cl.webhooks.create({
  url: 'https://your-app.example.com/webhooks/creatorlayer',
  events: ['verification.completed', 'verification.failed'],
});

console.log('Webhook secret:', webhook.secret); // store securely — shown once

List registered webhooks

const webhooks = await cl.webhooks.list();

Delete a webhook

await cl.webhooks.del(webhook.id);

Verify incoming webhook signatures

Always verify the X-Creatorlayer-Signature header before processing a payload.

// Express — use express.raw() to get the raw Buffer
app.post(
  '/webhooks/creatorlayer',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    let event;
    try {
      event = cl.webhooks.verifyAndParse(
        req.body,
        req.headers['x-creatorlayer-signature'] as string,
        process.env.WEBHOOK_SECRET!,
      );
    } catch {
      return res.sendStatus(400); // invalid signature
    }

    if (event.event === 'verification.completed') {
      const { verification_id } = event.data;
      // fetch the tape asynchronously
    }

    res.sendStatus(200);
  },
);

verifyAndParse throws CreatorlayerWebhookSignatureError on failure. Use verifySignature if you only need a boolean:

const ok = cl.webhooks.verifySignature(rawBody, signature, secret);

---

GDPR

The cl.gdpr resource supports data lookups and erasure requests for EU compliance.

// Look up personal data held for a creator
const data = await cl.gdpr.lookup({ creator_id: 'creator-abc-123' });

// Request data export (produces a download URL)
const { download_url } = await cl.gdpr.export({ creator_id: 'creator-abc-123' });

// Erase all personal data (irreversible)
await cl.gdpr.erase({ creator_id: 'creator-abc-123' });

---

Benchmarks

Retrieve peer-group benchmark percentiles for a completed verification:

const benchmarks = await cl.benchmarks.retrieve(verification_id);

for (const [metric, data] of Object.entries(benchmarks.metrics)) {
  console.log(`${metric}: p50=${data.p50}, your value=${data.value}`);
}

---

Error handling

All SDK methods throw typed errors. Import the error classes for instanceof checks:

import {
  CreatorlayerAuthError,
  CreatorlayerNotFoundError,
  CreatorlayerRateLimitError,
  CreatorlayerValidationError,
} from 'creatorlayer';

try {
  const tape = await cl.verifications.retrieveTape(id);
} catch (err) {
  if (err instanceof CreatorlayerNotFoundError) {
    // 404 — verification doesn't exist or tape not ready
  } else if (err instanceof CreatorlayerRateLimitError) {
    console.log(`Retry after ${err.retryAfter}s`);
  } else if (err instanceof CreatorlayerAuthError) {
    // 401 — check your API key
  } else {
    throw err;
  }
}

Class	HTTP status	When
CreatorlayerAuthError	401	Invalid or missing API key
CreatorlayerForbiddenError	403	Insufficient role
CreatorlayerNotFoundError	404	Resource not found
CreatorlayerValidationError	400 / 422	Invalid request parameters
CreatorlayerDuplicateError	409	Duplicate resource
CreatorlayerRateLimitError	429	Rate limit hit (err.retryAfter in seconds)
CreatorlayerServerError	500 / 503	Server-side error
CreatorlayerWebhookSignatureError	—	Webhook signature mismatch

The SDK automatically retries 429 (respecting Retry-After) and 503 (exponential backoff) up to maxRetries times.

---

Full example: verification + webhook

import { Creatorlayer, CreatorlayerNotFoundError } from 'creatorlayer';
import express from 'express';

const cl = new Creatorlayer({ apiKey: process.env.CREATORLAYER_API_KEY! });
const app = express();

// 1. Create verification and send consent link to creator
const { verification_id, consent_url } = await cl.verifications.create({
  obligor_reference: 'user-42',
  creator_platforms: ['youtube', 'patreon'],
  lender_name: 'My Finance Co',
});

// 2. Receive webhook when creator completes consent and tape is ready
app.post(
  '/webhooks/creatorlayer',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const event = cl.webhooks.verifyAndParse(
      req.body,
      req.headers['x-creatorlayer-signature'] as string,
      process.env.WEBHOOK_SECRET!,
    );

    if (event.event === 'verification.completed') {
      try {
        const tape = await cl.verifications.retrieveTape(event.data.verification_id);
        const decision = tape.eligibility.find(e => e.product_type === 'rbf');
        console.log('Risk tier:', decision?.risk_tier);
        console.log('Max advance:', decision?.max_advance_amount);
      } catch (err) {
        if (!(err instanceof CreatorlayerNotFoundError)) throw err;
      }
    }

    res.sendStatus(200);
  },
);

---

TypeScript types

All public types are exported from the package root:

import type {
  RiskTape,
  RiskTier,
  Platform,
  ProductType,
  WebhookEventPayload,
  CreateVerificationParams,
} from 'creatorlayer';

See the API Reference for full type documentation.