POSTing documents

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)

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 your InsuranceSuite application.
• 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 InsuranceSuite).

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:

The following is an example of POSTing a "billingerror.pdf" file in BillingCenter for account bc:10. This file does not yet exist in the document management system:

POST /billing/v1/accounts/bc:10/documents

METADATA:
{
    "data": {
        "attributes": {
            "name": "Billing error",
            "status": {
                "code": "draft"
            },
            "type": {
                "code": "billingerror"			
            }
        }
    }
}

CONTENTS:
<contents of "billingerror.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:

The following is an example of POSTing a "Property Assessment Report.pdf" file in ClaimCenter for claim cc:102. This file does exist in the document management system with id "doc:11-31":

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

Request body

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 InsuranceSuite). In this approach:

The following is an example of POSTing a "Printout of email from auto dealership" document in PolicyCenter for claim pc:10. This a physical piece of paper that PolicyCenter must track:

POST /account/v1/accounts/pc:10/documents

Request body

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.

Errors to avoid when POSTing documents

When POSTing documents, note the following guidelines:

• Sending the content FormData parameter without the metadata FormData parameter results in an error.
• Uploading documents of an unsupported MIME type results in an error.
• When working with the docUID and pendingDocUID fields, avoid the following to prevent errors:
  • Including both the docUID and the pendingDocUID in a document's metadata
  • Including the docUID property or the pendingDocUID property when including the content parameter in the post
  • Setting the dms property to true and including the pendingDocUID field
  • Setting the status to final and including the pendingDocUID field