Documents

Documents let you attach receipts, invoices, contracts, or other evidence to transactions. Use these endpoints to store metadata and link documents to purchases, invoices, or journal entries.

Prerequisites

• A Naqood API secret or OAuth-issued secret scoped to the organization
• The organization slug on every request
• A role that can manage documents in that organization

Upload flow (signed URLs)

Uploads use short-lived signed URLs. The flow keeps files private while letting you stream bytes directly.

1. Request a write token via docToken:

   query DocUploadUrl($slug: Slug!, $filename: String) {
     docToken(slug: $slug, action: write, filename: $filename) {
       id
       token
     }
   }

   • token is a pre-signed URL valid for ~15 minutes.
   • id is the document ID you will reference later.

2. Upload the file with PUT to the returned token. Set Content-Type to the file’s MIME type and send the raw bytes as the body.

3. Register metadata with createDoc, using the id from step 1 as input.id.

4. Attach that id to other mutations (for example docs on purchases or invoices).

Document fields

Field	Type	Notes
id	ID!	Stable identifier
number	Int!	Auto-incremented document sequence
name	String	Display name shown in the UI
source	String	Free-form source label (for example email)
note	String	Optional note
url	String	Download URL (when available)
isBooked	Boolean	Indicates whether the document is linked to a transaction
createdAt / updatedAt	Timestamp!	Audit timestamps

List documents

Fetch documents for an organization with paging, sorting, filtering, and optional search.

query Documents(
  $slug: Slug!
  $offset: Int
  $limit: Int
  $orderBy: OrderByInput
  $filter: JSONObject
  $search: String
) {
  organization(slug: $slug) {
    docs(
      offset: $offset
      limit: $limit
      orderBy: $orderBy
      filter: $filter
      search: $search
    ) {
      count
      entries {
        id
        name
        source
        url
        createdAt
      }
    }
  }
}

• filter supports the standard operators (equalTo, notEqualTo, greaterThan, lessThanOrEqualTo, in, plus and/or groups).
• search lets you match by name.

Create a document record

Use createDoc to register a document’s metadata after you have uploaded the file. Supply your own id to correlate the upload with the record you create here.

mutation CreateDocument($input: CreateDocInput!) {
  createDoc(input: $input)
}

CreateDocInput fields:

Field	Required	Notes
slug	✅	Organization issuing the document
id	✅	Identifier from the upload token (step 1)
name	✅	Display name
source	Optional	Source label (for example email, web)
note	Optional	Additional context

Example variables:

{
  "input": {
    "slug": "acme-co",
    "id": "doc_123",
    "name": "receipt-88312.pdf",
    "source": "web",
    "note": "Supplier receipt"
  }
}

Update a document

mutation UpdateDocument($input: UpdateDocInput!) {
  updateDoc(input: $input)
}

UpdateDocInput accepts docId plus optional name and note changes.

Delete a document

mutation DeleteDocument($docId: ID!) {
  deleteDoc(docId: $docId)
}

Only delete documents you no longer need; keep attachments that support existing transactions.

Attach documents to other records

Most entities that accept supporting files expose a docs field (for example CreatePurchaseInput). Pass the document IDs you created with createDoc to attach them when creating or updating those records. This keeps receipts and evidence linked to the ledger entry for later review.