POSTing documents

Use the following endpoints to POST documents:

POST /claim/v1/claims/{claimId}/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 metadata
content, 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 the DocumentStatusType typelist)
type (a typecode from the DocumentType typelist)

The 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 ClaimCenter.
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 ClaimCenter).

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.
ClaimCenter 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 claim cc:102 that does not yet exist in the Document Management System.

POST /claim/v1/claims/cc:102/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 claim cc:102 that does exist in the Document Management System with id "doc:11-31".

POST /claim/v1/claims/cc:102/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 ClaimCenter). 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 ClaimCenter must track.

POST /claim/v1/claims/cc:102/documents

METADATA:
{
    "data": {
        "attributes": {
            "name": "Printout of email from auto dealership",
            "status": {
                "code": "final"
            },
            "type": {
                "code": "letter_received"			
            }
        }
    }
}

CONTENTS:
<no content specified>

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.

Note: Every POST /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 a claim on an instance of ClaimCenter on your machine, enter: http://localhost:8080/cc/rest/claim/v1/claims/{claimId}/documents
On the Authorization tab, specify authorization information as appropriate.
Specify the request payload.
1. In the first row of tabs (the one that starts with Params), click Body.
2. In the row of radio buttons, select form-data.
3. On the first line, for KEY, enter: metadata
4. 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.
5. For VALUE, click the Select Files button and navigate to the JSON file containing the metadata.
6. On the second line, for KEY, enter: content
7. 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.
8. 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.