POSTing documents

You can use the following to POST documents.

  • (ContactManager) /contact/v1/contacts/{contactId}/documents
    • In ContactManager, documents can be posted only to contacts with the "vendor" tag.

FormData objects

For most Cloud API resource, the request object is constructed as 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 must send 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 object must be 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)

Two approaches to POSTing documents

There are two ways that a caller application can create a document:

  1. POST both the document metadata and content to BillingCenter using a /documents endpoint. In this approach:
    • BillingCenter 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).
  2. Add the document to the Document Management System directly, and then POST the document metadata to BillingCenter. In this approach:
    • The POST /documents call must provide any required information that comes from the Document Management System in the metadata (such as the document's DocUID).

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. For example, it may be appropriate to omit content when the document is a physical piece of paper that does not exist in the Document Management System, or when the caller application has added the document to the Document Management System directly.

Examples of POSTing documents

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

  1. 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.
  2. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
  3. Under the Untitled Request label, select POST.
  4. In the Enter request URL field, enter the URL for the server and the endpoint.
  5. On the Authorization tab, specify authorization information as appropriate.
  6. 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.
  7. Click Send. The response payload appears below the request payload.