Skip to main content
This walkthrough covers the contract lifecycle, from a reusable template to per-member signed PDFs. It uses the Contract and ContractUser resources. Who is this for: legal-ops integrations that provision contract templates (annual member agreement, NDA, parental-consent form), assign them in bulk, or chase signatures. Creating and changing templates needs organization administrator rights. Assigning contracts to other people, marking them signed and applying the default signature need organization-wide HR rights.

Concepts

  • A Contract is a template: content, signature requirements, duration. It belongs to the organization (and optionally to a unit) and is reusable.
  • A ContractUser is one instance of a contract assigned to a specific member or contact. It carries the signature state, the placeholder values, a validity period and the signed document.
  • A placeholder like {{firstName}} is resolved when the instance is created, from the recipient’s profile and any custom fields.
  • A ContractUser’s status is one of unsigned, signed-user (the member signed, an admin signature is still pending), complete or expired. Statuses are lowercase.

Step 1: Create a contract template

The response includes contractHash, a fingerprint of the content. When you edit the content materially, regenerate it with PATCH /api/v1/contracts/{id}/ask-resign (step 6).
Useful fields: hasSignature (the member signs digitally), hasUpload (the member may upload a signed copy), hasAdminSignature (an admin co-signature is required), required, isInfiniteDuration or yearDuration and monthDuration, enableSignatureCancellation, and defaultSignature with useDefaultSignatureAsPreSigned for a stored admin signature. Signature settings are validated when you save, and an invalid combination is refused with the reason.

displayInProfile

When true, the contract appears in the profile of the members of its unit, and they can sign it themselves from their dashboard. When false, it appears only after you assign it (step 2).

Step 2: Assign the contract to a member

This creates an unsigned instance for the member. The body takes contract, user and an optional placeholderMap to override resolved values. HR rights over the member’s chapter are required to assign to someone else, and tenant isolation is enforced across all linked records. To assign to a contact who is not yet a member, to set the validity period explicitly, or to override the content (html), use the admin endpoint, which needs organization-wide HR rights:
Response (abridged):
Edit an instance later with PATCH /api/v1/contract_users/admin/{id}.

Step 3: Sign the membership contract in advance

For the organization’s membership contract (set in its fee settings), a shortcut creates, or returns, the unsigned instance for the calling member:
It is meant for a member who pre-signs during registration. If an unsigned instance already exists it is returned instead of creating a duplicate. The signature itself is recorded when the member uploads it through the media endpoints; this call only prepares the record.

Step 4: Mark a paper signature as signed

For people who signed on paper, record the contract as complete without a digital signature. One call records one contract for one person:
The record is created as complete and locked, the validity start date is used as the signature date, and the calling admin is recorded. If a signed record for the same person and contract already overlaps the period, that record is updated rather than duplicated; a disjoint period (a renewal) creates a new one. dateValidityEnd must not be before dateValidityStart. For a batch, call it once per person.

Step 5: Apply the default admin signature

For contracts that need an admin co-signature, Orgo can apply the contract’s stored default signature in one call:
This:
  • Checks the contract has a default signature and has not already been admin-signed
  • Sets the admin signature, locks the instance and records the signature date
  • Generates the signed PDF and a contract number if one is needed
  • Emails the completion notice
The default signature is stored on the contract (defaultSignature, hasDefaultSignature).

Step 6: Force re-signing after content changes

After you materially edit a contract’s content, existing unsigned instances are stale. Regenerate the hash and cancel them:
This sets a new contractHash and marks every unsigned instance as canceled (with canceledBy and dateCanceled). Signed instances are untouched. Assign the contract again to issue fresh instances with the new content.

Listing and reporting

Members with unsigned contracts

Other filters: user, contact, isLocked, contract.unit, exists[canceledBy], and order[dateSignature], order[dateValidityEnd], order[status].

A member’s own contracts

Returns the contracts the signed-in member has already signed, plus contracts marked displayInProfile that belong to their groups, without duplicates.

Common gotchas

Placeholders are resolved once, when the instance is created. If the member’s profile lacked the value then, it stays empty. Fix the profile, then re-issue the instance (or edit it with the admin endpoint). For custom-field placeholders, the field must exist and be readable.
A template with any signed (locked) instance cannot be deleted: Cannot delete contract because it has signed instances. This keeps the audit trail. Stop offering it by setting displayInProfile: false and not assigning it again.
use-default-signature needs a default signature on the contract. Without one, or when the instance is already admin-signed, the call is refused. Set the default signature on the template first.
Not as separate fields. Embed annexes in the content HTML or link to them. The signed PDF captures whatever is in content.

What to do next