Skip to content
Orchid CRM Docs

Contracts & E-Signatures

What this module does

Every fertility journey requires legal contracts: a surrogacy agreement between the IP and GC, an egg donation agreement, escrow agreements, and more. This module manages the full contract lifecycle: setting up templates, sending documents for e-signature, and tracking who has signed.

Business value

Legal contracts are non-negotiable in third-party reproduction. Getting them signed correctly and tracking their completion is a compliance requirement. The integration with HelloSign removes the need for manual PDF routing and physical signatures, and gives the agency a digital audit trail of all signatures.

Key files

  • Directoryorchid/
    • Directorymodels/
      • contract.py CaseContract, Contract, ContractRelationship, HelloSignParent, HelloSignTemplate, SignedContract
    • Directoryapi/
      • hellosign.py 43 KB — HelloSign API integration
    • Directoryviews/
      • contracts.py 4 KB — contract UI views
  • Directorytemplates/
    • signed_contract.html — signed contract display template

How it works

sequenceDiagram
    participant Admin as Agency Staff
    participant App as Orchid
    participant HS as HelloSign (Dropbox Sign)
    participant IP as Intended Parent
    participant GC as Gestational Carrier


    Admin->>App: Initiate contract for Case
    App->>HS: Create signature request\n(using HelloSignTemplate ID)
    HS->>IP: Email with signing link
    HS->>GC: Email with signing link
    IP->>HS: Signs document
    GC->>HS: Signs document
    HS->>App: Webhook: all parties signed
    App->>App: Create SignedContract record\nUpdate CaseContract status
    Admin->>App: View signed contract

Data model

erDiagram
    HelloSignTemplate {
        int agency_id
        string hs_template_id
        string contract_type
        string name
    }
    HelloSignParent {
        int case_id
        string hs_signature_request_id
        string status
    }
    SignedContract {
        int hello_sign_parent_id
        string s3_key
        datetime signed_at
    }
    CaseContract {
        int case_id
        string contract_type
        string status
    }
    Contract {
        int agency_id
        string name
        string contract_type
    }


    HelloSignTemplate ||--o{ HelloSignParent : "generates"
    HelloSignParent ||--o| SignedContract : "results in"
    CaseContract }|--|| Case : "for"

Setup requirements — two places to configure

Contracts require configuration in two systems simultaneously:

  1. HelloSign dashboard — Create a template in HelloSign’s web interface with signature fields placed on the document. Copy the template_id from HelloSign.

  2. Orchid — Create a HelloSignTemplate record in Orchid’s database that stores the HelloSign template_id, the contract type, and which agencies can use it.

The two are linked by hs_template_id. If the IDs don’t match, signature requests will fail silently.

The signing lifecycle

HelloSignParent.statusMeaning
'sent'Signature request created, emails sent to signers
'awaiting_signature'At least one party has not yet signed
'signed'All parties have signed
'declined'One or more parties declined to sign
'error'An API error occurred

When all parties sign, HelloSign sends a webhook to Orchid. The webhook handler (in orchid/api/hellosign.py) creates the SignedContract record and updates the CaseContract status. The signed PDF is stored in S3.

Webhooks — critical configuration

HelloSign sends webhooks to Orchid when signing events happen. The webhook URL must be configured in the HelloSign dashboard and must be reachable from the internet. In local development, webhooks will not reach localhost — use a tool like ngrok to expose a local port for testing.

ContractRelationship — linking parties

ContractRelationship records define which parties in a case need to sign which contracts. For example: IP signs, GC signs, but the attorney does not sign (they drafted it). This model maps signers to their HelloSign signer roles.

Gotchas