Notifications
The notifications namespace gives your application access to fill pipeline events via standard REST API calls. When a fill job finishes or fails, a notification is recorded automatically - no extra setup required. Use these methods to display a badge counter, build an in-app notification feed, or check for completion without polling the document result endpoint directly.
What are notifications?
Every time the AI fill pipeline processes a job - whether it succeeds, fails, or reaches an intermediate state - the platform records a notification. Think of them as event receipts: they tell you what happened, when, and which pipeline or document was involved. You do not need to configure webhooks or set up listeners - notifications are recorded server-side and are available to fetch at any time through these REST endpoints.
list() on a schedule. Real-time push delivery (WebSockets / SSE) is not available yet and will be added in a future release.| Field | Type | Description |
|---|---|---|
| id | number | Unique numeric ID for this notification. |
| event_type | string | What happened - e.g. fill_complete or fill_failed. |
| status | string | Current pipeline state: ready, failed, or processing. |
| pipeline_id | string | The fill job that triggered this notification. |
| read | boolean | false until you call markAsRead(). |
| payload | object | The original event data - includes doc IDs, timestamps, and result details. |
import 'dotenv/config';
import Pdffillr from '@pdffillr/sdk';
const client = new Pdffillr({
apiKey: process.env['PDFFILLR_API_KEY'], // This is the default and can be omitted
});
// 1. list() - fetch the notification feed. Response includes unreadCount.
const result = await client.sdk.notifications.list();
console.log(`Unread: ${result.unreadCount}`);
result.data?.forEach((n) => {
console.log(`[${n.event_type}] Pipeline ${n.pipeline_id} - ${n.status}`);
});
// 2. markAsRead({ id }) - mark a single notification as read.
if (result.data && result.data.length > 0) {
await client.sdk.notifications.markAsRead({ id: result.data[0].id });
}
// 3. markAsRead() - omit id to mark all unread notifications as read.
await client.sdk.notifications.markAsRead();1. List Notifications
Returns your full notification feed - every event the pipeline has generated for your API key - ordered from newest to oldest. Results are paginated, so for large feeds you can request specific pages using the optional page and pageSize parameters. The response also conveniently includes the total unreadCount.
client.sdk.notifications.list(query?, options?)GET/v1/sdk/notifications| Parameter | Type | Default | Description |
|---|---|---|---|
| page | number | 1 | Page number to retrieve. 1-indexed. |
| pageSize | number | 20 | Number of notifications per page (1-100). |
import Pdffillr from '@pdffillr/sdk';
const client = new Pdffillr({
apiKey: process.env['PDFFILLR_API_KEY'], // This is the default and can be omitted
});
// Fetch the first page of notifications (default page size).
const result = await client.sdk.notifications.list();
console.log('Unread count:', result.unreadCount);
result.data?.forEach((notification) => {
console.log('Event type :', notification.event_type);
console.log('Pipeline :', notification.pipeline_id);
console.log('Status :', notification.status);
console.log('Read :', notification.read);
console.log('---');
});
// Paginate through a larger notification feed.
const page2 = await client.sdk.notifications.list({ page: 2, pageSize: 20 });
console.log(`Page 2 - ${page2.data?.length || 0} notification(s).`);docs.getMetadata() to check if a fill job is done, you can poll notifications.list() and look for a notification with event_type: "fill_complete". This is more efficient when you are waiting on multiple jobs at once.2. Mark Notification(s) as Read
Marks one or more notifications as read. By passing an object with an id, you mark a single, specific notification as read. If you omit the id, the system automatically marks all unread notifications as read at once.
client.sdk.notifications.markAsRead(body, options?)POST/v1/sdk/notifications/read| Parameter | Type | Required | Description |
|---|---|---|---|
| id | number | No | The numeric ID of the notification. Omit to mark ALL notifications as read. |
import Pdffillr from '@pdffillr/sdk';
const client = new Pdffillr({
apiKey: process.env['PDFFILLR_API_KEY'], // This is the default and can be omitted
});
// 1. Mark a single notification as read by passing its numeric ID.
await client.sdk.notifications.markAsRead({ id: 42 });
console.log('Notification 42 is now read.');
// 2. Clear all unread notifications in a single call by omitting the ID.
await client.sdk.notifications.markAsRead();
console.log('All notifications marked as read.');What to read next
PDFFILLR.AI
The intelligent layer for modern fund
administration. Automating high-stakes
documentation with precision and speed.