Introduction
The Paravant API is organized around HTTPS endpoints with OAuth 2.0 authorization.
Base URL
https://webhook.paravantlegal.com/api
{API_BASE} in this reference means this URL. Requests operate on the account identified by the access token. Examples use fictional records; write requests affect the connected account.
Authentication
Resource requests require this header:
Authorization: Bearer <access_token>
GET https://app.paravantsystems.com/oauth/authorize
The integration uses OAuth 2.0 authorization code flow with automatic refresh. After the user grants consent, the registered callback receives a single-use authorization code and the supplied state. The code expires after 10 minutes. Zapier sends these authorization query parameters:
Parameter | Value or meaning |
| Configured integration client ID |
| Zapier's registered callback URI |
|
|
|
|
| Zapier's state value, returned with the callback |
Scopes
Scope | Use in this integration |
| Authentication test, webhook subscription management, and setup history |
| Find Client |
| Create/update clients, append notes through those actions, add documents, and link a client |
| Link an existing client to an existing docketed trademark, together with |
Exchange an authorization code
POST {API_BASE}/oauth/token
Use form encoding and OAuth client authentication in the request body (client_secret_post). The integration does not use HTTP Basic authentication for this exchange.
grant_type=authorization_code code=<authorization_code> client_id=<configured_client_id> client_secret=<configured_client_secret> redirect_uri=<registered_zapier_callback>
Example HTTP 200 response, showing the source-code default access-token lifetime:
{ "access_token": "<access_token>", "token_type": "Bearer", "expires_in": 2592000, "refresh_token": "<refresh_token>", "scope": "triggers:read clients:read clients:write trademarks:write" }The default access-token lifetime is 30 days. It is configurable by deployment; clients must use expires_in from the actual token response. Refresh tokens have no expiration by default. A deployment can configure a refresh-token lifetime, which is renewed after a successful refresh.
Refresh an access token
POST {API_BASE}/oauth/token
grant_type=refresh_token refresh_token=<stored_refresh_token> client_id=<configured_client_id> client_secret=<configured_client_secret>
HTTP 200 returns a new access token, token_type, expires_in, and scope. The provider preserves the existing refresh token across renewals and normally does not return a replacement refresh_token. The integration has automatic refresh enabled.
Errors
OAuth failures use the OAuth error format, for example:
{ "error": "invalid_grant", "error_description": "<description>" }Validation failures are HTTP 400 or 401 as determined by the OAuth provider; unexpected token-endpoint failures are HTTP 500 with error: "server_error". Expired, revoked, already-used, or otherwise invalid credentials require a valid refresh or a new connection, depending on which credential failed.
Most action/search errors use this structure:
{ "success": false, "error": "client_not_found", "message": "No client found matching the provided unique_identifier.", "details": { "unique_identifier": "crm:contact:12345" } }details is optional. Common OAuth failures have their own error/message structure: HTTP 401 invalid_token and HTTP 403 insufficient_scope. Client action/search handlers return HTTP 500 server_error for unexpected failures. Client write actions return HTTP 400 validation_error when the request body is not a valid JSON object. Subscription handlers use endpoint-specific error values; setup-history failures return HTTP 500 history_unavailable. See each operation below for its response details.
Protected resource endpoints return HTTP 401 for a missing or invalid Bearer header, or an invalid, expired, or revoked access token:
{ "error": "invalid_token", "message": "Token is invalid or expired" }Missing required scopes return HTTP 403:
{ "error": "insufficient_scope", "message": "Token lacks required scope" }HTTP 401 invokes Zapier's OAuth handling; HTTP 429 is reported as throttling and HTTP 5xx as a server error.
The webhook object
Paravant posts one JSON payload object to every active subscription matching the authenticated account's user ID and the event key. The exported Zapier trigger returns that incoming object as a one-item array to Zapier. The payload is not wrapped in an event/data envelope.
Headers sent to Zapier include:
Content-Type: application/json User-Agent: Paravant-Docketing/1.0
Callbacks use the Zapier-provided hook URL without an OAuth header or custom signature. A successful delivery confirms receipt by that endpoint, not completion of subsequent Zap steps.
The two payload structures—upon event and date based—are explained in Understand Zapier Triggers and Their Data.
Attributes
JSON field | Type and meaning |
| String or null; trademark text |
| String or null; application serial number, preserving leading zeros |
| String or null; registration number |
| Date string ( |
| String or null |
| String or null; attorney docket reference |
| URL string or null; associated document |
| Integer or null; 1 for upon-event triggers, recurring reminder sequence when available |
| Array of linked clients; empty array when none are linked |
| String or null |
| String or null |
| Object or null when all address values are absent |
| String or null within each client's address; postal codes remain text |
| URL string or null |
| Plain text / HTML string or null containing the portal link |
| Reminder-only date string ( |
| Reminder-only string or null; examples include |
The dotted paths in this table describe nested JSON objects. Zapier's declared output paths use [] for client line items and __ for nested address fields, for example paravant_clients[]address__line_1. Friendly labels such as Client - Address - Line 1 remain separate from these keys.
Example webhook body
An upon-event trigger sends this JSON object directly as the request body. Values are illustrative; unavailable values may be null.
{ "mark_identification": "EXAMPLE BRAND", "serial_number": "90987654", "registration_number": "7654321", "filing_date": "2023-01-15", "registration_date": "2023-10-20", "attorney_name": "John Doe", "domestic_representative": "Doe Legal Services", "uspto_docket_number": "LAW456", "office_action_link": null, "notification_sequence_count": 1, "paravant_clients": [ { "client_name": "Sample Corporation", "unique_identifier": "Sample-001", "contact_email": "[email protected]", "contact_phone": "+15551234567", "address": { "line_1": "123 Main Street", "line_2": null, "city": "New York", "state_province_region": "NY", "postal_code": "10001", "country": "United States" }, "portal_link": null, "portal_cta_text": null, "portal_cta_html": null } ] }A deadline reminder uses the same body and, when its triggering deadline is found, adds:
{ "due_date": "2026-11-15", "absolute_final_due_date": "2027-02-15", "absolute_final_due_date_reason": "EXTENDABLE" }
Test a connection
GET {API_BASE}/zapier/v1/auth/test
Parameters
None.
Returns
HTTP 200:
{ "authenticated": true, "userid": "<authenticated_user_id>", "email": "[email protected]", "message": "OAuth authentication successful" }email may be null. Zapier uses it as the connection label.
Subscribe to a trigger
POST {API_BASE}/zapier/v1/hooks/subscribe
Each trigger module sends its fixed event key. Trigger setup has no additional configuration fields; reminder timing is configured in Paravant. Use the exact machine key from Zapier API reference: supported trigger event keys for event. That reference lists all 65 exported keys and their exact Zapier display names.
Parameters
Field | Required | Meaning |
| Yes | Zapier-provided webhook destination; must start with |
| Yes | Exact trigger event key |
| No | Zap identity, added by integration middleware when available |
| No | Integration version, added by middleware |
| No | Zap metadata, added by middleware when available |
Request example
{ "target_url": "https://hooks.zapier.com/hooks/catch/12345/example/", "event": "examiner_assigned", "zap_id": "<zap_id_if_available>", "zapier_app_version": "<integration_version>", "zap_meta": { "id": "<zap_id_if_available>" } }
Returns
HTTP 201 means a new subscription was created:
{ "id": 123, "success": true, "message": "Subscription created successfully", "event_type": "examiner_assigned", "target_url": "https://hooks.zapier.com/hooks/catch/12345/example/", "zap_id": "<zap_id_if_available>" }Save id for unsubscribe. zap_id can be null.
Repeated subscribe requests for the same authenticated user, target URL, and event reuse the existing row and return HTTP 200. An active row returns message: "Subscription already exists"; an inactive row is reactivated and returns message: "Subscription reactivated successfully". A repeated request is not a conflict response.
Validation errors are HTTP 400 with error and message: missing JSON, missing target_url or event, or an invalid target URL. Persistence failures return HTTP 500. Common OAuth 401/403 errors also apply.
Unsubscribe from a trigger
DELETE {API_BASE}/zapier/v1/hooks/unsubscribe/{id}
Zapier calls this when the trigger subscription is removed, including when a Zap is turned off or deleted. The row is marked inactive rather than deleted. Integration middleware also includes the saved subscription data and available target URL/Zap metadata in the JSON body.
Parameters
id — required integer subscription ID returned when subscribing.
Returns
HTTP 200 response:
{ "success": true, "message": "Subscription deactivated successfully", "subscription_ids": [123] }An already-inactive matching subscription also returns HTTP 200. No match, including an ID owned by another user, returns HTTP 404 with error: "Subscription not found". Unexpected failures return HTTP 500.
Retrieve records for trigger setup
GET {API_BASE}/zapier/v1/triggers/{event_type}/poll
This endpoint serves Zapier's trigger-test/editor experience. Live triggers use webhooks, not periodic polling of this endpoint. The same route pattern serves every exported trigger, including examiner_assigned.
Parameters
event_type — required trigger key in the URL path.
There are no pagination or date-filter inputs. The endpoint reads up to the 100 most recent webhook log rows for the authenticated user and exact event type whose status is SENT, newest first. It deduplicates records using the original automation-run ID when available, otherwise the current run ID; logs without a run ID use their log ID. Because deduplication happens after the 100-row limit, fewer than 100 payloads may be returned.
Returns
HTTP 200 returns an array of payload objects matching the webhook format above. Empty history returns []. The integration substitutes that trigger's static sample only when it receives an empty array. An API failure does not intentionally become sample data. Unreadable stored history returns HTTP 500:
{ "success": false, "error": "history_unavailable", "message": "Unable to load recent events. Please try again." }