API Reference

Object reference

Field-by-field reference for project, document, webhook, webhook event, and usage objects.

Object

The project object

Projects group documents, define an inbound email address, and own project-scoped webhooks.

Attribute Type Description
id uuid Unique project identifier.
name string Project name. 1 to 100 characters and unique within an organization.
email string Generated inbound email address for documents sent by email.
email_parse_option string How inbound email is processed. One of both, body, or attachments.
retention_days number Automatic document retention period. One of 1, 14, 30, 60, or 90.
documents_count number Number of documents currently in the project.
created_at datetime ISO 8601 timestamp when the project was created.
Example 
{
  "id": "019d1234-abcd-7890-ef01-234567890abc",
  "name": "Receipts",
  "email": "[email protected]",
  "email_parse_option": "both",
  "retention_days": 60,
  "documents_count": 8,
  "created_at": "2026-03-25T14:30:00Z"
}

Object

The document object

Documents are processed asynchronously. Uploads return a pending document, then move through processing to completed or failed.

Attribute Type Description
id uuid Unique document identifier.
filename string Sanitized filename stored in the project.
content_type string Detected or uploaded MIME type.
file_size number File size in bytes.
file_extension string Lowercase extension, including the leading dot.
status string Current run status. One of pending, processing, completed, or failed.
pages_count number or null Processed page count once known.
source string How the document entered NiceData. API file and URL uploads use api; email submissions use email.
parsed_data object Included by retrieve document after processing completes.
error_message string Included when the latest processing run failed.
email_metadata object Included by retrieve document when email metadata is present.
created_at datetime ISO 8601 timestamp when the document was created.
Example 
{
  "id": "019d5678-abcd-7890-ef01-234567890abc",
  "filename": "invoice.pdf",
  "content_type": "application/pdf",
  "file_size": 245760,
  "file_extension": ".pdf",
  "status": "completed",
  "pages_count": 3,
  "source": "api",
  "created_at": "2026-03-25T14:31:00Z",
  "parsed_data": {
    "vendor": "Acme Corp",
    "invoice_number": "INV-2026-0342",
    "total": "$1,250.00"
  },
  "email_metadata": {
    "from": "api",
    "subject": "March Expenses",
    "source": "api"
  }
}

Object

The webhook object

Webhooks belong to a project and receive document processing events. The signing secret is only returned when a webhook is created.

Attribute Type Description
id uuid Unique webhook identifier.
event_type string One of document.processed or document.failed.
target_url string HTTPS delivery URL. Private and internal network targets are rejected.
name string Display name.
active boolean Whether deliveries are enabled. Defaults to true.
signing_secret string Only included in the create response. Store it securely.
created_at datetime ISO 8601 timestamp when the webhook was created.
Example 
{
  "id": "019d9999-abcd-7890-ef01-234567890abc",
  "event_type": "document.processed",
  "target_url": "https://example.com/webhooks/nicedata",
  "name": "Production",
  "active": true,
  "created_at": "2026-03-25T14:35:00Z",
  "signing_secret": "a1b2c3d4e5f6..."
}

Object

The webhook event object

Webhook deliveries include document, processing, project, and organization context. Parsed data above 100 KB is omitted and can be fetched from the document endpoint.

Attribute Type Description
id uuid Unique delivery payload identifier.
event string Event name. document.processed or document.failed.
occurred_at datetime ISO 8601 timestamp when the event payload was built.
document object Document snapshot at delivery time.
processing object Current run state, page count, duration, completion time, and error message.
parsed_data object or null Extracted data when available and under the size limit.
parsed_data_truncated boolean True when parsed_data was omitted because it exceeded 100 KB.
parsed_data_size_bytes number or null Serialized parsed data size.
parsed_data_sha256 string or null SHA-256 digest of the serialized parsed data.
project object Project id and name.
organization object Organization id and name.
Example 
{
  "id": "d70961db-9b8f-4ab2-9f9a-3fd130ca7b98",
  "event": "document.processed",
  "occurred_at": "2026-03-25T16:05:00Z",
  "document": {
    "id": "019d5678-abcd-7890-ef01-234567890abc",
    "filename": "invoice.pdf",
    "content_type": "application/pdf",
    "file_size": 245760,
    "file_extension": ".pdf",
    "source": "api",
    "created_at": "2026-03-25T14:31:00Z"
  },
  "processing": {
    "run_id": "019d7777-abcd-7890-ef01-234567890abc",
    "status": "completed",
    "pages_count": 3,
    "duration_seconds": 12.34,
    "completed_at": "2026-03-25T16:05:00Z",
    "error_message": null
  },
  "parsed_data": {
    "vendor": "Acme Corp"
  },
  "parsed_data_truncated": false,
  "parsed_data_size_bytes": 58,
  "parsed_data_sha256": "3f0f0c7a...",
  "project": {
    "id": "019d1234-abcd-7890-ef01-234567890abc",
    "name": "Receipts"
  },
  "organization": {
    "id": "019d0000-abcd-7890-ef01-234567890abc",
    "name": "Acme Inc"
  }
}

Object

The usage object

Usage reports the current billing-period page consumption and whether uploads are currently allowed.

Attribute Type Description
current_usage number Pages used in the current billing period.
page_limit number or null Pages included in the current plan. Null when plan details are hidden.
remaining_pages number or null Pages remaining in the current billing period. Null when plan details are hidden.
can_upload boolean False when uploads are blocked by usage limits.
plan string or null Current plan name. Hidden internal plans are returned as custom.
billing_period_start datetime or null ISO 8601 billing period start.
billing_period_end datetime or null ISO 8601 billing period end.
Example 
{
  "current_usage": 142,
  "page_limit": 2500,
  "remaining_pages": 2358,
  "can_upload": true,
  "plan": "2500_pages",
  "billing_period_start": "2026-03-01T00:00:00Z",
  "billing_period_end": "2026-03-31T23:59:59Z"
}

Related sections

API basics

Authentication, rate limits, pagination, and error handling for the public NiceData API.

Projects API

Create, list, retrieve, update, and delete projects programmatically.

Documents API

Upload files, submit email content, retrieve extracted data, and delete document records.