Skip to main content

Document Mapping

A document mapping is a mapping of text, radio, and checkbox form field names to data keys. Documents can have multiple mappings that can be split up into phases. Phases are customed named and are useful to iteratively fill in a document

Document mapping can be useful when:

  • A template document will be filled out based on dynamic data
  • A document needs to be filled in multiple phases

To use the mapper: Suppose you have a PDF with two text fields "Name" and "Address"

  1. Upload the document with form fields via the /api/v1/documents endpoint, copy the uuid returned

  2. Create a document mapping via the /api/v1/documents/templates/{uuid}/phases/{phase}/mappings endpoint. Example:

 PUT /api/v1/documents/templates/{uuid}/phases/FirstPhase/mappings
   "fieldMappings" : [
       "@type" : "TEXT_FIELD_1_TO_1",
       "fieldName" : "Name",
       "data" : "SUBSCRIBER_NAME"
       "@type" : "TEXT_FIELD_1_TO_1",
       "fieldName" : "Address",
       "data" : "SUBSCRIBER_ADDRESS"
  1. Implement the DocValueGenerator interface function generate() which returns a map of the data key to a string or boolean value.
class Example() : DocValueGenerator {
    override fun generate(): Map<String, () -> DocValue> = mapOf(
        "SUBSCRIBER_NAME" to { retrieveNameFromSomething() },
        "SUBSCRIBER_ADDRESS" to { retrieveAddressFromSomething() },
  1. Use the DocMapper mapFields() method passing in the phase and implemented generator. This will output the PdfFormFillData needed for the call the fill a document
mapFields({uuid}, FirstPhase, Example())