Contents
- Introduction
- How to prepare a document via API
- How to collect document signatures via Mifiel’s widget
- How to retrieve the signed document via API
- Email notifications sent throughout the document’s cycle
- Interactions diagram
Mifiel supports three types of documents: regular documents, encrypted documents and endorsable promissory notes. This article will focus on regular documents, which are the basis of the other two types of documents.
Before starting, you must have created a Mifiel account and generated your access tokens.
How to prepare a document via API
The preparation of any document in Mifiel must always be authenticated.
The endpoint you must use to prepare documents is /documents, and the minimum suggested parameters are:
- File that will be signed (file), it has to specify the path of a PDF file with a size of less than 20 MB.
- Stakeholders, for each one it must specify:
- Email address (email).
- Mexican tax ID “RFC” (tax_id), if you have the RFC restriction feature enabled.
- Name (name).
- Type, you can add signers (signer) or if you have the Reviewers or Automated sequences features enabled, document reviewers (reviewer).
- Stakeholder’s webhook (sign_callback_url), the URL where you can receive notifications every time someone signs the document, it’s the same for all stakeholders.
- Document’s webhook (callback_url), the URL where you will be notified once all stakeholders have signed or approved the document.
You can check our API documentation to review in detail how to do this process, find all the available parameters to prepare a document depending on your needs such as automatic reminders frequency and expiration date, and see an implementation example.
When you finish preparing the documents (if you sent the parameters correctly), you will receive a response saying that you did it successfully. It will include various data, the most relevant being:
- Stakeholder’s widget_id, it is used to sign in Mifiel’s widget and is unique for each stakeholder.
- Document’s id, it allows you to consult the document status.
How to collect document signatures via Mifiel’s widget
When the signing widget’s script (Javascript) has been added to your application, you will have to add the widget_id of the stakeholder who will be presented with the signing flow.
Remember that you can customize the colors of various signing flow elements from our user interface in mifiel.com.
How to retrieve the signed document via API
If you defined a webhook for the document, once all stakeholders have signed or approved it you will be notified about it. The notification will include relevant information of the signed document such as the URLs that will allow you to retrieve it.
To retrieve the signed document, you will have to call its endpoints. These calls to retrieve documents must be authenticated. This way you will be able to retrieve either the signed PDF (with the signatures sheet) or the XML (file with legal validity).
Email notifications sent throughout the document’s cycle
Each person who prepares or manages the document as well as its stakeholders receive various email notifications during the lifecycle of the document. These notifications are:
Email notifications for stakeholders (signers and reviewers)
- Signing invites: when you define the send_invites: true parameter when preparing the document and requesting its signatures, the stakeholders will receive an email invite. This email includes a link directing them to sign or approve the document in mifiel.com. If your signing flow is through the Mifiel widget implemented in your website, we suggest you don’t enable this notification.
- When other stakeholders sign or approve the document.
- When the document has been completely signed, attaching the PDF and the signed XML.
- Among others.
Email notifications for users who prepare or manage documents
- When stakeholders sign or approve the document.
- When the document has been completely signed, attaching the PDF and the signed XML.
- When a stakeholder rejects signing or approving the document.
- Among others.
Email notifications for document viewers
- When a document is prepared and its signatures are requested, attaching the original PDF
- When stakeholders sign or approve the document.
- When the document has been completely signed, attaching the PDF and the signed XML.
Interactions diagram
We created this diagram so that you can visualize the interactions between your application and Mifiel’s API during the document preparation and signing processes.
If you need help integrating encrypted documents or endorsable promissory notes, please contact us via chat or through your integration channel in Slack.