Skip to main content

Zapier API reference: client actions and search

The client object

Successful action responses include success: true, warnings as an array, a result, and an operation-specific message. Create, update, link, and successful search responses include a nested client object using readable keys:

{   "Client Name": "Sample Corporation",   "Unique Identifier": "crm:contact:12345",   "Contact Email": "[email protected]",   "Contact Phone": "+14155552671",   "Address": {     "Line 1": "123 Example Street",     "Line 2": null,     "City": "Example City",     "State Province Region": "CA",     "Postal Code": "90001",     "Country": "United States"   } }

Address is null when there are no address values.

Client parameters

Create Client and Update Client use these request fields:

API field

Type

Meaning

unique_identifier

String

Required stable client identifier, unique within the authenticated user's clients

client_name

String or null

Person or organization name

contact_email

String or null

Client email

contact_phone

String or null

Phone number; use international format such as +14155552671

address_line_1

String or null

Street address

address_line_2

String or null

Suite, unit, or second line

city

String or null

City

state_province_region

String or null

State, province, or region

postal_code

String or null

Postal code

country

String or null

Country

client_note

String or null

Optional new note; at most 5,000 characters after trimming

Identifiers are trimmed but retain their case. They are matched exactly after trimming. Optional text values are trimmed, and empty strings normalize to null. Emails are trimmed and lowercased. Phone values are normalized to E.164; numbers without an international prefix use the United States as the default parsing region. An unparseable or impossible nonblank phone number on create or update produces a validation error.

For Update Client, unique_identifier selects the client and cannot be changed by this action. Only provided mutable fields are compared or written. Omitted fields remain unchanged; a provided null or empty string can clear an optional field. Do not map blank values unless clearing the stored value is intended. Zapier's handling of an unmapped field can differ from sending an explicit empty value, so inspect the action's test input.

An empty client_note is ignored. Every nonblank note appends a separate entry; notes are not replaced or deduplicated. A note can be the only change in Update Client.

Create Client

POST {API_BASE}/zapier/v1/creates/client

Scope: clients:write

Creates a new client.

Parameters

unique_identifier is required; the remaining client parameters listed above and note are optional. This action does not update or return an existing client when the identifier already exists.

Request example

{   "unique_identifier": "crm:contact:12345",   "client_name": "Sample Corporation",   "contact_email": "[email protected]",   "client_note": "Created from the CRM onboarding workflow." }

Returns

HTTP 201 response:

{   "success": true,   "warnings": [],   "result": "created",   "client_note_result": "appended",   "message": "Client created. Client note appended.",   "client": {     "Client Name": "Sample Corporation",     "Unique Identifier": "crm:contact:12345",     "Contact Email": "[email protected]",     "Contact Phone": null,     "Address": null   } }

Without a note, client_note_result is none and the message is Client created.

Errors

HTTP status / error

Meaning

400 validation_error

Missing/blank identifier, invalid JSON, invalid phone, oversized note, or another validation failure

409 client_exists

A client with that identifier already exists in this account

Update Client

POST {API_BASE}/zapier/v1/updates/client

Scope: clients:write

Parameters

Requires unique_identifier plus at least one mutable client field or a nonblank client_note. Use the shared client parameters listed above, excluding changes to the identifier.

Request example

{   "unique_identifier": "crm:contact:12345",   "contact_email": "[email protected]",   "client_note": "Contact information confirmed." }

Returns

HTTP 200 response includes:

{   "success": true,   "warnings": [],   "result": "updated",   "client_note_result": "appended",   "changed_fields": ["contact_email"],   "message": "Client updated. Client note appended.",   "client": {     "Client Name": "Sample Corporation",     "Unique Identifier": "crm:contact:12345",     "Contact Email": "[email protected]",     "Contact Phone": null,     "Address": null   } }

If normalized field values are unchanged, the response is still HTTP 200 with result: "unchanged" and changed_fields: []. A provided note is still appended, so an unchanged result can coexist with client_note_result: "appended". If no note is provided, client_note_result is none.

Errors

HTTP status / error

Meaning

400 validation_error

Missing identifier, no mutable field/note, invalid phone, oversized note, or another validation failure

404 client_not_found

No client matches the identifier in the connected account

Update Client does not create a missing client.

Find Client

GET {API_BASE}/zapier/v1/searches/client

Scope: clients:read

Parameters

Supply exactly one nonblank query parameter. The Zapier step validates this before making an API request during editor testing and live execution.

Parameter

Match

unique_identifier

Exact stable identifier after trimming

email

Exact stored email after email normalization

phone

Exact stored phone after phone normalization

Request example

GET {API_BASE}/zapier/v1/searches/client?unique_identifier=crm%3Acontact%3A12345

This is not a fuzzy, name-based, multi-field, or paginated search. If more than one record matches, the API reports ambiguity instead of choosing a record.

Returns

One match returns HTTP 200 with success: true, warnings: [], result: "found", match_method equal to the query field used, and the shared nested client object. There is no message field in the successful search handler. The Zapier adapter returns a one-item array containing result, match_method, warnings_csv, and flattened client fields.

Example successful API response:

{   "success": true,   "warnings": [],   "result": "found",   "match_method": "unique_identifier",   "client": {     "Client Name": "Sample Corporation",     "Unique Identifier": "crm:contact:12345",     "Contact Email": "[email protected]",     "Contact Phone": null,     "Address": null   } }

No match returns HTTP 200 with an empty array:

[]

A no-match result does not create a client. Shared email addresses and phone numbers can match more than one client; a stable unique identifier is preferable when available.

Errors

HTTP status / error

Meaning

400 missing_search_parameters

No nonblank supported search field supplied

400 too_many_search_parameters

More than one supplied; details.received_fields lists them

409 ambiguous_match

More than one match; details.match_method and details.count describe the result

Link Client to Trademark

POST {API_BASE}/zapier/v1/links/trademark-client

Scopes: Both trademarks:write and clients:write

Both the client and trademark case must already exist in the connected account. This operation does not docket a new trademark and does not create a client.

Parameters

client_unique_identifier — required string identifying an existing client.

serial_number — required application serial number as text, trimmed before lookup.

Request example

{   "serial_number": "88123456",   "client_unique_identifier": "crm:contact:12345" }

Returns

HTTP 200 response:

{   "success": true,   "warnings": [],   "result": "linked",   "message": "Client linked to trademark.",   "serial_number": "88123456",   "case_id": 12345,   "client": {     "Client Name": "Sample Corporation",     "Unique Identifier": "crm:contact:12345",     "Contact Email": "[email protected]",     "Contact Phone": null,     "Address": null   } }

An existing association returns HTTP 200 with result: "already_linked" and message: "Client is already linked to this trademark." It does not create a duplicate association.

Errors

HTTP status / error

Meaning

400 validation_error

Missing required field or invalid operation

404 case_not_found

No docketed case with that serial number in the connected account

404 client_not_found

No client with that identifier in the connected account

Add Document to Client Record

POST {API_BASE}/zapier/v1/creates/client-document

Scope: clients:write

Adds a file to an existing client's document record. The Zapier input File has type file; the integration sends its downloadable URL as API field file_url. This endpoint is JSON-based, not a multipart binary upload.

Parameters

API field

Required

Meaning

client_unique_identifier

Yes

Existing client's stable identifier

file_url

Yes

Reachable HTTP or HTTPS download URL

file_name

No

Display filename; Zapier labels this Document Name

Request example

{   "client_unique_identifier": "crm:contact:12345",   "file_url": "https://files.example.com/engagement-letter.pdf",   "file_name": "engagement-letter.pdf" }

Files must be non-empty, at most 104,857,600 bytes (100 MiB), and downloadable from a public HTTP/HTTPS URL. The URL must not require an interactive login. Supported extensions: csv, doc, docx, gif, htm, html, iif, jpg, jpeg, json, md, odt, pdf, png, ppt, pptx, rtf, tsv, txt, webp, xls, xlsx, and xml.

Returns

HTTP 201 response includes:

{   "success": true,   "warnings": [],   "result": "created",   "message": "Document added to client record.",   "document": {     "id": 123,     "client_id": 456,     "client_unique_identifier": "crm:contact:12345",     "original_file_name": "engagement-letter.pdf",     "mime_type": "application/pdf",     "file_size_bytes": 245760,     "uploaded_by_userid": "<authenticated_user_id>",     "created_at": "2026-10-24T12:00:00Z"   },   "client": {     "Client Name": "Sample Corporation",     "Unique Identifier": "crm:contact:12345",     "Contact Email": "[email protected]",     "Contact Phone": null,     "Address": null   } }

Errors

HTTP status / error

Meaning

400 validation_error

Missing client identifier/file URL or invalid JSON body

400 invalid_file_url

Invalid URL, unresolvable host, or nonpublic network target

400 file_download_failed

Source HTTP error, timeout/transport failure, missing redirect location, or too many redirects

400 file_too_large

Download exceeds 104,857,600 bytes; details.max_file_size_bytes supplies the limit

400 empty_file

Download contains no bytes

400 unsupported_file_type

Neither the MIME hint nor selected filename resolves to an allowed type; details.allowed_mime_types lists allowed types

404 client_not_found

No client matches the identifier

409 ambiguous_client

More than one client matches the identifier

Retries

Repeating a request that appends a note or uploads a document can create another copy.

Did this answer your question?