API Reference

Documents API

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

GET /projects/{project_id}/documents

List documents

Returns documents in a project, sorted by newest first.

Parameter Type Description
page number, optional Page number. Defaults to 1.
per_page number, optional Results per page. Defaults to 25, maximum 100.
Returns

A documents array and a pagination meta object.

Endpoint 
https://api.nicedata.ai/v1/projects/{project_id}/documents
Example request 
curl https://api.nicedata.ai/v1/projects/{project_id}/documents
  -H "Authorization: Bearer nd_live_abc123..."
Example response 
{
  "documents": [
    {
      "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"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 1,
    "total_pages": 1
  }
}
GET /projects/{project_id}/documents/{document_id}

Retrieve document

Returns a single document. When processing is complete, parsed_data is included.

No request parameters.

Returns

A document object.

Endpoint 
https://api.nicedata.ai/v1/projects/{project_id}/documents/{document_id}
Example request 
curl https://api.nicedata.ai/v1/projects/{project_id}/documents/{document_id}
  -H "Authorization: Bearer nd_live_abc123..."
Example response 
{
  "document": {
    "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"
    }
  }
}
POST /projects/{project_id}/documents

Upload document file

Uploads a file directly using multipart/form-data. Processing starts asynchronously.

Parameter Type Description
file file, required Supported extensions: .pdf, .jpg, .jpeg, .jfif, .png, .gif, .webp, .tiff, .tif, .heic, .heif, .bmp, .avif, .docx, .doc, .xlsx, .xls, .csv, .txt, .html. Maximum 15 MB. PDFs are limited to 25 pages.
Returns

The newly created document object with a pending status.

Endpoint 
https://api.nicedata.ai/v1/projects/{project_id}/documents
Example request 
curl https://api.nicedata.ai/v1/projects/{project_id}/documents \
  -X POST \
  -H "Authorization: Bearer nd_live_abc123..." \
  -F "file=@/path/to/invoice.pdf"
Example response 
{
  "document": {
    "id": "019d5678-abcd-7890-ef01-234567890abc",
    "filename": "invoice.pdf",
    "content_type": "application/pdf",
    "file_size": 245760,
    "file_extension": ".pdf",
    "status": "pending",
    "pages_count": null,
    "source": "api",
    "created_at": "2026-03-25T14:31:00Z"
  }
}
POST /projects/{project_id}/documents

Upload document from URL

Downloads a public HTTPS URL and processes the file. Private/internal network URLs are blocked, and redirects are treated as download failures.

Parameter Type Description
source string, required Must be url.
file_url string, required Public HTTPS URL to download. The downloaded file must match the supported file type and size limits.
Returns

The newly created document object with a pending status.

Endpoint 
https://api.nicedata.ai/v1/projects/{project_id}/documents
Example request 
curl https://api.nicedata.ai/v1/projects/{project_id}/documents \
  -X POST \
  -H "Authorization: Bearer nd_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"source":"url","file_url":"https://example.com/invoice.pdf"}'
Example response 
{
  "document": {
    "id": "019d5678-abcd-7890-ef01-234567890abc",
    "filename": "invoice.pdf",
    "content_type": "application/pdf",
    "file_size": 245760,
    "file_extension": ".pdf",
    "status": "pending",
    "pages_count": null,
    "source": "api",
    "created_at": "2026-03-25T14:31:00Z"
  }
}
POST /projects/{project_id}/documents

Create documents from email

Submits email body content and/or attachments. Each accepted body or attachment becomes a separate document. If no documents can be created, the API returns 422.

Parameter Type Description
source string, required Must be email.
subject string, optional Email subject line. Used to generate the body document filename.
body string, optional Plain text email body. Bodies shorter than 10 characters are ignored.
attachments array, optional Up to 10 attachment objects. Each object can include name or filename, content_type, content as base64, and content_length.
Returns

A documents array for the documents created by this request. Returns an error if the body is too short, all attachments are invalid or unsupported, or project email parsing settings exclude the submitted parts.

Endpoint 
https://api.nicedata.ai/v1/projects/{project_id}/documents
Example request 
curl https://api.nicedata.ai/v1/projects/{project_id}/documents \
  -X POST \
  -H "Authorization: Bearer nd_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"source":"email","subject":"March Expenses","body":"Please process this report.","attachments":[{"name":"expenses.pdf","content_type":"application/pdf","content":"JVBERi0xLjQK..."}]}'
Example response 
{
  "documents": [
    {
      "id": "019d5678-body-7890-ef01-234567890abc",
      "filename": "March_Expenses.txt",
      "content_type": "text/plain",
      "file_size": 245760,
      "file_extension": ".txt",
      "status": "pending",
      "pages_count": null,
      "source": "email",
      "created_at": "2026-03-25T14:31:00Z"
    },
    {
      "id": "019d5678-file-7890-ef01-234567890abc",
      "filename": "expenses.pdf",
      "content_type": "application/pdf",
      "file_size": 245760,
      "file_extension": ".pdf",
      "status": "pending",
      "pages_count": null,
      "source": "email",
      "created_at": "2026-03-25T14:31:00Z"
    }
  ]
}
DELETE /projects/{project_id}/documents/{document_id}

Delete document

Permanently deletes the document and all associated stored files.

No request parameters.

Returns

No content.

Endpoint 
https://api.nicedata.ai/v1/projects/{project_id}/documents/{document_id}
Example request 
curl https://api.nicedata.ai/v1/projects/{project_id}/documents/{document_id} \
  -X DELETE \
  -H "Authorization: Bearer nd_live_abc123..."
Example response 
204 No Content

Related sections

API basics

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

Object reference

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

Projects API

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