"How do I get signer fields onto my document" is a central question when designing solutions for creating signature requests.
These end-points involve templates:
POST https://[api key]:@api.hellosign.com/v3/signature_request/send_with_template
POST https://[api key]:@api.hellosign.com/v3/signature_request/create_embedded_with_template
POST https://[api key]:@api.hellosign.com/v3/unclaimed_draft/create_embedded_with_template
When templates are involved you can get signer fields onto your document by dragging and dropping signer fields onto the document from the template editor.
If you drag a textbox onto the template and set it to ME (when sending) then you can use this field when sending the signature request such that you can pass a value to it programmatically via a custom_field. Details on how to do this can be found in our template walkthrough.
If your API workflow involves embedded templates which allows your users to create and edit templates on your site in an iFrame:
POST https://[api key]:@api.hellosign.com/v3/template/create_embedded_draft
For this workflow you will include merge_fields that can later be chosen as custom_fields, described above. This is explained in detail in the embedded templates section of our documentation.
NOT USING TEMPLATES
Lastly, if your signature requests do not involve templates (maybe because the underlying document changes with each signature request) then a different set of methods are available for placing signer fields onto the document. Remember that templates are used to share frequently-used documents and send them for signatures. If the document you are using changes with each signature request then you are most likely using one of these end-points:
POST https://[api key]:@api.hellosign.com/v3/signature_request/send
POST https://[api key]:@api.hellosign.com/v3/signature_request/create_embedded
POST https://[api key]:@api.hellosign.com/v3/unclaimed_draft/create
POST https://[api key]:@api.hellosign.com/v3/unclaimed_draft/create_embedded
If you're using embedded requesting, which is the POST /unclaimed_draft/create_embedded case, you can allow your user to use drag and drop to place signer fields onto the document in an iframe on your site:
or, if you're placing the fields programmatically, you can use Form Fields Per Document where you can pass X and Y coordinates of all signer fields, or you can use Text Tags, which are specifically formatted blocks of text that you place directly on the document.
We've found that Text Tags are especially useful if you're creating the document on the fly at runtime, as you can include the tags right in the creation process.
Note that if you do not include form_fields_per_document or text_tags in a /signature_request/send or a /signature_request/create_embedded call, HelloSign will automatically append a "Signatures" page to the bottom of your document, where the signers will sign. This appended page becomes part of the document.