How to upload a document?

We will cover the upload a new document endpoint in detail. It allows you to upload any kind of document (pdf, image, etc...) to your api's storage.
Then you can use it in other endpoints of the API, in your own website or anywhere else.

Upload a new Document of type file
base url
https://api.particeep.com/v1/document/{owner_id}/upload
method
POST

Step 1 - Upload a document

To upload a document you will need to link it to a User : its owner. In this tutorial we will be using the administrator of the test environment. His id is bf5788e8-9756-4d18-8b0f-100d7fba17a2. We need it in the url.
In a real application you should use the id of the connected User or the id of your administrator.

Then we need a file to upload, we will use the Particeep's logo. Save the file locally to allow your code to acces it

You can upload any number of file, we only add a restriction on the file's size : it must be 12Mo or less

Finally the code : 


		
	public static void uploadDocument() {
		String url = "https://test-api.particeep.com/v1/document/bf5788e8-9756-4d18-8b0f-100d7fba17a2/upload";
		String apiKey = "d6a53e1a-fc8e-4251-9dda-fabbce5f2a2c";
		String apiSecret = "9bb3c122-0272-4bed-a632-19d5d52c7b5e";

		String dateTime = buildDateHeader();
		Map headers = new HashMap();
		headers.put("DateTime", dateTime);
		headers.put("Authorization", buildAuthorizationHeaderSafe(apiKey, apiSecret, dateTime));

		HttpResponse rez = WS.url(url)
				.headers(headers)
				.files(new WS.FileParam(new File("/path/to/file/logo.png"), "document"))
				.post();

		System.out.println("status: " + rez.getStatus());
		System.out.println("json:" + rez.getString());
	}

We are using functions from the previous tutorial to handle security and web requests.
The main point is to send a file in the request body as a form parameter named `document`. Your code need to act like it is submitting a file in a form. 


			<form action="https://test-api.particeep.com/v1/document/bf5788e8-9756-4d18-8b0f-100d7fba17a2/upload" method="POST">
		<input type="file" name="document">
	</form>

You should get the following json as a result (or something similar as id are generated) 


		{
	"id": "0ced192a-4d86-48fb-9fdf-3cc98c26aff1",
	"created_at": "2017-06-08T13:15:25Z",
	"owner_id": "bf5788e8-9756-4d18-8b0f-100d7fba17a2",
	"name": "logo.png",
	"content_type": "image/png",
	"path": "/",
	"doc_type": "FILE",
	"locked": false,
	"permalink": "https://test-api.particeep.com/document/0ced192a-4d86-48fb-9fdf-3cc98c26aff1"
}

You can add some meta-data on your file while uploading it, like a description. You can also change default values like the file's name.
You can find the detail of every parameters in the api documentation. 


		
	Map parameters = new HashMap();
	parameters.put("name", "logo_particeep");
	parameters.put("description", "a test file");

	HttpResponse rez = WS.url(url)
			.headers(headers)
			.files(new WS.FileParam(new File("/Users/adrien/Downloads/13487.png"), "document"))
			.params(parameters)
			.post();

You can see that the name has changed and our description is saved.


		{
	"id": "e34767cd-6f26-4c42-99ea-99363efa6d99",
	"created_at": "2017-06-08T13:43:51Z",
	"owner_id": "bf5788e8-9756-4d18-8b0f-100d7fba17a2",
	"name": "logo_particeep",
	"description": "a test file",
	"content_type": "image/png",
	"path": "/",
	"doc_type": "FILE",
	"locked": false,
	"permalink": "https://local.particeep.com:9100/document/e34767cd-6f26-4c42-99ea-99363efa6d99"
}

Step 2 - Permalink and security

Once uploaded, you can access your file via 2 ways:

It is your responsibility to choose how you share your documents. Be careful as permalinks can be accessed by anybody.

Step 3 - Common use case

We covered only the very basics of the document management in Particeep's API. We will list some examples of how our users are using the document's upload.
If you want to go further you can follow our tutorial on How to generate PDF document

Request a test key Dive deeper in documentation Follow the next tutorial