US Virtual Notary - Developer's Guide

Build with US Virtual Notary. Our API and webhooks let your team create reservations, automate scheduling, and receive notarized results — securely and reliably.

API Reference Webhooks

• ⚡
  Fast integration
  RESTful API with predictable JSON responses and webhook events.
• 🔒
  Secure by default
  OAuth-style bearer tokens and signed webhook requests.
• 🔄
  End-to-end workflow
  From draft reservation to notarized document delivery.

Reservation Lifecycle

These are the exact statuses you’ll see in API responses and webhook payloads:

• draft — you create & edit the reservation (no outreach yet)
• queued — ready for outreach; we contact the customer to schedule
• pending — customer is in the scheduling flow
• scheduled — appointment is booked
• complete — notarized document is available

Draft › Queued › Pending › Scheduled › Complete

Draft

• Team creates reservation (UI or API).
• Add parties, documents, and metadata.
• No customer outreach yet.

Create Reservation (API) Model: Reservation

Tip: use webhooks to stay in sync; poll only for recovery.

Testing & Fixtures

Use the sandbox to exercise your integration end-to-end without touching production customers or documents.

Basic test flow

1. Create a draft reservation (API).
2. Update status to queued when ready for outreach.
3. USVN sends the customer a scheduling email (simulated in sandbox).
4. Customer schedules → status becomes scheduled → you receive a webhook.
5. After the session completes → status complete → you receive a webhook with document availability.

See the API Reference for the exact endpoints and the Webhooks page for payloads and headers.

Auth & headers (sandbox)

Authorization: Bearer <SANDBOX_API_KEY>
Idempotency-Key: a-unique-key-per-create
Content-Type: application/json

Time zones

Appointments are handled in the customer’s local time. Include an explicit time zone (IANA, e.g., America/New_York) wherever the API accepts a date/time. If unspecified, the sandbox may default to the workspace time zone.

Retrying & webhooks

• Webhooks are retried on network errors and 5xx responses (at-least-once delivery).
• Always verify the signature with your sandbox webhook secret and treat events as idempotent.
• You can safely replay processing by using the envelope id to dedupe.

Card testing (sandbox)

If your sandbox workflows include taking payment, use common test card numbers. Do not use real card data.

Brand	Number	Expiry / CVC	Outcome
Visa	4111 1111 1111 1111	Any future / Any 3-digit	Successful authorization
Mastercard	5555 5555 5555 4444	Any future / Any 3-digit	Successful authorization
Visa (decline)	4000 0000 0000 0002	Any future / Any 3-digit	Simulated decline
American Express	3782 822463 10005	Any future / Any 4-digit	Successful authorization
Discover	6011 0009 9013 9424	Any future / Any 3-digit	Successful authorization

Use any valid future date (e.g., 12/30) and any CVC (e.g., 123). Billing ZIP can be any 5 digits.

Common test scenarios

• Create draft → queue → customer schedules → complete.
• Reschedule flow (customer rebooks after initial schedule).
• Cancellation flow (before and after scheduling).
• Webhook retry (return a non-2xx once to observe a retry, then return 200).

Auth, Rate Limits & Reliability

Authentication

All API requests must include a Bearer token.

Authorization: Bearer <API_KEY>
Content-Type: application/json
Idempotency-Key: a-unique-key-per-create

• Where to get keys: Your USVN account manager will provision sandbox and production keys.
• Scope: Keys are tied to your workspace. Keep them server-side; never expose in client code.
• Rotation: Rotate by creating a new key, deploy, then revoke the old key.

Idempotency

To avoid duplicate objects on retries, send a unique Idempotency-Key for all POST/PUT/PATCH requests that create or mutate state.

• The same key + same request body → returns the original result.
• Different body with the same key → rejected as a conflict.
• Keep keys for at least 24 hours on your side if you generate them client-side first.

Rate limits

Planned. We will publish concrete limits and response headers once enabled.

• Design for 429 Too Many Requests handling now (see backoff below).
• Batch non-urgent operations and spread them out (jittered backoff).

Error handling & retries

• 4xx (e.g., 400/401/403/404/409): fix the request—don’t retry blindly.
• 422: validation error; inspect errors[] for fields and messages.
• 429: back off and retry with exponential backoff + jitter.
• 5xx: safe to retry (use idempotency on writes).

Recommended backoff (client-side)

// Pseudocode
base = 500ms
attempt = 1..6
delay = random(0, 1) * base * (2 ** (attempt - 1))
// e.g. ~0.5s, 1s, 2s, 4s, 8s, 16s (cap at ~20s)

Timeouts

• Client request timeout: 10–20s is typical. Prefer 20–30s for long list reads.
• If you hit timeouts on list endpoints, use pagination cursors.

Pagination

• Most list endpoints accept limit and return next_cursor when more data exists.
• Always loop until next_cursor is absent to get a complete set.

Canonical status codes we use

Code	Meaning	Your action
200/201	OK / Created	Proceed
400	Bad Request	Fix payload parameters
401/403	Unauthorized / Forbidden	Check API key/permissions
404	Not Found	Verify IDs & paths
409	Conflict (idempotency)	Reuse original response
422	Unprocessable Entity	Fix field-level errors
429	Too Many Requests	Back off & retry with jitter
5xx	Server Error	Retry (use idempotency on writes)

Error body format

{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "request_id": "req_abc123",
    "errors": [
      { "field": "customer.email", "message": "Invalid email format" }
    ]
  }
}

Need Help?

Your USVN account manager is your primary point of contact. They can connect you with our engineering team for technical questions if needed.