---
title: "How to integrate Mifiel's e-signature API: frequently asked questions"
description: "Get answers about Mifiel's electronic signature API: how to create documents, embed the signing widget, use webhooks, and test in the sandbox."
---
[Skip to content](https://guia.mifiel.com/en/electronic-signature-api#main-content)
- [English](https://guia.mifiel.com/en/electronic-signature-api)
- [Español](https://guia.mifiel.com/es/integrar-api-firma-electronica)
English
Show submenu for translations
[](https://www.mifiel.com/en/)
Open main navigation
Close main navigation
- - [English](https://guia.mifiel.com/en/electronic-signature-api)
- [Español](https://guia.mifiel.com/es/integrar-api-firma-electronica)
English
Show submenu for translations
Hi! How can we help you?
- There are no suggestions because the search field is empty.
1. [Frequently Asked Questions](https://guia.mifiel.com/en?hsLang=en)
2. [API integration](https://guia.mifiel.com/en/api-integration?hsLang=en)
3. [General](https://guia.mifiel.com/en/api-integration?hsLang=en#general)
# How to integrate Mifiel's e-signature API: frequently asked questions
## If you're evaluating or integrating Mifiel's API, you'll find answers to the most common questions here: what you can automate, how to create documents, display the signing widget, receive webhooks, and move to production.
**Contents**
1. [Getting started](https://guia.mifiel.com/en/electronic-signature-api#getting-started)
2. [Integration](https://guia.mifiel.com/en/electronic-signature-api#integration)
3. [Signing](https://guia.mifiel.com/en/electronic-signature-api#signing)
4. [Webhooks and the signed document](https://guia.mifiel.com/en/electronic-signature-api#webhooks)
5. [Searches and cleanup](https://guia.mifiel.com/en/electronic-signature-api#searches)
6. [Sandbox and production](https://guia.mifiel.com/en/electronic-signature-api#sandbox-and-production)
---
### Getting started
#### Does Mifiel have an electronic signature API?
Yes. Mifiel has a REST API that lets your system prepare documents, collect signatures, and retrieve signed documents without manual work. The full documentation is at [docs.mifiel.com](https://docs.mifiel.com/en/).
#### What can I do with the API?
With Mifiel's API you can:
- Automate the preparation and sending of documents for signature.
- Receive notifications of signature events through webhooks.
- Run advanced searches on your documents pending signature.
- Delete documents.
- Embed a signing widget on your website.
- Generate NOM-151 Certificates of Data Preservation for documents that don't need a signature.
#### How long does it take to integrate the API?
It can take anywhere from a few weeks to several months. There's no average time, because it depends on how complex your system is and on how you design the integration between your system and Mifiel's.
Define how you want the integration to work before you write any code. If you start programming without a clear design, you'll have to change or rewrite the code constantly, and the finished integration will take longer.
#### Do you have libraries for the API?
Yes. There are libraries for PHP, Ruby, Java, Python, Node.js, and C# (.NET) in the [Mifiel GitHub repository](https://github.com/Mifiel). Using them is optional.
#### Do you have code examples?
Yes. This guide includes examples in Ruby, Node.js, Python, PHP, C#, and cURL for creating and deleting documents. The [API documentation](https://docs.mifiel.com/en/) includes request and response examples for each endpoint.
---
### Integration
#### What are the steps to integrate the API?
There are five steps:
1. **Register your webhooks.** Webhooks tell your system what happens with your documents. You configure them once per account, not per document: with a `POST` request you provide your server URL and the event you want to subscribe to.
2. **Generate your document as a PDF.** You can use a library in your programming language to create or convert documents to PDF. The API also lets you use HTML templates; if you're interested, write to us through Mifiel's chat.
3. **Send the document to Mifiel through the API.** Make a `POST` request with the PDF and the signers' details, such as their email address.
4. **Present the signing flow to your signer.** To have them sign on your site, use Mifiel's signing widget: an interface where the signer reviews the document and signs it. You add it by inserting a script on your page, which loads an iframe.
5. **Get the signed document.** When you receive the notification that the document was closed, make an authenticated call to `GET /api/v1/documents/{id}/zip` to download a .zip with the PDF and the XML of the signed document.
#### How do I create a document?
With a `POST /api/v1/documents` request that includes the PDF and the details of each signer. The PDF can be up to 20 MB.
These examples create a document with two signers:
In the **Request** tab you'll see the request body for a document with a single signer. The response includes the document `id` and a `widget_id` for each signer: if you have three signers, you receive three `widget_id` values.
You'll find all the parameters in the [documentation for creating documents](https://docs.mifiel.com/en/#tag/Document/operation/CreateDocument).
#### What are widget\_id values, and why should I save them?
The `widget_id` is the unique identifier of each signer within a document, and it's what you pass to the widget so it shows the right document. Save it when you create the document: you'll need it every time you display the widget. If you don't save it, your system would end up creating a new document every time the signer reloads the page.
Pass each signer their own `widget_id`: signer 1 gets signer 1's `widget_id`, signer 2 gets signer 2's, and so on.
---
### Signing
#### Do my signers have to sign on mifiel.com or with the widget?
It depends on whether you want to embed signing on your site. Your signers can sign directly on the Mifiel platform (mifiel.com) or on your site with Mifiel's widget.
**Signing on mifiel.com.** This is a good fit if:
- You need your customers to sign their contracts and you can't build your own implementation.
- You want a simpler, lighter integration: you don't have to embed the signing process on your site, you only handle the automations.
- You want the signing experience to use your brand's colors and logo without writing code. You set this up from the platform if your account has the branding feature.
If you choose this option, create the document with `send_invites` set to `true` so Mifiel emails each signer and they can sign in Mifiel's signing portal. If your signers sign with the widget on your site, you can leave it that way and send your own emails.
**Signing with the widget.** This is a good fit if:
- Your site is a platform where your customers complete processes with your organization (not just an informational site) and you have a development team that can implement and maintain API integrations.
- You want to customize colors, text, the size of the widget, and document information.
- You want to place the signature flow anywhere on your page: the widget is implemented with a responsive iframe.
#### How do I display the signing widget on my site?
Include the widget on the page where you want the signing to happen and pass it the signer's `widget_id`. Do this after your server creates the document and receives the `widget_id` values. Installation options (a web component via CDN or npm, and versions for Angular, React, and Vue) and configuration options are in the Signing Widget section of the [API documentation](https://docs.mifiel.com/en/).
The widget shows the document to the signer and lets them sign it; the signature cryptography runs in the signer's browser. Your signers can sign with their e.firma or with Mifiel's electronic signature with identity verification.
During signing, the widget generates JavaScript events that your page can use to trigger actions. For example, if the signer types the wrong e.firma password, the widget generates an error event.
- **Error events:** you can ignore them, because Mifiel takes care of showing the errors to the signer.
- **Successful signature event:** don't ignore it. Use it to take the signer to the next step on your page.
In the current widget component, these events are called `signSuccess` and `signError`.
#### Can I modify the widget so it matches my site?
Only in part. In general you can't modify the [Mifiel widget](https://blog.mifiel.com/widget-mifiel-que-es/), because you could cause problems that invalidate the electronic signature or that affect your signers' experience.
You can make [some changes](https://guia.mifiel.com/es/personalizaci%C3%B3n-del-widget-de-mifiel?hsLang=en) so it fits your site's design, such as button colors or the size and placement of the widget.
#### Does my system have to handle my signers' private keys?
No. Because the signature happens in the widget, you don't have to worry about handling your signers' private keys or passwords.
---
### Webhooks and the signed document
#### Why use webhooks instead of checking the document status?
Because webhooks notify you of each event without your having to query the API continuously. Checking the document status at intervals, manually or automatically, becomes a problem when you scale: Mifiel limits the calls to check document status and blocks the IP that exceeds that limit, which would delay your processes.
#### How do I register a webhook?
With a `POST /api/v1/webhooks` request that specifies your server URL and the event type you subscribe to. Webhooks are configured at the account level, not per document.
The response includes the webhook `id`. Save it, because you'll need it later to look it up or delete it.
- To see your active webhooks: `GET /api/v1/webhooks`.
- To unsubscribe a webhook: `DELETE /api/v1/webhooks/{id}`.
You'll find more details in the [webhooks section of the documentation](https://docs.mifiel.com/en/#tag/Webhooks).
#### What events are there?
There are four events:
- `document_closed`: all parties signed the document and the [Certificate of Data Preservation](https://guia.mifiel.com/en/nom-151-certificate-of-data-preservation-via-api?hsLang=en) (NOM-151) was generated.
- `signer_completed`: a participant signed or approved the document.
- `signer_rejected`: a participant rejected the signature or approval of the document.
- `document_deleted`: a document was deleted.
#### How do I get a copy of the signed document?
Use the `document_closed` event: when you receive it, make an authenticated call to `GET /api/v1/documents/{id}/zip` with the document `id`. It returns a .zip with the PDF and the XML of the signed document.
Your server must respond with a success code (`2xx`). A document's signing cycle ends when you receive the webhook, download the .zip, and your server responds with `200`.
#### Do signed documents include a NOM-151 Certificate of Data Preservation?
Yes. Documents signed electronically in Mifiel include a Certificate of Data Preservation automatically. The certificate demonstrates that the document existed at a given point in time and that its content has not changed since then.
The certificate is not what makes an electronic signature valid: that validity depends on how the signature was created.
If you need certificates for documents that don't require a signature, the API has a specific endpoint (`POST /api/v1/psc/nom151`). See how to use it in the guide [NOM-151 Certificate of Data Preservation via API](https://guia.mifiel.com/en/nom-151-certificate-of-data-preservation-via-api?hsLang=en).
#### What happens if my server doesn't respond to the webhook?
Mifiel retries delivery up to 10 times, once every 10 minutes, and stops as soon as it receives a `2xx` response. This applies both if your server doesn't reply and if it replies with a code other than `2xx`.
#### How do I test my integration?
Trigger a webhook manually with `POST /api/v1/webhooks/{id}/trigger` and send the document `id` in `resource`.
With `instant: true`, the delivery happens once and immediately, instead of queuing the 10 attempts. The response includes the status, headers, and body your server returned, so you can use it to debug your endpoint.
We recommend testing your webhooks in the Sandbox before you write the rest of your integration.
---
### Searches and cleanup
#### How do I run advanced searches?
With a `POST /api/query` request. The attributes and relationships of each resource are defined, so you can use them according to what you need. For example, you can:
- Search for documents by part of their name.
- Identify all the documents that a specific signer needs to sign.
- Identify all unsigned documents so you can delete them if you no longer need them.
You'll find more examples in the guide [Cómo hacer búsquedas avanzadas utilizando la API](https://guia.mifiel.com/es/como-hacer-busquedas-avanzadas-api?hsLang=en).
#### How do I delete pending documents?
Find them with an advanced search and delete each one by its `id` with `DELETE /api/v1/documents/{id}`. You can only delete documents that aren't completed.
This is useful for documents that were left unsigned and are no longer needed, or that were uploaded with errors and you're going to replace with the correct one.
For example, this search requests all pending documents created between January 1 and July 31, 2021. The response includes the `id` of each document:
With each `id`, delete the document like this:
You'll find more details in the [documentation for deleting documents](https://docs.mifiel.com/en/#tag/Document/operation/DeleteDocument).
---
### Sandbox and production
#### How do I get started?
Mifiel has two environments: a test environment (Sandbox) and a production environment. You can start testing in the Sandbox or go straight to production.
**To test in the Sandbox:**
1. Create an account in [Mifiel's Sandbox](https://app-sandbox.mifiel.com/users/sign_up). When your account is created and confirmed, you'll be credited with 5 documents.
2. Contact us via chat (the green icon in the bottom-right corner) and request that we enable the API and the test credits. If you later need more test documents, write to us through the same chat or at ayuda@mifiel.com with your user email.
3. Generate your API keys in the [API settings](https://app-sandbox.mifiel.com/settings/access-tokens) section, under Access tokens. They are the APP\_ID and APP\_SECRET you use to authenticate your API calls.
4. Review the [API documentation](https://docs.mifiel.com/en/).
5. Register your [webhooks](https://docs.mifiel.com/en/#tag/Webhooks) in the Sandbox and test them with the manual trigger endpoint before you write the rest of your integration.
6. Optional: if you don't have an e.firma (FIEL) on hand, [generate a test one](https://pki-sandbox.mifiel.com/). Enter your correct name, RFC, and CURP, because the structure of the RFC and CURP is validated.
7. Optional: install one of the [Mifiel libraries](https://github.com/Mifiel) (PHP, Ruby, Java, Python, Node.js, or C#).
Documents signed in the Sandbox don't have the same legal validity as those signed in production, so use it only for testing.
**To go straight to production:** if you prefer to skip the Sandbox, contact us via chat and we'll help you set up your production environment.
#### How do I move to production?
When you finish your tests, or if you decided to go straight to production:
1. Create an account at [mifiel.com](https://www.mifiel.com/en/), if you don't already have one.
2. Contact us via chat to get the API feature and activate your production environment.
3. Generate your production API keys in API settings, under [Access tokens](https://app.mifiel.com/settings/access-tokens). Sandbox API keys don't work in production.
4. Register your webhooks again, pointing to your production server.
5. Change `app-sandbox.mifiel.com` to `app.mifiel.com` in all your endpoints, including the widget's.
Questions about the API? Write to us through Mifiel's chat
- [Document signing](https://guia.mifiel.com/en/document-signing?hsLang=en#main-content)
- [How to sign a document using the e.firma in Mifiel](https://guia.mifiel.com/en/document-signing?hsLang=en#how-to-sign-a-document-using-the-e-firma-in-mifiel)
- [Features of the e.firma](https://guia.mifiel.com/en/document-signing?hsLang=en#features-of-the-e-firma)
- [Common errors](https://guia.mifiel.com/en/document-signing?hsLang=en#common-errors)
- [Document preparation](https://guia.mifiel.com/en/document-preparation?hsLang=en#main-content)
- [Invite signers](https://guia.mifiel.com/en/document-preparation?hsLang=en#invite-signers)
- [Customize the characteristics of a document](https://guia.mifiel.com/en/document-preparation?hsLang=en#customize-the-characteristics-of-a-document)
- [Document management](https://guia.mifiel.com/en/document-management?hsLang=en#main-content)
- [General](https://guia.mifiel.com/en/document-management?hsLang=en#general)
- [For document managers](https://guia.mifiel.com/en/document-management?hsLang=en#for-document-managers)
- [Verifying a signed document and its signatures](https://guia.mifiel.com/en/verifying-a-signed-document-and-its-signatures?hsLang=en)
- [Private signing process of encrypted documents](https://guia.mifiel.com/en/private-signing-process-of-encrypted-documents?hsLang=en#main-content)
- [Creation of encrypted documents](https://guia.mifiel.com/en/private-signing-process-of-encrypted-documents?hsLang=en#creation-of-encrypted-documents)
- [Signing of encrypted documents](https://guia.mifiel.com/en/private-signing-process-of-encrypted-documents?hsLang=en#signing-of-encrypted-documents)
- [Set up of organizations and accounts](https://guia.mifiel.com/en/private-signing-process-of-encrypted-documents?hsLang=en#set-up-of-organizations-and-accounts)
- [API integration](https://guia.mifiel.com/en/api-integration?hsLang=en#main-content)
- [General](https://guia.mifiel.com/en/api-integration?hsLang=en#general)
- [Signing widget customizations](https://guia.mifiel.com/en/api-integration?hsLang=en#signing-widget-customizations)
- [Additional features](https://guia.mifiel.com/en/api-integration?hsLang=en#additional-features)
- [Plans and packets, billing and payment](https://guia.mifiel.com/en/plans-and-packets-billing-and-payment?hsLang=en#main-content)
- [Features](https://guia.mifiel.com/en/plans-and-packets-billing-and-payment?hsLang=en#features)
- [Pricing scheme](https://guia.mifiel.com/en/plans-and-packets-billing-and-payment?hsLang=en#pricing-scheme)
- [Purchasing process](https://guia.mifiel.com/en/plans-and-packets-billing-and-payment?hsLang=en#purchasing-process)
- [Billing process](https://guia.mifiel.com/en/plans-and-packets-billing-and-payment?hsLang=en#billing-process)
- [Checking your consumption](https://guia.mifiel.com/en/plans-and-packets-billing-and-payment?hsLang=en#checking-your-consumption)
- [Managing your e.firma and your Mifiel account](https://guia.mifiel.com/en/managing-your-e-firma-and-your-mifiel-account?hsLang=en#main-content)
- [Your Mifiel account](https://guia.mifiel.com/en/managing-your-e-firma-and-your-mifiel-account?hsLang=en#your-mifiel-account)
- [Features for signers](https://guia.mifiel.com/en/managing-your-e-firma-and-your-mifiel-account?hsLang=en#features-for-signers)
- [Your e.firma (FIEL)](https://guia.mifiel.com/en/managing-your-e-firma-and-your-mifiel-account?hsLang=en#your-e-firma-fiel)
- [Legal topics](https://guia.mifiel.com/en/legal-topics?hsLang=en#main-content)
- [Electronic signature regulations](https://guia.mifiel.com/en/legal-topics?hsLang=en#electronic-signature-regulations)
- [Common questions when transitioning to electronic signature](https://guia.mifiel.com/en/legal-topics?hsLang=en#common-questions-when-transitioning-to-electronic-signature)
- [Organization Management](https://guia.mifiel.com/en/organization-management?hsLang=en#main-content)
- [Generating an organization in Mifiel](https://guia.mifiel.com/en/organization-management?hsLang=en#generating-an-organization-in-mifiel)
- [Adding members and editing their permissions](https://guia.mifiel.com/en/organization-management?hsLang=en#adding-members-and-editing-their-permissions)
- [About Mifiel](https://guia.mifiel.com/en/about-mifiel?hsLang=en#main-content)
- [General information](https://guia.mifiel.com/en/about-mifiel?hsLang=en#general-information)
- [Signing from the app](https://guia.mifiel.com/en/signing-from-the-app?hsLang=en)
[](http://www.mifiel.com)