Skip to main content

Retrieve documents of your clients​


Follow this recipe to retrieve documents from a client's business space via an API app.


Prerequisites​

  • The API app has been granted the 'client_read' permission for the client. See Grant app access to clients recipe for information on granting access.
  • You have the following resource IDs:
    • partnerSpaceId: The spaceId of the partner to which the client is assigned.
    • clientId: The ID of the client whose documents you want to retrieve.
Retrieve the client's documents with a specific filter​

Endpoint: /workspace/partner/v2/spaces/{partnerSpaceId}/clients/{clientId}/documents


Path parameters:

  • partnerSpaceId
  • clientId

To retrieve documents issued within a specific date range, use the issueDate[gte] and issueDate[lte] filters.


curl -L 'https://{{serverURL}}/workspace/partner/v2/spaces/{partnerSpaceId}/clients/{clientId}/documents?issueDate[gte]=2026-01-01&issueDate[lte]=2026-08-31' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer YOUR_TOKEN'

Successful response:


{
  "documents" : [ {
    "id" : "3cc0af3d-b35a-46b5-b626-5c22258907e8",
    "spaceId" : "ffddb588-315d-49eb-b015-964978b4f0d8",
    "source" : "documentprocessor",
    "folder" : "PURCHASES",
    "status" : {
      "document" : "AWAITING_VALIDATION"
    },
    "category" : "INVOICE",
    "metadata" : {
      "$schema" : "https://btx.unifiedpost.com/btx/datastore/document/document_metadata/v1/document-metadata-schema.json",
      "dueDate" : "2026-07-31",
      "customer" : {
        "address" : {
          "country" : "BE",
          "postCode" : "8310",
          "townName" : "Brugge",
          "streetName" : "Leliestraat",
          "buildingNumber" : "14"
        },
        "legalName" : "SDD Active",
        "tradeName" : "SDD Active",
        "globalIdentifiers" : {
          "be:en" : "0800782609",
          "be:vat" : "BE0800782609",
          "global:participantId" : "0208:0800782609"
        }
      },
      "supplier" : {
        "address" : {
          "country" : "BE"
        },
        "legalName" : "Quick Quick Co",
        "tradeName" : "Quick Quick Co",
        "globalIdentifiers" : {
          "be:en" : "0408937548",
          "be:vat" : "BE0408937548"
        }
      },
      "issueDate" : "2026-03-01",
      "vatDetails" : [ {
        "netAmount" : "17.00",
        "vatAmount" : "1.02",
        "vatCategory" : "S",
        "vatPercentage" : "6"
      } ],
      "invoiceType" : "380",
      "currencyCode" : "EUR",
      "paymentMeans" : [ {
        "code" : "1",
        "paymentAccount" : {
          "scheme" : "IBAN",
          "identifier" : "BE62504010182561"
        }
      } ],
      "documentNumber" : "INV-0001",
      "documentTotals" : {
        "netAmount" : "17.00",
        "vatAmount" : "1.02",
        "grossAmount" : "18.02",
        "payableAmount" : "18.02",
        "linesNetAmount" : "17.00",
        "roundingAmount" : "0"
      },
      "linesNetAmount" : "17.00"
    },
    "tags" : [ "SEEN" ],
    "retentionTime" : "2036-06-15T04:27:04.676791Z",
    "readOnly" : false
  }, {
    "id" : "a17ab254-90ea-494b-b51b-88ad5922fe2e",
    "spaceId" : "ffddb588-315d-49eb-b015-964978b4f0d8",
    "source" : "documentcreator",
    "folder" : "PURCHASES",
    "status" : {
      "document" : "DRAFT"
    },
    "category" : "SELF_BILLED_INVOICE",
    "metadata" : {
      "$schema" : "https://btx.unifiedpost.com/btx/datastore/document/document_metadata/v1/document-metadata-schema.json",
      "dueDate" : "2026-06-25",
      "customer" : {
        "address" : {
          "country" : "BE",
          "postCode" : "8310",
          "townName" : "Brugge",
          "streetName" : "Leliestraat",
          "buildingNumber" : "14"
        },
        "legalName" : "SDD Active",
        "tradeName" : "SDD Active",
        "globalIdentifiers" : {
          "be:en" : "0800782609",
          "be:vat" : "BE0800782609"
        }
      },
      "issueDate" : "2026-05-26",
      "vatDetails" : [ {
        "netAmount" : "45.00",
        "vatAmount" : "2.70",
        "vatCategory" : "S",
        "vatPercentage" : "6"
      }, {
        "netAmount" : "23.00",
        "vatAmount" : "2.76",
        "vatCategory" : "S",
        "vatPercentage" : "12"
      } ],
      "invoiceType" : "389",
      "currencyCode" : "EUR",
      "documentNumber" : "AUTOGENERATE",
      "documentTotals" : {
        "netAmount" : "68.00",
        "vatAmount" : "5.46",
        "grossAmount" : "73.46",
        "payableAmount" : "73.46",
        "linesNetAmount" : "68.00",
        "roundingAmount" : "0"
      }
    },
    "tags" : [ ],
    "retentionTime" : "2037-05-26T00:00:00Z",
    "readOnly" : false
  }, {
    "id" : "40be2be1-2218-4218-92d0-b06ce5008be5",
    "spaceId" : "ffddb588-315d-49eb-b015-964978b4f0d8",
    "source" : "documentcreator",
    "folder" : "PURCHASES",
    "status" : {
      "document" : "DRAFT"
    },
    "category" : "SELF_BILLED_INVOICE",
    "metadata" : {
      "$schema" : "https://btx.unifiedpost.com/btx/datastore/document/document_metadata/v1/document-metadata-schema.json",
      "dueDate" : "2026-06-25",
      "customer" : {
        "address" : {
          "country" : "BE",
          "postCode" : "8310",
          "townName" : "Brugge",
          "streetName" : "Leliestraat",
          "buildingNumber" : "14"
        },
        "legalName" : "SDD Active",
        "tradeName" : "SDD Active",
        "globalIdentifiers" : {
          "be:en" : "0800782609",
          "be:vat" : "BE0800782609"
        }
      },
      "issueDate" : "2026-05-26",
      "invoiceType" : "389",
      "currencyCode" : "EUR"
    },
    "tags" : [ ],
    "retentionTime" : "2037-05-26T00:00:00Z",
    "readOnly" : false
  } ],
          "totalElements" : 3,
          "currentPage" : 1,
          "pageSize" : 1
}