POSTing documents
Use the following endpoints to POST documents:
- POST
/account/v1/accounts/{accountId}/documents
- POST
/job/v1/jobs/{jobId}/documents
- POST
/policy/v1/policies/{policyId}/documents
- (ContactManager) POST
/contact/v1/contacts/{contactId}/documents
- In ContactManager, documents can be posted only to contacts with the "vendor" tag.
FormData objects
For most Cloud API endpoints, the request has a body with a single string of JSON text.
However, this format is not sufficiently robust for documents. When working with documents,
the caller application typically sends two sets of data: the document metadata and the
document contents. This is accomplished using FormData
objects.
FormData is an industry-standard interface that constructs an object as a set
of key/value pairs. When a caller application is constructing a POST
/documents
call, the request has a FormData object with the following
keys:
metadata
, whose value is a JSON string identifying the document metadatacontent
, whose value is the contents of the document (and whose format varies based on the document type)
Minimum creation criteria
When POSTing a document, the
metadata
JSON must include the following fields:
name
status
(a typecode from theDocumentStatusType
typelist)type
(a typecode from theDocumentType
typelist)
content
value is not required. In some use cases, it can be
omitted.Use cases for POSTing document information
There are several ways that a caller application can POST document information:
- You can POST information about a document that is not yet in the Document Management System.
- You can POST information about a document that is already in the Document Management System but is not yet known to PolicyCenter.
- You can POST information about a document that will never be in the Document Management System (such as a physical piece of paper that must be tracked by PolicyCenter).
POSTing a document that is not yet in the Document Management System
You can POST a document that is not yet in the Document Management System. In this approach:
- You provide both document content and document metadata.
- PolicyCenter adds the document to the Document Management System through its own integration point.
- The integration point is responsible for storing values created by the Document
Management System in the document metadata (such as the document's
docUID
).
The following is an example of POSTing a "Property Assessment Report.pdf" file for account pc:10 that does not yet exist in the Document Management System.
POST /account/v1/accounts/pc:10/documents
METADATA:
{
"data": {
"attributes": {
"name": "Property Assessment Report",
"status": {
"code": "draft"
},
"type": {
"code": "letter_received"
}
}
}
}
CONTENTS:
<contents of "Property Assessment Report.pdf" file>
POSTing a document that is already in the Document Management System
You can POST a document that is already in the Document Management System. In this approach:
- You must know the ID assigned to the document in the Document Management System.
- You provide document metadata only. The metadata must specify the ID from the Document
Management System in the
docUID
field. - The integration point links the new document metadata to the document in the Document Management System.
The following is an example of POSTing a "Property Assessment Report.pdf" file for account pc:10 that does exist in the Document Management System with id "doc:11-31".
POST /account/v1/accounts/pc:10/documents
METADATA:
{
"data": {
"attributes": {
"docUID": "doc:11-31",
"name": "Property Assessment Report",
"status": {
"code": "draft"
},
"type": {
"code": "letter_received"
}
}
}
}
CONTENTS:
<no content specified>
If a POST /documents
call needs to specify document metadata only, it can
be executed using a request body that is formatted as JSON (as opposed to FormData). For
more information, see Sending document metadata only using JSON.
POSTing a document that will never be in the Document Management System
You can POST information about a document that will never be in the Document Management System (such as a physical piece of paper that must be tracked by PolicyCenter). In this approach:
- You provide document metadata only.
- There is no information stored in the Document Management System.
The following is an example of POSTing a "Printout of email from auto dealership" document for claim cc:102 that is a physical piece of paper that PolicyCenter must track.
POST /account/v1/accounts/pc:10/documents
METADATA:
{
"data": {
"attributes": {
"name": "Printout of email from auto dealership",
"status": {
"code": "final"
},
"type": {
"code": "letter_received"
}
}
}
}
CONTENTS:
<no content specified>
If a POST /documents
call needs to specify document metadata only, it can
be executed using a request body that is formatted as JSON (as opposed to FormData). For
more information, see Sending document metadata only using JSON.
POSTing documents using Postman
About this task
From Postman, you can POST documents using FormData objects. When doing so, both the metadata and content must be stored in separate files referenced by the Postman call.
/documents
endpoint supports the ability to receive the
metadata as either a string or a file. However, there is a known issue with Postman which
prevents the sending of metadata as a string. When using Postman, the metadata can be sent
only as file. This is described in the following procedure. (Client applications other than
Postman may support both string and file.)Procedure
-
Identify the files needed for the FormData object. This includes:
-
A JSON file that contains the metadata. (The file extension must be .json.)
- The document file that has the content.
-
- In Postman, start a new request by clicking the + to the right of the Launchpad tab.
- Under the Untitled Request label, select POST.
-
In the Enter request URL field, enter the URL for the server and
the endpoint.
- For example, to POST a document to an account on an instance of PolicyCenter on your
machine, enter:
http://localhost:8180/pc/rest/account/v1/accounts/{accountId}/documents
- For example, to POST a document to an account on an instance of PolicyCenter on your
machine, enter:
- On the Authorization tab, specify authorization information as appropriate.
-
Specify the request payload.
- In the first row of tabs (the one that starts with Params), click Body.
- In the row of radio buttons, select form-data.
- On the first line, for KEY, enter: metadata
- Click outside of the metadata cell. Then, mouse over the right side of the cell. A drop-down list appears. Change the value from Text to File.
- For VALUE, click the Select Files button and navigate to the JSON file containing the metadata.
- On the second line, for KEY, enter: content
- Click outside of the content cell. Then, mouse over the right side of the cell. A drop-down list appears. Change the value from Text to File.
- For VALUE, click the Select Files button and navigate to the file containing the document content.
- Click Send. The response payload appears below the request payload.