API Documentation

Everything you need to integrate Aficial into your system

Authentication

Send a scoped Aficial API key as a header with every request. Keys are shown once, stored only as hashes, and can be revoked.

x-api-key: afc_live_abcdefghij_your_secret_part_here

Alternatively: Authorization: Bearer afc_live_abcdefghij_your_secret_part_here

API Keys

Authenticated admins create keys through API key management. Webhook ingest requires the scope webhook:write.

curl -X POST https://aficial.ai/api/api-keys \
  -H "Content-Type: application/json" \
  -H "Cookie: sb-access-token=USER_SESSION" \
  -d '{
    "name": "Shop webhook",
    "scopes": ["webhook:write"],
    "rateLimitPerMinute": 120
  }'

The OpenAPI document is available at /api/openapi.

Endpoints

POST/api/webhookSend external business data into Aficial

Webhook

The webhook endpoint accepts data that the agent uses to answer customer inquiries. More data means better answers.

The agent uses this data automatically. If a customer asks about order #4521 and you sent this order via webhook, the agent can provide tracking number, status and details.

Send orders

curl -X POST https://aficial.ai/api/webhook \
  -H "Content-Type: application/json" \
  -H "x-api-key: afc_live_abcdefghij_your_secret_part_here" \
  -d '{
    "type": "order",
    "order": {
      "order_number": "4521",
      "status": "shipped",
      "tracking_number": "DE-2026-4521-89",
      "carrier": "DHL",
      "customer_email": "max@example.com",
      "customer_name": "Max Müller",
      "items": [
        { "name": "Wireless Headphones Pro", "qty": 2, "price": 59.95 },
        { "name": "Ladestation", "qty": 1, "price": 29.99 }
      ],
      "total": 149.89,
      "currency": "EUR",
      "ordered_at": "2026-03-12T10:30:00Z",
      "shipped_at": "2026-03-14T06:42:00Z"
    }
  }'

Response

{ "success": true, "message": "Order data received" }

Send customer data

curl -X POST https://aficial.ai/api/webhook \
  -H "Content-Type: application/json" \
  -H "x-api-key: afc_live_abcdefghij_your_secret_part_here" \
  -d '{
    "type": "customer",
    "customer": {
      "email": "max@example.com",
      "name": "Max Müller",
      "company": "Müller GmbH",
      "phone": "+49 123 456789",
      "tier": "premium",
      "lifetime_value": 2450.00,
      "orders_count": 18,
      "since": "2024-01-15",
      "tags": ["vip", "enterprise"]
    }
  }'

Send products

curl -X POST https://aficial.ai/api/webhook \
  -H "Content-Type: application/json" \
  -H "x-api-key: afc_live_abcdefghij_your_secret_part_here" \
  -d '{
    "type": "product",
    "product": {
      "sku": "WHP-001",
      "name": "Wireless Headphones Pro",
      "price": 59.95,
      "currency": "EUR",
      "in_stock": true,
      "category": "Audio",
      "description": "Kabellose Kopfhörer mit Active Noise Cancelling",
      "return_policy": "14 Tage Rückgabe, Originalverpackung nötig"
    }
  }'

Send events

Any events the agent uses as context:

curl -X POST https://aficial.ai/api/webhook \
  -H "Content-Type: application/json" \
  -H "x-api-key: afc_live_abcdefghij_your_secret_part_here" \
  -d '{
    "type": "event",
    "event": "shipping_delay",
    "data": {
      "region": "EU",
      "delay_days": 2,
      "reason": "Wetterbedingungen",
      "affected_orders": ["4521", "4522", "4530"]
    }
  }'

Max Payload: 100 KB. Format: JSON. Any structure, the agent processes everything.

Customer satisfaction (CSAT)

Every AI reply gets a unique CSAT token. Customers can use it to rate.

Query status

GET /api/csat?token=CSAT_TOKEN

Submit rating

curl -X POST https://aficial.ai/api/csat \
  -H "Content-Type: application/json" \
  -d '{
    "token": "CSAT_TOKEN",
    "rating": 5,
    "comment": "Schnelle und hilfreiche Antwort"
  }'

Rating: 1-5. Comment: optional, max 500 characters. Each token can only be rated once.

Redeem activation code

Authenticated endpoint. The signed-in user redeems a code for their organization.

curl -X POST https://aficial.ai/api/activate \
  -H "Content-Type: application/json" \
  -H "Cookie: sb-access-token=USER_SESSION" \
  -d '{
    "code": "HELLOFRESH"
  }'

Response

{
  "success": true,
  "plan": "starter",
  "trialDays": 14,
  "trialEnds": "2026-04-06T12:00:00.000Z",
  "message": "Aktiviert! Ihr 14-Tage Testzeitraum läuft."
}

Health Check

GET /api/health

Response

{
  "status": "healthy",
  "uptime": 42.5,
  "totalMs": 155,
  "checks": {
    "supabase": { "status": "ok", "ms": 56 },
    "redis": { "status": "ok", "ms": 104 },
    "anthropic": { "status": "ok" }
  },
  "version": "1.0.0"
}

Outgoing Webhooks

Aficial can notify your system when something happens. Configure webhook URLs in the dashboard under Integrations.

Events

email.receivedNew email received

reply.sentReply sent

email.escalatedEmail escalated to team

sla.breachedSLA deadline exceeded

csat.receivedNew CSAT rating

Payload example

{
  "event": "reply.sent",
  "timestamp": "2026-03-23T14:30:00Z",
  "data": {
    "emailId": "abc-123",
    "replyId": "def-456",
    "category": "order_status"
  }
}

Signature verification

Every webhook is signed with HMAC-SHA256:

X-Aficial-Signature: sha256=a1b2c3d4e5...
X-Aficial-Event: reply.sent

// Node.js Verification
const crypto = require('crypto');
const signature = crypto
  .createHmac('sha256', WEBHOOK_SECRET)
  .update(JSON.stringify(body))
  .digest('hex');
const valid = signature === header.split('=')[1];

Rate Limits

Webhook

100 Requests/minper IP

CSAT

30 Requests/minper IP

Inbox Test

5 Requests/minper user

AI Processing

60 Requests/minper org

When exceeded you will receive 429 Too Many Requests with Retry-After Header.

Error codes

200

SuccessRequest processed successfully

400

Bad RequestMissing or invalid parameters

401

UnauthorizedMissing or invalid API key

403

ForbiddenNo permission for this resource

404

Not FoundResource does not exist

413

Payload Too LargeRequest body over 100 KB

429

Rate LimitedToo many requests, please wait

500

Server ErrorInternal error, please try again

Error Response Format

{
  "error": "Token and rating required"
}

SDKs & Libraries

Official SDKs are planned. Until then any HTTP client works. Example for the webhook endpoint:

JavaScript / Node.js

const res = await fetch('https://aficial.ai/api/webhook', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'afc_live_abcdefghij_your_secret_part_here',
  },
  body: JSON.stringify({
    type: 'order',
    order: { order_number: '4521', status: 'shipped' },
  }),
});
console.log(await res.json());

Python

import requests

res = requests.post(
    'https://aficial.ai/api/webhook',
    headers={'x-api-key': 'afc_live_abcdefghij_your_secret_part_here'},
    json={'type': 'order', 'order': {'order_number': '4521', 'status': 'shipped'}},
)
print(res.json())

PHP

$ch = curl_init('https://aficial.ai/api/webhook');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'x-api-key: afc_live_abcdefghij_your_secret_part_here',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'type' => 'order',
    'order' => ['order_number' => '4521', 'status' => 'shipped'],
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
echo curl_exec($ch);

Ruby

require 'net/http'
require 'json'

uri = URI('https://aficial.ai/api/webhook')
req = Net::HTTP::Post.new(uri, {
  'Content-Type' => 'application/json',
  'x-api-key' => 'afc_live_abcdefghij_your_secret_part_here',
})
req.body = { type: 'order', order: { order_number: '4521', status: 'shipped' } }.to_json
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
puts res.body

API Documentation

Everything you need to integrate Aficial into your system

Authentication

Send a scoped Aficial API key as a header with every request. Keys are shown once, stored only as hashes, and can be revoked.

x-api-key: afc_live_abcdefghij_your_secret_part_here

Alternatively: Authorization: Bearer afc_live_abcdefghij_your_secret_part_here

API Keys

Authenticated admins create keys through API key management. Webhook ingest requires the scope webhook:write.

curl -X POST https://aficial.ai/api/api-keys \
  -H "Content-Type: application/json" \
  -H "Cookie: sb-access-token=USER_SESSION" \
  -d '{
    "name": "Shop webhook",
    "scopes": ["webhook:write"],
    "rateLimitPerMinute": 120
  }'

The OpenAPI document is available at /api/openapi.

Endpoints

POST/api/webhookSend external business data into Aficial

Webhook

The webhook endpoint accepts data that the agent uses to answer customer inquiries. More data means better answers.

The agent uses this data automatically. If a customer asks about order #4521 and you sent this order via webhook, the agent can provide tracking number, status and details.

Send orders

curl -X POST https://aficial.ai/api/webhook \
  -H "Content-Type: application/json" \
  -H "x-api-key: afc_live_abcdefghij_your_secret_part_here" \
  -d '{
    "type": "order",
    "order": {
      "order_number": "4521",
      "status": "shipped",
      "tracking_number": "DE-2026-4521-89",
      "carrier": "DHL",
      "customer_email": "max@example.com",
      "customer_name": "Max Müller",
      "items": [
        { "name": "Wireless Headphones Pro", "qty": 2, "price": 59.95 },
        { "name": "Ladestation", "qty": 1, "price": 29.99 }
      ],
      "total": 149.89,
      "currency": "EUR",
      "ordered_at": "2026-03-12T10:30:00Z",
      "shipped_at": "2026-03-14T06:42:00Z"
    }
  }'

Response

{ "success": true, "message": "Order data received" }

Send customer data

curl -X POST https://aficial.ai/api/webhook \
  -H "Content-Type: application/json" \
  -H "x-api-key: afc_live_abcdefghij_your_secret_part_here" \
  -d '{
    "type": "customer",
    "customer": {
      "email": "max@example.com",
      "name": "Max Müller",
      "company": "Müller GmbH",
      "phone": "+49 123 456789",
      "tier": "premium",
      "lifetime_value": 2450.00,
      "orders_count": 18,
      "since": "2024-01-15",
      "tags": ["vip", "enterprise"]
    }
  }'

Send products

curl -X POST https://aficial.ai/api/webhook \
  -H "Content-Type: application/json" \
  -H "x-api-key: afc_live_abcdefghij_your_secret_part_here" \
  -d '{
    "type": "product",
    "product": {
      "sku": "WHP-001",
      "name": "Wireless Headphones Pro",
      "price": 59.95,
      "currency": "EUR",
      "in_stock": true,
      "category": "Audio",
      "description": "Kabellose Kopfhörer mit Active Noise Cancelling",
      "return_policy": "14 Tage Rückgabe, Originalverpackung nötig"
    }
  }'

Send events

Any events the agent uses as context:

curl -X POST https://aficial.ai/api/webhook \
  -H "Content-Type: application/json" \
  -H "x-api-key: afc_live_abcdefghij_your_secret_part_here" \
  -d '{
    "type": "event",
    "event": "shipping_delay",
    "data": {
      "region": "EU",
      "delay_days": 2,
      "reason": "Wetterbedingungen",
      "affected_orders": ["4521", "4522", "4530"]
    }
  }'

Max Payload: 100 KB. Format: JSON. Any structure, the agent processes everything.

Customer satisfaction (CSAT)

Every AI reply gets a unique CSAT token. Customers can use it to rate.

Query status

GET /api/csat?token=CSAT_TOKEN

Submit rating

curl -X POST https://aficial.ai/api/csat \
  -H "Content-Type: application/json" \
  -d '{
    "token": "CSAT_TOKEN",
    "rating": 5,
    "comment": "Schnelle und hilfreiche Antwort"
  }'

Rating: 1-5. Comment: optional, max 500 characters. Each token can only be rated once.

Redeem activation code

Authenticated endpoint. The signed-in user redeems a code for their organization.

curl -X POST https://aficial.ai/api/activate \
  -H "Content-Type: application/json" \
  -H "Cookie: sb-access-token=USER_SESSION" \
  -d '{
    "code": "HELLOFRESH"
  }'

Response

{
  "success": true,
  "plan": "starter",
  "trialDays": 14,
  "trialEnds": "2026-04-06T12:00:00.000Z",
  "message": "Aktiviert! Ihr 14-Tage Testzeitraum läuft."
}

Health Check

GET /api/health

Response

{
  "status": "healthy",
  "uptime": 42.5,
  "totalMs": 155,
  "checks": {
    "supabase": { "status": "ok", "ms": 56 },
    "redis": { "status": "ok", "ms": 104 },
    "anthropic": { "status": "ok" }
  },
  "version": "1.0.0"
}

Outgoing Webhooks

Aficial can notify your system when something happens. Configure webhook URLs in the dashboard under Integrations.

Events

email.receivedNew email received

reply.sentReply sent

email.escalatedEmail escalated to team

sla.breachedSLA deadline exceeded

csat.receivedNew CSAT rating

Payload example

{
  "event": "reply.sent",
  "timestamp": "2026-03-23T14:30:00Z",
  "data": {
    "emailId": "abc-123",
    "replyId": "def-456",
    "category": "order_status"
  }
}

Signature verification

Every webhook is signed with HMAC-SHA256:

X-Aficial-Signature: sha256=a1b2c3d4e5...
X-Aficial-Event: reply.sent

// Node.js Verification
const crypto = require('crypto');
const signature = crypto
  .createHmac('sha256', WEBHOOK_SECRET)
  .update(JSON.stringify(body))
  .digest('hex');
const valid = signature === header.split('=')[1];

Rate Limits

Webhook

100 Requests/minper IP

CSAT

30 Requests/minper IP

Inbox Test

5 Requests/minper user

AI Processing

60 Requests/minper org

When exceeded you will receive 429 Too Many Requests with Retry-After Header.

Error codes

200

SuccessRequest processed successfully

400

Bad RequestMissing or invalid parameters

401

UnauthorizedMissing or invalid API key

403

ForbiddenNo permission for this resource

404

Not FoundResource does not exist

413

Payload Too LargeRequest body over 100 KB

429

Rate LimitedToo many requests, please wait

500

Server ErrorInternal error, please try again

Error Response Format

{
  "error": "Token and rating required"
}

SDKs & Libraries

Official SDKs are planned. Until then any HTTP client works. Example for the webhook endpoint:

JavaScript / Node.js

const res = await fetch('https://aficial.ai/api/webhook', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'afc_live_abcdefghij_your_secret_part_here',
  },
  body: JSON.stringify({
    type: 'order',
    order: { order_number: '4521', status: 'shipped' },
  }),
});
console.log(await res.json());

Python

import requests

res = requests.post(
    'https://aficial.ai/api/webhook',
    headers={'x-api-key': 'afc_live_abcdefghij_your_secret_part_here'},
    json={'type': 'order', 'order': {'order_number': '4521', 'status': 'shipped'}},
)
print(res.json())

PHP

$ch = curl_init('https://aficial.ai/api/webhook');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'x-api-key: afc_live_abcdefghij_your_secret_part_here',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'type' => 'order',
    'order' => ['order_number' => '4521', 'status' => 'shipped'],
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
echo curl_exec($ch);

Ruby

require 'net/http'
require 'json'

uri = URI('https://aficial.ai/api/webhook')
req = Net::HTTP::Post.new(uri, {
  'Content-Type' => 'application/json',
  'x-api-key' => 'afc_live_abcdefghij_your_secret_part_here',
})
req.body = { type: 'order', order: { order_number: '4521', status: 'shipped' } }.to_json
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
puts res.body