Guides / Contracts API
Contracts API
Read contract templates and contracts, prepare a contract from a template, and send, remind, correct or void it through the Goliath developer API
About
Contracts are e-signature documents built from your organization’s templates. These operations read templates and the contracts sent from them, fill a template for a contact and freeze it READY to send, and then — from your own code — send it to its signers, remind them, correct it, complete it or void it.
Templates themselves are built in the Goliath app; through the API you can archive and restore them, and keep a one-off contract as a template.
All operations go through the developer API gateway — one endpoint, called by
operationId. If you haven’t set up a key yet, start with the
Developer API Overview.
Operations
Reading templates and contracts (READ scope)
| operationId | What it does |
|---|---|
listContractTemplates |
The organization’s templates: name, category, status (only a PUBLISHED one with a currentVersionNumber can be sent), signer roles in signing order, the records a send asks for (uses: Contact A, Contact B, Deal, Property), and how many contracts went out (sentCount) and came back signed (signedCount). Archived templates only with includeArchived. |
listContracts |
The organization’s contracts, newest first (at most 200), with status and who signed. held marks a workflow or AI employee send waiting on a blank required value — reopen it with getHeldContractDraft. |
listContactContracts |
One contact’s contracts (as Contact A or another signer), newest first, at most 50. |
listDealContracts |
One deal’s contracts, held drafts included, newest first, at most 50. |
getContract |
One contract: its values, each signer’s status (viewed, signed, declined with their reason, a deliveryProblem when their link never arrived), its revisionNumber, and short-lived PDF links (signedPdfUrl once everyone signed). READY means prepared but not sent. |
getContractSendDraft |
Step 1 of preparing a contract: a PUBLISHED template filled for one contact (optionally a deal, and contactBId for a co-seller). Returns the template version, the CRM-filled values, missingTokens, one suggested recipient per role, and the subject, message and expiry. A required value left blank needs one — never invent a price, date or address. |
getHeldContractDraft |
A held contract (a workflow or AI employee send stopped on a blank required value) reopened to fill in, in the same shape as getContractSendDraft. Prepare it with prepareContract and heldContractId set. |
Preparing a contract (WRITE scope)
| operationId | What it does |
|---|---|
previewContract |
The filled PDF a contract would be (pdfUrl, short-lived) and any values that overflow their box or cannot print. Takes what prepareContract takes as input.contract. Nothing is saved. |
previewContractMessages |
What the first signers would be sent: the signing email’s words (email) and the text (text), each null when no first signer is reached that way. Nothing is saved or sent. |
prepareContract |
Step 2: freeze a contract READY to send, with its unsigned PDF. Build input.contract from getContractSendDraft — values as { key, value } for every value to set, required blanks included, and one recipient per role with exactly one of email or phone. Pass idempotencyKey (a new UUID) and resend it unchanged on a retry, so a lost response never makes a second contract. A template published again since step 1 is refused: start over. Reaches no signer. |
Sending and managing a contract (WRITE scope)
| operationId | What it does |
|---|---|
sendContract |
Send a READY contract for signature: the first signers in signing order get their links by email or text, and it becomes SENT. expectedRevisionNumber (getContract’s revisionNumber) refuses the send if the contract was corrected since. |
remindContract |
Email a fresh link to every signer whose turn it is; their earlier links stop working. Takes expectedRevisionNumber. |
correctContract |
Correct a sent contract on the same template version, contact and deal: input.contract with the changes, a reason (emailed to the signers whose link stops working, and kept on the evidence chain), expectedRevisionNumber, expectedSignatureCount (a signature since refuses the correction) and an idempotencyKey. |
completeContract |
Retry completing a contract whose last signature is in (sealing the signed PDF), or file and email a completed contract’s signed copy to everyone again. |
issueContractSigningLink |
A working signing link for one signer whose turn it is (recipientId from getContract), returned once for you to pass on yourself. Nothing is emailed, and the emailed link keeps working; remindContract or voidContract retires both. Opening it still asks for the code emailed to the signer. Not for the key owner’s own signature — they sign in the app. |
voidContract |
Void a sent contract: every signing link stops working and the signers who were sent one are told, with your reason. It cannot be un-voided; to go on, prepare a new one. Takes expectedRevisionNumber. |
Templates (WRITE scope)
| operationId | What it does |
|---|---|
archiveContractTemplate |
Take a template out of the list and the pickers (status ARCHIVED). Contracts already sent from it are not changed, but they move to its Archived view with it — check sentCount first. A one-off PDF (sent without a template) is discarded for good instead. |
unarchiveContractTemplate |
Put an archived template back in the list and the pickers, as it was. A discarded one-off is refused. |
keepContractAsTemplate |
Keep a one-off contract as a template under a name and category, so it joins the template list and pickers. templateId is the contract’s own (from listContracts, listContactContracts or listDealContracts). One-way. |
Example
Fill a template for a contact, freeze it, then send it:
curl -X POST https://server.goliathdata.com/api/v1/call \
-H "Authorization: Bearer gsk_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{ "operationId": "getContractSendDraft", "variables": { "input": { "templateId": "TEMPLATE_ID", "contactId": "CONTACT_ID" } } }'curl -X POST https://server.goliathdata.com/api/v1/call \
-H "Authorization: Bearer gsk_YOUR_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{ "operationId": "sendContract", "variables": { "contractId": "CONTRACT_ID", "expectedRevisionNumber": 1 } }'Full variable schemas, response shapes, and worked examples for every operation are available from the discovery endpoint.