Uploading documents to the GraphQL API

The Vasco API accepts file uploads through the GraphQL multipart request spec. File arguments use the custom scalar UploadDocument (single file) or [UploadDocument!]! (multiple files).

Prerequisites

• A valid JWT — see the Authentication guide.
• The right environment host — see API endpoints.

Request format

A file upload is a multipart/form-data POST to /graphql/ with three parts:

1. operations — JSON with the query and variables. File-typed variables are set to null.
2. map — JSON mapping each file part ("0", "1", …) to the variable path it fills.
3. 0, 1, … — the actual file payloads.

cURL example (single file)

curl -X POST https://api.<client>.vasco.fund/graphql/ \
  -H "Authorization: Bearer $TOKEN" \
  -F operations='{
    "query": "mutation($accountId: ID!, $documentType: DocumentType!, $uploadedDocument: UploadDocument!, $issueDate: Date!) { UploadAccountDocument(accountId:$accountId, documentType:$documentType, uploadedDocument:$uploadedDocument, issueDate:$issueDate) { id } }",
    "variables": {
      "accountId": "abc-123",
      "documentType": "KYC_DOCUMENT",
      "uploadedDocument": null,
      "issueDate": "2026-05-28"
    }
  }' \
  -F map='{"0":["variables.uploadedDocument"]}' \
  -F 0=@./id-card.pdf

This calls UploadAccountDocument; valid documentType values are listed in the DocumentType enum.

Multiple files

For an argument like documents: [UploadDocument!]!, reference each file by its array index:

{
  "0": ["variables.documents.0"],
  "1": ["variables.documents.1"]
}

The same file part can be reused by listing several paths in its array.

Uploads inside a form answer

Configurable forms accept files through FormAnswerInput:

input FormAnswerInput {
  formQuestionId: ID!
  value: Any
  uploadDocument: UploadDocument
  uploadDocuments: UploadDocumentsInput
}

For multi-file answers, wrap the list in UploadDocumentsInput:

input UploadDocumentsInput {
  documents: [UploadDocument]
  mergeWithFormerAnswer: Boolean!
}

mergeWithFormerAnswer: true appends to the previous answer instead of replacing it.

This shape is consumed by:

• AnswerInvestmentModalities — see the Investment Management recipe.
• AnswerKyc — see the KYC Management recipe.

Mutations that accept uploads

Mutation	Use case
UploadAccountDocument	Attach a document to an account (KYC, tax, regulatory, …)
UploadKycDocuments	Bulk-attach documents to the KYC of an account
UploadShareholderKycDocument	Documents tied to a corporate-account shareholder
UploadSubscriptionDocuments	Signed subscription pack(s) attached to an investment
UploadTransactionDocument	Document attached to a transaction (capital call, distribution, …)
UploadOperationDocument	Document attached to a security operation
UploadCompanyDocument	Document attached to a company
UploadCommunicationDocument	Investor-facing communication document
UploadPrometheePack	Promethée signed-pack import

Form-answer mutations (AnswerKyc, AnswerInvestmentModalities) accept uploads through FormAnswerInput, as described above.

Common pitfalls

• The HTTP Content-Type must be multipart/form-data; a plain JSON POST will reject the file fields.
• File-typed variables in operations must be null — the actual binding happens through map.
• Paths in map start with variables. and use dots (e.g. variables.documents.0), not bracket notation (variables.documents[0]).
• Set the file part's Content-Type to match the upload (e.g. application/pdf, image/png) when the consumer relies on MIME-type validation.

Related

• Authentication — how to obtain the JWT used by upload requests
• API endpoints — environment hosts
• Downloads — retrieve files generated by the platform
• UploadDocument — the scalar
• DocumentType — accepted document categories