Skip to main content

Zapier API reference: authentication and webhook triggers

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

client_id

Configured integration client ID

redirect_uri

Zapier's registered callback URI

response_type

code

scope

triggers:read clients:read clients:write trademarks:write

state

Zapier's state value, returned with the callback

Scopes

Scope

Use in this integration

triggers:read

Authentication test, webhook subscription management, and setup history

clients:read

Find Client

clients:write

Create/update clients, append notes through those actions, add documents, and link a client

trademarks:write

Link an existing client to an existing docketed trademark, together with clients:write

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

mark_identification

String or null; trademark text

serial_number

String or null; application serial number, preserving leading zeros

registration_number

String or null; registration number

filing_date, registration_date

Date string (YYYY-MM-DD) or null

attorney_name, domestic_representative

String or null

uspto_docket_number

String or null; attorney docket reference

office_action_link

URL string or null; associated document

notification_sequence_count

Integer or null; 1 for upon-event triggers, recurring reminder sequence when available

paravant_clients

Array of linked clients; empty array when none are linked

paravant_clients[].client_name, .unique_identifier

String or null

paravant_clients[].contact_email, .contact_phone

String or null

paravant_clients[].address

Object or null when all address values are absent

address.line_1, .line_2, .city, .state_province_region, .postal_code, .country

String or null within each client's address; postal codes remain text

paravant_clients[].portal_link

URL string or null

paravant_clients[].portal_cta_text, .portal_cta_html

Plain text / HTML string or null containing the portal link

due_date, absolute_final_due_date

Reminder-only date string (YYYY-MM-DD) or null; fields may be absent if no deadline is found

absolute_final_due_date_reason

Reminder-only string or null; examples include EXTENDABLE and GRACE_PERIOD

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

target_url

Yes

Zapier-provided webhook destination; must start with https://hooks.zapier.com/

event

Yes

Exact trigger event key

zap_id

No

Zap identity, added by integration middleware when available

zapier_app_version

No

Integration version, added by middleware

zap_meta

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." }
Did this answer your question?