Documents

Create Document
Delete Document
Restore Document

Create Document

POST https://api.everisbigcontent.com/edms/rest/v1/documents

Creates a document in the Document Store. A document is formed by the metadata and the file(s).

The metadata has some system fields that are automatically managed (id, _hidden, author, dateCreated, dateModified, lastModifier, currentVersion, content and documentStore) and some fields that we can send as parameters when creating the document (description and categories).

When setting a date property, keep in mind that we accept both timestamps and date formatted strings.

The timestamp follows Unix time conventions, representing the time in milliseconds since January 1st, 1970 UTC. In case of using a string, it must adhere to the following format yyyy-MM-ddTHH:mm:ss.SSSZ. Where the T is used to separate date and time, and the Z is the zone designator for the zero UTC offset. If another offset is needed (e.g. London time), we must replace the Z by +01.

Make sure you set the correct timezone during creation or update, that is the one where the documents are created or consulted. Otherwise users may experience troubles locating documents.

The content type is automatically inferred from the file extension.

Parameters

HTTP Headers

HTTP headers allow pass additional information with the request or the response. BigContent headers are used for recurrent details like authentication or document store.

Table 1. Headers
Name	Example	Description
`Content-Type`	`multipart/form-data`	The Content-Type entity header is used to indicate the media type of the resource. In this case, it must be `multipart/form-data`
`Document-Store`	`invoice_store`	Document Store identifier
`Authorization`	`Bearer ha9r6DG4e5AQ84gferAd8EQ…`	Mandatory header of String type that authorizes you as the user with the right to execute this operation. The string is a Bearer Token returned from the operation create token
`Access-User`	john@company.com or john or 211555 or …	Optional header that allows to send an additional user identifier associated with the operation. May be required depending on specific document store configuration. The value is a free style string to identify the individual user who has sent the request.
`Transfer-Encoding`	`chunked`	Establishes if the content is sent in chunks according to rfc7230 (https://tools.ietf.org/html/rfc7230#section-4.1). Required to send files of 2048MB or larger.

Multipart body

The body’s type is multipart/form-data. It contains the two entities that compose a document, the file and the metadata.

Table 2. Body parts
Name	Example	Description
metadata	Metadata Example	It is a Json object that provides information about the document.
file	-	The file we want to store in the system. Current size limit 1GB.

Metadata JSON object must to be sent with encoding UTF-8 (RFC 7159/8.1. Character Encoding). If it is not sent in UTF-8, metadata and filename may be incorrectly stored, and even for some special cases operations may fail with error message.

Metadata Example

{
  "description" : "Invoice template",
  "categories" : [
    {
      "_name": "template",
      "Type": "invoice",
      "date": "2018-10-24T07:10:51.709Z",
      "boolean": true
    }
  ]
}

Responses

Success

Successful responses can be easily identified being always 20x (e.g. 200, 201).

Table 3. Success
Field	Value	Description
Status code	`201`	`CREATED`
`Content-Type`	`text/plain`	The Content-Type entity header is used to indicate the media type of the resource. In this case, it must be `text/plain`
Body	`qga8r5hsy9rw5weggf93lopa58`	A unique ID auto generated that identifies the document.

Error

In case of error, the response body contains a JSON object with additional information:

span-id: auto-generated identifier of the request. Please provide this when asking for support in our forum.
message: descriptive message of the error. This is aimed for developers and is specially important for Bad Request errors., where contains hints on how to fix the request.

Error messages should not be used to validate errors since they may be subject to change.

Example

{
  "span-id" : "7eb38962-2618-85f9-brte-4f15f6729590",
  "message" : "No match found for the Id"
}

Table 4. Error messages
Status code	Message	Description
400	`Malformed JSON exception (line _, col _): …`	The JSON body has a bad structure. Message points where is the problem with line and column numbers as well as what is the problem (e.g. double "{", or a missing ",", …)
400	`Malformed JSON exception (line _, col _): Invalid UTF-8 middle byte…`	The encoding used to send the object was not `UTF-8`. This error can happen due to launching a curl in git-bash. A possible solution can be seen in Code examples
400	`Category name cannot be empty or blank`	The category name is null, have blank value or was not sent
400	`Category property _ has not been defined`	The category definition with the specified name, does not have that property
400	`Category property _ is not of expected type _`	The category property type does not match the one we are sending. For example, it expects a `number` and we are sending a `String`
400	`Category property _ is mandatory`	We are not sending the value for a mandatory property
400	`Category _ not found`	No category has been found to match the `_name` specified
400	`Document cannot have duplicated categories`	The category you are trying to assign is already assigned If you want to modify it, you must delete and reassign it, or use update metadata
400	`Category property _ has value _ not found in accepted values`	The category property has a valid set of values, and the one we are sending is not valid
400	`Category property _ has an invalid date format`	The category property has a valid set of values, and the one we are sending is not valid
401	`The Token has expired on…`	Has passed more than an hour since the last create token or refresh token operation
401	`Malformed token`	The token sent is not valid
401	`Problems parsing token`	An empty token has been sent
401	`The Document-Store header must be set`	The header indicating the document store that you want to access, must be set
403	`User _ has no rights to access to the DocumentStore _`	We dont have access to that document store, or it is misspelled
404	`No match found for the Id`	The document doesn’t exists in the specified Document Store
415	`Content type _ not supported`	The Content-Type header is not correctly set
429	`Too Many Requests`	Contact with the service provider to increase your service plan.
500	`Internal server error`	If it happens consistently, please report it on our forum

Code examples

cURL
cURL + encoding
Java
Node.js

curl "https://api.everisbigcontent.com/edms/rest/v1/documents" \
-X POST \
-H 'Content-Type: multipart/form-data' \
-H "Authorization: Bearer ha9r6DG4e5AQ84gferAd8EQ..." \
-H "Document-Store: invoice_store" \
-F metadata='{"description" : "Invoice template"};type=application/json' \
-F file=@file_path

json=$(echo '{"description":"Encoding characters: á ö $ % &"};type=application/json' | iconv -f iso-8859-1 -t UTF-8)
curl "https://api.everisbigcontent.com/edms/rest/v1/documents" \
-X POST \
-H 'Content-Type: multipart/form-data' \
-H "Authorization: Bearer ha9r6DG4e5AQ84gferAd8EQ..." \
-H "Document-Store: invoice_store" \
-F metadata=json \
-F file=@file_path

import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;

String url = "https://api.everisbigcontent.com/edms/rest/v1/";
String token = "Bearer ha9r6DG4e5AQ84gferAd8EQ...";
String documentStore = "invoice_store";
File file = new File("src/main/resources/invoice.pdf");
String metadata = "{"description" : "Invoice template"}";

HttpPost post = new HttpPost(url);
post.setHeader("Authorization", token);
post.setHeader("Document-Store", documentStore);

byte[] bytes = Files.readAllBytes(file.toPath());
HttpEntity multipart = MultipartEntityBuilder.create()
        .addTextBody("metadata", metadata, ContentType.APPLICATION_JSON)
        .addBinaryBody("file", file, ContentType.DEFAULT_BINARY, "text.txt")
        .build();

post.setEntity(multipart);

CloseableHttpClient client = HttpClients.createDefault();
CloseableHttpResponse execute = client.execute(post);
HttpEntity entity = execute.getEntity();

String jsonResponse = EntityUtils.toString(entity, StandardCharsets.UTF_8);

var request = require('request');
var fs = require('fs');
var token = "ha9r6DG4e5AQ84gferAd8EQ...";
var documentStore = "invoice_store";

var formData = {
  file: {
    value:  fs.createReadStream("./resources/invoice.pdf"),
    options: {
      contentType: 'application/pdf'
    }
  },
  metadata: {
    value:  `{"description" : "Invoice template"}`,
    options: {
      contentType: 'application/json'
    }
  }
}

request.post({
  headers: {
    "Authorization": "Bearer " + token,
    "Content-Type": "multipart/form-data",
    "Document-Store": "documentStore"
  },
  url: 'https://api.everisbigcontent.com/edms/rest/v1/documents',
  formData : formData

}, function(error, response, body){
  console.log(body);
});

Delete Document

DELETE https://api.everisbigcontent.com/edms/rest/v1/documents/{ID}?type=DELETION_TYPE

Deletes a document, including all its contents and metadata from the document store. Optionally, users with administrative rights can override the document store’s default deletion policy adding the type parameter. In other words, if no type is set, the document store default value is applied.

There are 3 supported different types of deletion: metadata_flagging, metadata_deletion and physical_deletion.

Any of them can be set as the default one in the document store. Being metadata_flagging set automatically as the default value.

metadata_flagging: doesn’t actually delete any information about the document. Instead, it sets the deleted document or content as hidden, so only users with administration privileges are able to manipulate them.
Hidden documents are flagged with the _hidden property, which is only visible by administrators. Once hidden, a document or content can be easily restored by admins using the appropriate operations (restore document, restore content).
metadata_deletion: deletes only the metadata, without deleting the binary contents. The binary files will be unreachable, even for admins, but won’t be lost. If a restore is needed, make a request to the BigContent support team.
physical_deletion: deletes the whole document permanently, including both metadata and content files. Restoration WILL NOT be possible under ANY circumstances.

Parameters

HTTP Headers

HTTP headers allow pass additional information with the request or the response. BigContent headers are used for recurrent details like authentication or document store.

Table 5. Headers
Name	Example	Description
`Document-Store`	`invoice_store`	Document Store identifier
`Authorization`	`Bearer ha9r6DG4e5AQ84gferAd8EQ…`	Mandatory header of String type that authorizes you as the user with the right to execute this operation. The string is a Bearer Token returned from the operation create token
`Access-User`	john@company.com or john or 211555 or …	Optional header that allows to send an additional user identifier associated with the operation. May be required depending on specific document store configuration. The value is a free style string to identify the individual user who has sent the request.

Path

Table 6. Path
Name	Value	Detail
id	`qga8r5hsy9rw5weggf93lopa58`	Unique non-sequential auto-generated identifier of the document

Query Parameters

Table 7. Query Parameters
Name	Value	Detail
`type`	`metadata_flagging,` `metadata_deletion,` `physical_deletion`	Type of deletion to be applied. Overrides the type defined in the document store configuration

Table 8. Deletion type
Type	Explanation
`metadata_flagging`	The document `_hidden` field is set to true. After that, only users with administrative rights will be able to access the document.
`metadata_deletion`	All the metadata of the document is permanently deleted. Only the binary files will be preserved. (If a restore is needed, make a request to the BigContent support team)
`physical_deletion`	The whole document is permanently deleted, including both metadata and binary files. Restoration will not be possible under ANY circumstances.

Responses

Success

Successful responses can be easily identified being always 20x (e.g. 200, 201).

Table 9. Success
Field	Example	Description
Status code	`204`	`NO CONTENT`

Error

In case of error, the response body contains a JSON object with additional information:

span-id: auto-generated identifier of the request. Please provide this when asking for support in our forum.
message: descriptive message of the error. This is aimed for developers and is specially important for Bad Request errors., where contains hints on how to fix the request.

Error messages should not be used to validate errors since they may be subject to change.

Example

{
  "span-id" : "7eb38962-2618-85f9-brte-4f15f6729590",
  "message" : "No match found for the Id"
}

Table 10. Error messages
Status code	Message	Description
400	`Deletion type _ is not valid`	You have sent a deletion type different from `metadata_flagging`, `metadata_deletion` or `physical_deletion`
401	`The Token has expired on…`	Has passed more than an hour since the last create token or refresh token operation
401	`Malformed token`	The token sent is not valid
401	`Problems parsing token`	An empty token has been sent
401	`The Document-Store header must be set`	The header indicating the document store that you want to access, must be set
403	`User _ has no rights to access to the DocumentStore _`	We dont have access to that document store, or it is misspelled
403	`Admin privileges required to perform physical deletion`	Physical deletion is an operation reserved for admins.
404	`No match found for the Id`	The document doesn’t exists in the specified Document Store
500	`Internal server error`	If it happens consistently, please report it on our forum

Code examples

cURL
Java
Node.js

$ curl "https://api.everisbigcontent.com/edms/rest/v1/documents/qga8r5hsy9rw5weggf93lopa58?type=metadata_flagging" \
-X DELETE \
-H "Authorization: Bearer ha9r6DG4e5AQ84gferAd8EQ..." \
-H "Document-Store: invoice_store"

import org.apache.http.HttpEntity;
import org.apache.http.client.methods.*;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;

String url = "https://api.everisbigcontent.com/edms/rest/v1/documents/qga8r5hsy9rw5weggf93lopa58?type=metadata_flagging";
String token = "Bearer ha9r6DG4e5AQ84gferAd8EQ...";
String documentStore = "invoice_store";

HttpDelete delete = new HttpDelete(url);
delete.setHeader("Authorization", token);
delete.setHeader("Document-Store", documentStore);

CloseableHttpClient client = HttpClients.createDefault();
CloseableHttpResponse execute = client.execute(delete);
HttpEntity entity = execute.getEntity();

var request = require('request');
var token = "ha9r6DG4e5AQ84gferAd8EQ...";
var documentStore = "invoice_store";

request.delete({
  headers: {
    'Authorization': 'Bearer ' + token,
    'Document-Store': documentStore
  },
  url: 'https://int-api.everisbigcontent.com/edms/rest/v1/documents/qga8r5hsy9rw5weggf93lopa58?type=metadata_flagging'
}, function (error, response, body) {
});

Restore Document

PUT https://api.everisbigcontent.com/edms/rest/v1/metadata/{ID}

Restores the specified document if it is hidden.

Only user with admin privileges can perform this operation

Parameters

HTTP Headers

HTTP headers allow pass additional information with the request or the response. BigContent headers are used for recurrent details like authentication or document store.

Table 11. Headers
Name	Example	Description
`Document-Store`	`invoice_store`	Document Store identifier
`Authorization`	`Bearer ha9r6DG4e5AQ84gferAd8EQ…`	Mandatory header of String type that authorizes you as the user with the right to execute this operation. The string is a Bearer Token returned from the operation create token
`Access-User`	john@company.com or john or 211555 or …	Optional header that allows to send an additional user identifier associated with the operation. May be required depending on specific document store configuration. The value is a free style string to identify the individual user who has sent the request.
`Content-Type`	`application/json`	The Content-Type entity header is used to indicate the media type of the resource. In this case, it must be `application/json`

Path

Table 12. Path
Name	Value	Detail
id	`qga8r5hsy9rw5weggf93lopa58`	Unique non-sequential auto-generated identifier of the document

Body

As indicated by headers, the body of the http request must be a JSON.

Restore Example

{
  "_hidden" : false
}

Responses

Success

Successful responses can be easily identified being always 20x (e.g. 200, 201).

Table 13. Success
Field	Example	Description
Status code	`204`	`NO CONTENT`

Error

In case of error, the response body contains a JSON object with additional information:

span-id: auto-generated identifier of the request. Please provide this when asking for support in our forum.
message: descriptive message of the error. This is aimed for developers and is specially important for Bad Request errors., where contains hints on how to fix the request.

Error messages should not be used to validate errors since they may be subject to change.

Example

{
  "span-id" : "7eb38962-2618-85f9-brte-4f15f6729590",
  "message" : "No match found for the Id"
}

Table 14. Error messages
Status code	Message	Description
400	`Malformed JSON exception (line _, col _): …`	The JSON body has a bad structure. Message points where is the problem with line and column numbers as well as what is the problem (e.g. double "{", or a missing ",", …)
401	`The Token has expired on…`	Has passed more than an hour since the last create token or refresh token operation
401	`Malformed token`	The token sent is not valid
401	`Problems parsing token`	An empty token has been sent
401	`The Document-Store header must be set`	The header indicating the document store that you want to access, must be set
403	`User _ has no rights to access to the DocumentStore _`	We dont have access to that document store, or it is misspelled
404	`No match found for the Id`	The document doesn’t exists in the specified Document Store
415	`Content type _ not supported`	The Content-Type header is not correctly set
500	`Internal server error`	If it happens consistently, please report it on our forum

Code examples

cURL
Java
Node.js

curl "https://api.everisbigcontent.com/edms/rest/v1/metadata/qga8r5hsy9rw5weggf93lopa58" \
-X PUT \
-H "Authorization: Bearer ha9r6DG4e5AQ84gferAd8EQ..." \
-H "Document-Store: invoice_store" \
-H 'Content-Type: application/json' \
-d '{"_hidden" : false}'

import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpPut;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;

String url = "https://api.everisbigcontent.com/edms/rest/v1/metadata/qga8r5hsy9rw5weggf93lopa58";
String token = "Bearer ha9r6DG4e5AQ84gferAd8EQ...";
String documentStore = "invoice_store";

HttpPut put = new HttpPut(url);
put.setHeader("Authorization", token);
put.setHeader("Document-Store", documentStore);

StringEntity json = new StringEntity("{\"_hidden\": false}");
json.setContentType(ContentType.APPLICATION_JSON.toString());

put.setEntity(json);

CloseableHttpClient client = HttpClients.createDefault();
CloseableHttpResponse execute = client.execute(put);
HttpEntity entity = execute.getEntity();

var request = require('request');
var token = "Bearer ha9r6DG4e5AQ84gferAd8EQ...";
var documentStore = "invoice_store";

request.put({
    headers: {
      "Authorization": token,
      "Document-Store": documentStore
    },
    url: "https://api.everisbigcontent.com/edms/rest/v1/metadata/qga8r5hsy9rw5weggf93lopa58",
    json : {"_hidden" : false}
  }, function(error, response, body){
  console.log(body);
});