Frequently asked questions and troubleshooting for SignBox end users and integrators. Short answers are given below; for more integration and API details, see Developer documentation.
Billing credentials are the credentials used by the platform to meter and bill your usage of SignBox (and other services such as One-Shot and Timestamp). They are separate from the credentials you use to sign documents.
To obtain billing credentials, contact your commercial contact or Operations directly. They will provide the username, password, and PIN (or the appropriate authentication method for your contract).
Yes. You can use a token generated with the create-token API call instead of sending username, password and PIN in each signing request. This is not a Bearer token or API key—it is the token returned by the create-token operation. For the exact endpoint, parameters and examples, see SignBox API (OpenAPI) and the authentication section in Get started.
You configure the graphic signature (visual appearance of the signature in the PDF) using the signature_appearance parameter in the signing request. It lets you set text, position, date format, and an optional image.
- Configuration: Use the
signature_appearanceJSON object with fields such astext,position,page,imageorb64_image, and optionallydate,timezone,reason,location. See Signature appearance for the full parameter reference and a complete example. - Adding an image: You can either (1) upload an image via the API and use its ID in the
imagefield, or (2) send the image inline as base64 in theb64_imagefield. The documentation linked above includes examples for both.
Your certificate may have two-factor authentication enabled. In that case you must generate an OTP and send it in the signing request. Your commercial contact or Operations will have provided this information when giving you the instructions to generate your certificate.
The API returns invalid OTP when the one-time password sent in the request does not match what the service expects, or is no longer valid. Typical causes:
- The OTP has expired (see next question for duration).
- The OTP was already used (OTPs are single-use).
- Typo or wrong value sent in the request (e.g. copy-paste error, wrong parameter name).
Verify that you are sending the current OTP in the correct parameter and that it has not expired or been used before.
The OTP is valid for 5 minutes. Use it as soon as it is generated to avoid expiry.
Yes. The Redis container is always required for SignBox. It is a dependency of the service. See Docker installation and Configuration overview for deployment details.
No. With SignBox, only the hash of the document (or the data required for signing) is sent to the signing service; the full document content does not need to leave your infrastructure. The signed result is returned to you (e.g. via the url_out webhook). For the exact flow, see Signing flow and Architecture.
Yes. SignBox expects your application to provide webhook URLs so the service can send you the signing result and status updates. You must set at least:
- url_out — to receive the signed document when the signature completes successfully.
- urlback — to receive status and log callbacks.
Both must be publicly reachable endpoints that accept POST requests. For details and payload formats, see Webhooks.
For more integration and API details, see Developer documentation.