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
statusis one ofunsigned,signed-user(the member signed, an admin signature is still pending),completeorexpired. Statuses are lowercase.
Step 1: Create a contract template
contractHash, a fingerprint of the content. When you edit the content materially, regenerate it with PATCH /api/v1/contracts/{id}/ask-resign (step 6).
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
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:
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: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: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:- 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
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: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
user, contact, isLocked, contract.unit, exists[canceledBy], and order[dateSignature], order[dateValidityEnd], order[status].
A member’s own contracts
displayInProfile that belong to their groups, without duplicates.
Common gotchas
Placeholders appear literally in the signed PDF
Placeholders appear literally in the signed PDF
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.
Deleting a contract is refused with 403
Deleting a contract is refused with 403
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.The signed PDF is missing the admin signature
The signed PDF is missing the admin signature
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.Can I attach annexes or riders?
Can I attach annexes or riders?
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
- Onboard a new member: pair contract assignment with an approved application
- Handle webhooks:
contract_user.updatedfires when a signature is recorded - Manage local centers and permissions: scoping contracts per local center

