Add document recipient

POST/api/v1/documents/{ref}/recipients

Add a recipient to an editable document

Permission

An OAuth access token with this scope. How to get a token

documents:write
Copy, update, and transfer documents and recipients.

Parameters

Not sure what to enter? Here’s where to find IDs.

refpath · stringrequired
The document’s number, shown as #1234 in the ID column of your documents list and beside the title in the editor. Enter it without the #. In API responses it’s displayId.Matches ^\d+$.
client_idquery · stringrequired
The Client ID of your OAuth client. It’s public, and goes on every request alongside your access token. Find it in QuoteCloud under Settings → API dashboard → Manage Integrations → OAuth Clients.Length at least 1.

Request body

Sent as application/json.

contactIdstring
firstNamestring
lastNamestring
emailstring (email)
phonestring
mobilestring
jobTitlestring
companystring
addressstring
accountRefstring
rolestring
One of primary, to, toRecipient, cc, ccRecipient, bcc, bccRecipient.
notifyWhenOpenedvaries
Boolean coercion accepted by the v1 compatibility routes.
Fields

Exactly one of these:

Option 1boolean
Option 2number
One of 0, 1.
Option 3string
One of true, false, 1, 0, yes, no, y, n.
customFieldsobject
Fields
^custom(?:f|F)ield\d+$keys matching · any

Responses

200Recipient added.
dataobject or nullrequired
Fields
idstringrequired
recipientRefstringrequired
contactIdstring or nullrequired
firstNamestringrequired
lastNamestringrequired
emailstringrequired
phonestringrequired
mobilestringrequired
jobTitlestringrequired
companystringrequired
addressstringrequired
accountRefstringrequired
rolestringrequired
One of primary, toRecipient, ccRecipient, bccRecipient.
notifyWhenOpenedbooleanrequired
400Invalid request or validation failure.
dataobjectrequired
Fields
statusstringrequired
Always error.
messagestringrequired
codestring
documentRefstring
assetGenerationIdstring
errorsarray of object
Item fields
fieldstringrequired
messagestringrequired
401Missing or invalid bearer token or client ID.
errorstringrequired
error_descriptionstring
403Insufficient scope, missing add-on, usage limit, or permission denial.

Exactly one of these:

OAuthError
errorstringrequired
error_descriptionstring
ApiErrorEnvelope
dataobjectrequired
Fields
statusstringrequired
Always error.
messagestringrequired
codestring
documentRefstring
assetGenerationIdstring
errorsarray of object
Item fields
fieldstringrequired
messagestringrequired
404Requested resource was not found in the token's company.
dataobjectrequired
Fields
statusstringrequired
Always error.
messagestringrequired
codestring
documentRefstring
assetGenerationIdstring
errorsarray of object
Item fields
fieldstringrequired
messagestringrequired
409Request conflicts with resource state or an idempotent request.
dataobjectrequired
Fields
statusstringrequired
Always error.
messagestringrequired
codestring
documentRefstring
assetGenerationIdstring
errorsarray of object
Item fields
fieldstringrequired
messagestringrequired

Rate limit

120 requests a minute per company, shared across REST, Zapier and MCP. On a 429, wait for Retry-After.