When a company goes beyond a few contracts a week, sending each one by hand from a control panel becomes a real burden. This is where an e-signature API comes in: it lets your systems create, send, and track signature requests automatically, with no employee stepping in at each stage. The HR system sends the employment contract when a hire is approved, the financing app sends the contract when it approves the application, and the sales system sends the contract when the deal closes.
In this guide we explain the concept of a signing API for developers and business decision-makers alike: what it does, what its core components are, how an integration is built step by step, what mistakes technical teams usually make, and how to test before real sending. A non-technical reader does not need to understand every detail, but will understand what to ask the team.
First: what is a signing API, and when do you need one?
Why it matters: An API is a way for your system to talk directly to the signing platform: it asks the platform to create a contract and send it, and the platform tells it what happens to it. The decision to integrate depends on the volume and frequency of your contracts, and on how closely signing is tied to other processes in your system.
How to do it right: Ask yourself: is the contract created from data that already exists in another system? Does a later action, such as disbursing financing or activating a service, depend on signing being complete? Is sending repeated in large numbers? If the answer is yes to one or more of these, the integration is worth the effort.
| Case | Control panel | API |
|---|---|---|
| Few, varied contracts | Suitable | Unnecessary |
| Recurring contracts with data from another system | Burdensome | Suitable |
| A later action that depends on signing | Needs manual follow-up | Happens automatically through notifications |
| Signing inside your app or website | Not possible | Possible |
Integration does not mean giving up the control panel. Many companies combine the two: recurring contracts are sent automatically from systems, while special or unusual contracts are sent manually from the panel after review.
Common mistake: Starting the integration before the way of working itself has become clear, so the integration is built on a process that will change in a month.
Example: A recruitment firm sent contracts from the control panel for several weeks until the contract wording and verification steps settled. It then built the integration on the stable process, so it did not need to rebuild it.
Second: the core components of any signing API
Why it matters: Although platforms differ, signing APIs share core components. Understanding them helps the technical team plan and helps the decision-maker evaluate the platform.
How to do it right: Get to know these components before writing a single line:
- Authentication: a secret key that proves the request comes from your system, kept on the server and not in the app.
- The signature request: the document, the signers and their details, the verification method, the channel, and the signing order.
- Instant notifications (webhooks): messages the platform sends to your system at each event, such as the link being opened or signing being completed.
- Querying: asking for the contract's status or downloading the final copy and the evidence record.
- Test mode: an environment in which you can try everything with no legal effect.
Common mistake: Building the integration on repeatedly polling the contract's status every minute instead of instant notifications, so the system consumes resources needlessly and is slow to learn of the event.
Example: A technical team at a financing company was asking the platform for the status of thousands of contracts every five minutes. When it switched to instant notifications, its system learned of signing completion at the moment it happened, and requests fell to what it actually needed.
Third: creating the signature request
Why it matters: The signature request is the heart of the integration. Every error in it, such as a wrong phone number, an incomplete name, or an incorrect order, reaches the signer directly without any employee seeing it.
How to do it right: Validate the signers' data in your system before sending it: the full name as on the ID, the email or phone number in a valid format, and the signer's capacity. Set the verification method suited to the contract type, the channel through which the link is sent, and the signing order if the contract has multiple parties. Store in your system the request ID that the platform returns; it is what you will tie notifications to later.
It also helps for each request to carry a reference from your own system, such as the deal number or employee number, so that you can later tie any contract to its internal record without searching. And where the platform has ready-made signing workflows that predefine the verification method, channel, and order, your system only needs to send the variable data, which reduces the chance of error and keeps contract settings consistent across all requests.
Common mistake: Sending the same request twice because of a retry after a dropped connection, so two links to one contract reach the signer.
Example: A sales system re-sent a request when no response arrived within seconds, so some customers received two invitations. When the system began first checking whether a request already existed for the same deal before resending, the duplication stopped.
Fourth: instant notifications and receiving them securely
Why it matters: Notifications are what make the integration fully automatic. When the signing-completed notification arrives, your system can disburse the financing, activate the service, or update the employee's status. But the notification address on your server is a public address, and someone may try to send it a fake notification.
How to do it right: Verify the signature of every notification you receive using the secret the platform gives you, and reject any notification whose signature does not match. Make notification handling capable of receiving the same notification more than once without repeating the action, because platforms resend if no response reaches them. Respond to the notification quickly, and then do the heavy work afterward.
- Verify the notification's signature before anything else.
- Make sure the event has not already been processed.
- Record the notification and reply with an acknowledgment of receipt.
- Carry out the action tied to the event.
- When in doubt, query the contract's status from the platform directly.
Common mistake: Disbursing money or activating a service as soon as a notification arrives without verifying its signature.
Example: A team discovered during a security review that its notification endpoint did not verify the signature, and that anyone who knew the address could send "signing completed." It added verification before launch, and closed a hole that would have cost a great deal.
Fifth: test mode before real sending
Why it matters: An integration deals with real people and binding contracts. Any development error, such as sending test contracts to real customers, may embarrass the company or create unintended obligations.
How to do it right: Build and try the whole integration in test mode, which allows creating requests and receiving notifications with no legal effect. Try all paths: full signing, the signer declining, expiry, cancelling the send, and multi-party contracts. Then move to live mode with different keys.
Common mistake: Using the live key during development "to save time," so test contracts reach real numbers.
Example: A developer at a real-estate company was testing the sending of leases and used a real customer list from the database with the live-mode key. Dozens of tenants received invitations to sign test contracts with incorrect prices, and the company had to apologize to them one by one. Afterward the team developed only with the test key and fake data, and the live key is activated only after a review signed off by the technical lead.
Sixth: ready-made SDKs
Why it matters: Writing every request from scratch takes time and raises the chance of error in details, such as building authentication and verifying notification signatures. Ready-made libraries shorten this work and apply the correct method in advance.
How to do it right: Use the official library for the language your system runs on, if available, pin a specific version of it, and update it after reading each release's notes. Wthaiq provides an API at developers.wthaiq.com with libraries for PHP, Node, and Python, and for Java/Android and iOS apps, plus instant notifications and a test mode.
Common mistake: Copying code examples from unofficial sources without understanding them, carrying over bugs or unsafe practices.
Example: A small team working in Python began by writing its requests by hand and spent two days setting up authentication and notification-signature verification. When it moved to the official library, it completed the basic integration in hours, and got rid of small errors in notification handling that it had fallen into.
Seventh: signing inside your app or website
Why it matters: Some companies do not want the customer to leave their app to sign, but want signing to take place within his own journey. This improves the experience and reduces the chance that the customer abandons the process midway.
How to do it right: Some platforms let the signing page be displayed inside your website or app, from domains you specify and prove ownership of in advance. The page sends your app a signal when signing is completed or the signer declines, so the app knows when to move to the next step. Make sure the instant notification from the server remains the source of truth, not the signal that reaches the browser alone.
Common mistake: Relying on what happens in the customer's browser to decide whether signing is complete, because the browser is an environment the user controls.
Example: A financing app displayed the signing page inside its journey and moved to the "approved" screen as soon as the completion signal arrived from the page. It then changed its logic so the screen appears to the customer at once, but disbursement does not begin until the verified notification reaches the server, combining a fast experience with a secure decision.
Eighth: security and key management
Why it matters: An API key gives its holder the ability to send contracts in your company's name. Its leak is equivalent to the leak of the company seal.
How to do it right:
- Keep the key in server environment variables, not in the code or the code repository.
- Do not put the secret key in a mobile app or a web page.
- Use different keys for test and live mode.
- Restrict the key's use to your servers' addresses if the platform allows.
- Change the key immediately if you suspect a leak.
- Give technical team members permissions suited to their roles.
Common mistake: Pushing the configuration file that holds the key to a public code repository, where automated programs look for it within minutes of its being pushed.
Example: A developer pushed a configuration file to a public repository without noticing that it contained the key. Because the team had restricted the key to its servers' addresses, no one could use it from outside them, and the key was changed within the hour.
Ninth: evidence and retention after signing is complete
Why it matters: The integration does not end when signing is completed. Your system needs the final copy and the evidence record to store in the customer's file, and you may need them in a dispute years later.
How to do it right: After the completion notification, download the final copy and the evidence record and store them with the request ID and the verification number in the customer's file. The evidence record includes the verification method, the time of signing, the document fingerprint, and the trusted timestamp, and the verification number allows consulting the public verification page.
Common mistake: Settling for recording "signed" in the system without keeping the copy and the evidence.
Example: A telecom company tied subscription contracts to its system and recorded only a "signed" status. When a customer denied his subscription a year later, it needed to extract the evidence by hand from the platform. Afterward its system downloads the final copy and the evidence record automatically after every completion notification, and stores them in the customer's file with the verification number.
Checklist for an integration project
- Had the way of working settled before the integration was built?
- Is the signers' data validated before sending?
- Does the system prevent duplicate requests on retry?
- Is the signature of every instant notification verified?
- Does notification handling tolerate the same notification arriving more than once?
- Were all paths tried in test mode?
- Are keys stored on the server, restricted, and separated between test and live mode?
- Are the final copy and the evidence record stored in the customer's file?
Frequently asked questions
Do I need a large technical team to integrate signing?
Usually not. With ready-made libraries and clear documentation, a single developer can build a basic integration and then expand as needed.
Does signing through the API have the same legal value?
Yes, since the API is a way of creating and sending the request, and the signing itself takes place by the same methods with the same evidence preserved, and the judge assesses its strength under Law No. 15 of 2004 and its Executive Regulations.
What is the difference between test mode and live mode?
Test mode is for experimentation with no legal effect, and live mode is for real, binding contracts. A different key is used for each.
Can the signing link be sent via WhatsApp from the API?
Yes, the channel can be specified in the signature request, including WhatsApp with the verification code delivered to the same number.
What if my server goes down while a notification arrives?
Platforms usually resend the notification if no response reaches them, and you can also query the contract's status directly once the server is back.
An e-signature API turns signing from a manual task into an automatic step in your systems, provided the integration is built carefully: correct data, verified notifications, comprehensive testing, and protected keys. You can start experimenting in test mode through the developer portal, or create your Wthaiq account and try sending from the control panel first.