How to upload a document with the public API

Upload a file through Swagger

Use the POST visitor document upload. The fields needed to be used:

id of the visitor → technical ID of the visitor
id of the document type → technical ID of the document created in the database. To find it, go to configuration in the UI, hover the mouse over the Edit button in the right menu of the document, and check the link displayed in the bottom left corner of the browser window. Link example: https://cnita-test.peripass.app/Configuration/DocumentType/EditModal/1 → the “1” from the link is the id of the document.

the name of the uploaded file → use the following: "attachment; filename=XXX". When writing the file name, be sure you put also the “.pdf” extension. Example: attachment; filename=4321.pdf
Choose File → select the file to upload from your machine.
Click Execute.

Upload a file with Http

It can be confusing for customers to figure out how to translate the swagger UI to an implementation at their side. Therefor it is useful to share them an example of how the underlying Http request looks like.

Example: upload a document

Below you can find an example. The customer still needs to replace:

{visitor-id} with the actual visitor id
{document-type-id} with the id of the document type
{tenant} with the name of the tenant
{api-key} with their api key
{filename-with-extension} with the filename including the file extension
- Example: cmr-0001.pdf
{mime-type-of-the-file} with the mime type of the file
- ❗ Important: the mimetype must always match the extension of the filename (see {filename-with-extension})
- Example: application/pdf
{... raw bytes of the file itself ...} with the actual content of the file they are uploading.

Example request:

CODE

POST https://restapi.peripass.app/api/v2/visitors/{visitor-id}/attachments/upload?documentType={document-type-id}&tenant={tenant}
X-API-Key: {api-key}
Content-Disposition: attachment; filename={filename-with-extension}
Content-Type: {mime-type-of-the-file}

{... raw bytes of the file itself ...}

Uploading a file (not a document)

When no documentTypeId is set in the url, the file will simply be added as an attachment without a document type.

Example request:

CODE

POST https://restapi.peripass.app/api/v2/visitors/{visitor-id}/attachments/upload?tenant={tenant}
X-API-Key: {api-key}
Content-Disposition: attachment; filename={filename-with-extension}
Content-Type: {mime-type-of-the-file}

{... raw bytes of the file itself ...}

Troubleshooting

My upload is not working?

Check for following potential issues:

Spaces in the filename are not allowed