Uploading your own document

A document does not have to come from a Doodocs template. When an external system has already produced the PDF — an order from 1C, a contract from a CRM, a scan — upload it and route it like any other document. The bytes travel outside the API: the server hands you a presigned form, you send the file straight to storage, confirm the upload, then create the document by file_id. All three steps are covered by the documents:write scope.

From a file to a document in flight

Step 1. Reserve the file

POST /developer/v1/files creates the record and returns the upload form.

curl -X POST -H "X-API-Key: ddp_YOUR_KEY" -H "Content-Type: application/json" \
  https://app.doodocs.kz/api/developer/v1/files \
  -d '{
    "filename": "employment-order.pdf",
    "content_type": "application/pdf",
    "size_bytes": 148392
  }'

{
  "file": {
    "id": "01a0235f-697e-7ce1-ba86-bcde95928a68",
    "filename": "employment-order.pdf",
    "content_type": "application/pdf",
    "size_bytes": 148392,
    "status": "FILE_UPLOAD_STATUS_PENDING",
    "create_time": "2026-08-21T09:30:00Z"
  },
  "upload": {
    "url": "https://storage.doodocs.kz/people-files",
    "fields": {
      "key": "…/documents/01a0235f…",
      "Content-Type": "application/pdf",
      "policy": "eyJleHBpcmF0aW9uIjoi…",
      "x-amz-signature": "9f2c…"
    },
    "expires_at": "2026-08-21T09:45:00Z"
  }
}

size_bytes is the exact byte count. The signed policy rejects an object larger than that, and _confirm compares what storage holds against what you declared.

Step 2. Send the bytes to storage

Submit the form as multipart/form-data: every entry of fields verbatim first, the file last as the file part.

curl -X POST "https://storage.doodocs.kz/people-files" \
  -F "key=…/documents/01a0235f…" \
  -F "Content-Type=application/pdf" \
  -F "policy=eyJleHBpcmF0aW9uIjoi…" \
  -F "x-amz-signature=9f2c…" \
  -F "file=@employment-order.pdf"

A successful upload is 204 with no body. Do not send X-API-Key here — the signature in the form already authorizes the request. The form is valid until expires_at; after that, reserve the file again.

Step 3. Confirm the upload

Until the upload is confirmed, the file cannot be attached to a document.

curl -X POST -H "X-API-Key: ddp_YOUR_KEY" -H "Content-Type: application/json" \
  https://app.doodocs.kz/api/developer/v1/files/01a0235f-697e-7ce1-ba86-bcde95928a68/_confirm \
  -d '{}'

{
  "file": {
    "id": "01a0235f-697e-7ce1-ba86-bcde95928a68",
    "status": "FILE_UPLOAD_STATUS_UPLOADED",
    "size_bytes": 148392
  }
}

Confirming an already confirmed file changes nothing and returns 200, so retrying after a timeout is safe.

Step 4. Create the document from the file

Pass file_id to POST /documents instead of template_id. The file becomes the document’s PDF — exactly what approvers see and signers sign.

curl -X POST -H "X-API-Key: ddp_YOUR_KEY" -H "Content-Type: application/json" \
  https://app.doodocs.kz/api/developer/v1/documents \
  -d '{
    "title": "Employment order — Qanysh Satbayev",
    "type_id": "t1…",
    "file_id": "01a0235f-697e-7ce1-ba86-bcde95928a68",
    "subject_employee_ids": ["3f2a9c7e-…"]
  }'

template_id and file_id are mutually exclusive: passing both or neither is DEVELOPER.INVALID_ARGUMENT. template_values without template_id is rejected too, rather than silently ignored.

From here the path is the usual one — route, send and sign. The key’s owner becomes the initiator, the same as when creating from a template.

Limits

What	Value
Format	`application/pdf` only
Size	up to 50 MB
Unconfirmed	at most 10 at a time per key owner
One attachment	a confirmed file attaches to exactly one document

Nothing is converted: a DOCX or an image is rejected, and the file goes to signing exactly as you sent it. Produce the PDF on your side.

The unconfirmed-upload limit counts by key owner and is shared with the web app: an integration that reserves files without confirming them also consumes that person’s quota in the interface.

Errors

`code`	When it happens
`FILE.INVALID_CONTENT_TYPE`	`content_type` is not `application/pdf`
`FILE.INVALID_SIZE`	`size_bytes` is zero, negative, or above the limit
`FILE.PENDING_LIMIT_EXCEEDED`	Too many unconfirmed uploads
`FILE_NOT_FOUND`	No such file, it belongs to another owner, or the id is not a UUID
`FILE.NOT_UPLOADED`	`_confirm` was called but the bytes never reached storage
`FILE.SIZE_MISMATCH`	The stored object is larger than declared
`FILE.INVALID_STATUS_TRANSITION`	`file_id` was passed to `POST /documents` before confirmation
`FILE.ALREADY_LINKED`	The file is already attached to another document

A document created from a file gets no number automatically — numbering is tied to templates. Pass number in POST /documents if you need one.

Getting started

Employees

Documents

Recipes

Uploading your own document

Step 1. Reserve the file

Step 2. Send the bytes to storage

Step 3. Confirm the upload

Step 4. Create the document from the file

Limits

Errors

​Step 1. Reserve the file

​Step 2. Send the bytes to storage

​Step 3. Confirm the upload

​Step 4. Create the document from the file

​Limits

​Errors

Step 1. Reserve the file

Step 2. Send the bytes to storage

Step 3. Confirm the upload

Step 4. Create the document from the file

Limits

Errors