API reference / Documents

post/v1/applications/{id}/documents

Ask for somewhere to put a file

Operation
requestDocumentUpload
Authentication
API key

Returns a presigned URL. The bytes go straight to storage, not through this API.

The file is validated against its slot's rules before the URL is issued.

Scoped to the authenticated tenant. Keys issued to one tenant can never read or modify another tenant’s resources.

Request

Parameters

idpathrequiredstring

Body

typestringrequired

Which slot this is for, e.g. `passport_scan`. Drives the file rules.

filenamestringrequired
mime_typestringrequired
size_bytesintegerrequired

Responses

201The upload ticket.
document_idstringrequired
upload_urlstringrequired

PUT the bytes here directly. They do not pass through the API.

storage_keystringrequired
expires_atstringrequired
headersobjectrequired

Headers the storage provider requires on the PUT. Send them verbatim.

400The request body or query failed validation.
errorobjectrequired
401No key, an unknown key, a revoked key, or a key whose tenant is not active. All four return an identical body on purpose: distinguishing them would let a caller discover which partners we have.
errorobjectrequired
403The key is valid but does not hold the scope this route requires.
errorobjectrequired
404Not found, or not yours. A resource belonging to another tenant answers 404 rather than 403, because 403 would confirm the record exists.
errorobjectrequired

Example

curl
curl -X POST https://api.haavisa.com/v1/applications/<id>/documents \
  -H "Authorization: Bearer $HAAVISA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "<type>",
    "filename": "<filename>",
    "mime_type": "<mime_type>",
    "size_bytes": 0
  }'

More in Documents

Something unclear? The eligibility guide explains the model behind the answers; the errors guide covers the envelope.