API Best Practices
Concise guidance for building production integrations against the Undersign API.
Keep credentials server-side
Store API credentials in environment variables or a secrets manager on the server. Never expose them in browser JavaScript, public HTML, source repositories or mobile code. See Authentication.
Store returned identifiers
Store package_id and package_guid with your internal record so you can retrieve status and correlate the request later.
Use external_id
Use external_id to associate requests with records in your own system. See External IDs & Metadata.
Use metadata for context
Use metadata to attach additional application context that should travel with the request.
Use idempotency keys
Use idempotency keys for create operations so retries don't produce duplicates. See Idempotency.
Avoid aggressive polling
Avoid aggressive polling. Retrieve status at meaningful checkpoints and prefer webhooks for event-driven tracking. See Rate Limits.
Use webhooks where appropriate
Use webhooks to be notified when signing activity occurs instead of checking repeatedly.
Log the request_id
Log the request_id returned in every response. It's the correlation identifier for support and debugging.
Never log credentials
Never log tokens, authorization headers or API keys. Treat any log line that could contain a credential as a leak.
Make webhook processing safe to repeat
Design event processing to be idempotent so repeated notifications don't cause duplicate side effects. See Webhook Security.