Cookbook
Hire your first contractor
Onboard a contractor as a stakeholder, send NDA + IP assignment + W-9 + contractor agreement under one envelope, capture the executed package.
Last updated
Independent-contractor agreement, IP assignment, W-9 collection, and 1099 reporting setup.
Trigger
You're bringing on an independent contractor in the US.
Call sequence
1. Add as stakeholder
POST /v1/stakeholders { kind: 'contractor', name, email, ein_or_ssn }2. Issue contractor agreement + IP assignment
POST /v1/documents { template: 'tpl_contractor_us_v2' }3. Collect W-9
POST /v1/documents { template: 'tpl_w9_v2024' }Idempotency
Stakeholder creation is idempotent on `(entity, ein_or_ssn)`.
Webhooks
| Event | Description |
|---|---|
document.signed | Both documents execute. |
Errors
| Status | Code | Description |
|---|---|---|
422 | tin_invalid | The TIN failed IRS TIN-matching. Surface for correction. |
IP assignment is non-optional. Without it, the contractor owns the work
they create — a fact that surfaces on the diligence checklist of every
acquisition and priced-round close. Matter's contractor template auto-includes
the IP assignment clause, but a separate signed IP-assignment document is
the audit-trail-clean shape. The endpoint returns
422 missing_ip_assignment_for_contractor if you try to onboard a contractor
without one — bypass with acknowledge_no_ip_assignment: true only when the
contractor's role doesn't produce IP (e.g., a payroll bookkeeper).
Pre-flight
The governance baseline must already be in place — the founder needs to be on file as an authorized officer before they can sign on behalf of the entity. See establish your governance baseline.
Three internal templates ready to use:
- Contractor agreement — your standard fee structure, scope, and termination terms.
- NDA — mutual or one-way; one-way is the default for first-hire contractors.
- IP assignment — the work-product-belongs-to-entity clause; Matter
ships a default at
matter:contractor:ip_assignment:2026-04-26.
Upload via POST /v1/documents with kind: contractor_agreement,
kind: nda, kind: ip_assignment. Or use the Matter-hosted defaults by
referencing them as template_id instead of a document_id.
US contractors → W-9. Foreign contractors → W-8BEN (individuals) or
W-8BEN-E (entities). Matter's template catalog has all three:
matter:tax_form:w9:2026-04-26,
matter:tax_form:w8ben:2026-04-26,
matter:tax_form:w8ben_e:2026-04-26.
Bundling four documents in one envelope
The four documents — contractor agreement, NDA, IP assignment, W-9 — go in
one envelope. The W-9 attaches to the contractor agreement so the
parent/child grammar is preserved (attaches_to + attachment_kind: tax_form).
# Draft the four documents (parallel-safe), then bundle them in one envelope
DOC_AGREEMENT=$(curl -s -X POST https://api.mattermode.com/v1/documents \
-H "Authorization: Bearer $MATTER_KEY" \
-H "Matter-Version: 2026-05-01" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"entity_id": "ent_Nq3KcAbc",
"kind": "contractor_agreement",
"template_id": "matter:contractor:agreement:2026-04-26",
"parties": [
{"stakeholder_id": "stk_priya_W4tJh3z", "role": "contractor"},
{"stakeholder_id": "stk_jane_F0und3r", "role": "officer", "title": "CEO"}
],
"fields": {
"scope_of_work": "Frontend engineering on the Matter dashboard (~20 hrs/week).",
"fee_structure": "USD $150/hr, invoiced bi-weekly, NET-15.",
"term_months": 12,
"termination_notice_days": 14
}
}' | jq -r '.id')
DOC_W9=$(curl -s -X POST https://api.mattermode.com/v1/documents \
-H "Authorization: Bearer $MATTER_KEY" \
-H "Matter-Version: 2026-05-01" \
-H "Idempotency-Key: $(uuidgen)" \
-d "{
\"entity_id\": \"ent_Nq3KcAbc\",
\"kind\": \"tax_form_w9\",
\"template_id\": \"matter:tax_form:w9:2026-04-26\",
\"attaches_to\": \"$DOC_AGREEMENT\",
\"attachment_kind\": \"tax_form\",
\"parties\": [{\"stakeholder_id\": \"stk_priya_W4tJh3z\", \"role\": \"taxpayer\"}]
}" | jq -r '.id')
# Bundle in one envelope, sequential — contractor signs first, founder counter-signs
curl -X POST https://api.mattermode.com/v1/signing_envelopes \
-H "Authorization: Bearer $MATTER_KEY" \
-H "Matter-Version: 2026-05-01" \
-H "Idempotency-Key: $(uuidgen)" \
-d "{
\"entity_id\": \"ent_Nq3KcAbc\",
\"subject\": \"Contractor onboarding — Priya Ramaswamy\",
\"document_ids\": [\"$DOC_AGREEMENT\", \"$DOC_NDA\", \"$DOC_IP\", \"$DOC_W9\"],
\"signers\": [
{\"stakeholder_id\": \"stk_priya_W4tJh3z\", \"order\": 1},
{\"stakeholder_id\": \"stk_jane_F0und3r\", \"order\": 2}
],
\"routing\": \"sequential\",
\"reminder_policy\": {\"interval_hours\": 72, \"max_reminders\": 3}
}"On signing_envelope.completed, Matter parses the W-9, extracts the SSN/EIN,
and stores it on Stakeholder.tax_id (vaulted, same flow as founder onboarding).
Error recovery
| Failure | Cause | Remediation |
|---|---|---|
409 Conflict stakeholder_email_exists | The contact email is already on a different stakeholder for this entity. | Confirm with the contractor whether they're already onboarded under a different name. If a duplicate, reuse the existing stakeholder_id. |
422 Unprocessable Entity missing_ip_assignment_for_contractor | Envelope didn't include an ip_assignment document. | Add one to document_ids[], or pass acknowledge_no_ip_assignment: true (not recommended; surfaces in diligence). |
422 Unprocessable Entity tax_form_kind_mismatch | A US-resident contractor was attached to a W-8BEN-E (or vice versa). Matter cross-checks tax-form kind against Stakeholder.residency. | Re-draft the tax form with the correct template_id. |
409 Conflict attaches_to_document_not_in_envelope | The W-9 attaches to a document that isn't in the envelope. | Add the parent document to document_ids[]. |
408 Request Timeout on signing_envelope | Contractor didn't sign within the envelope's expires_at. | Re-fire via POST /v1/signing_envelopes/{id}/reopen with a fresh deadline. |
Full taxonomy: errors.
Variations
For an EU/UK/Asia-based incorporated contractor (e.g., a Portuguese Sociedade Unipessoal), swap the W-9 for a W-8BEN-E:
{
"entity_id": "ent_Nq3KcAbc",
"kind": "tax_form_w8ben_e",
"template_id": "matter:tax_form:w8ben_e:2026-04-26",
"attaches_to": "doc_agreement_…",
"attachment_kind": "tax_form",
"parties": [{"stakeholder_id": "stk_studio_lisbon_lda", "role": "taxpayer"}],
"fields": {
"country_of_incorporation": "PT",
"treaty_residency": "PT",
"tax_id_type": "EIN_or_foreign_tin"
}
}Matter validates the country code against the IRS treaty-eligibility table
and surfaces treaty_withholding_rate on the executed Document. For a non-
incorporated individual contractor abroad, use template_id: matter:tax_form:w8ben:2026-04-26 instead.
Some early contractors take part of their compensation in options. After the contractor envelope lands (so the IP assignment is in place), issue the grant:
{
"entity_id": "ent_Nq3KcAbc",
"stakeholder_id": "stk_priya_W4tJh3z",
"kind": "nso",
"shares": 50000,
"vesting": {"schedule": "monthly", "months": 24, "cliff_months": 0},
"authorizing_resolution_id": "res_grant_priya_2026"
}The grant requires its own authorizing_resolution_id — chain through
run a board consent first if the equity
plan's grant-policy bylaw requires per-grant board approval.
A contractor who's a sole proprietor (not incorporated) is 1099-eligible — Matter will issue a 1099-NEC at year-end. An incorporated contractor (LLC filing as S-Corp, or a C-Corp) is not 1099-eligible; their income is reported on their own corporate return.
Set Stakeholder.tax_classification at create-time to control 1099
generation:
{
"kind": "natural_person",
"name": "Priya Ramaswamy",
"contact": {"email": "priya@example.com"},
"tax_classification": "individual_sole_proprietor",
"roles": [{"type": "contractor", "title": "Senior Frontend Engineer", "start_date": "2026-04-28"}]
}tax_classification enum: individual_sole_proprietor, single_member_llc,
s_corp, c_corp, partnership, trust_estate, other. Matter's W-9
form pre-fills this field.
For US-resident contractors who'll touch source code, layer a Confidential Information and Invention Assignment Agreement (CIIAA) on top of the IP assignment. The CIIAA binds the contractor to ongoing confidentiality obligations that survive the contract; the IP assignment binds the work product. Both are belt-and-braces but standard for venture-track companies:
{
"entity_id": "ent_Nq3KcAbc",
"kind": "ciiaa",
"template_id": "matter:contractor:ciiaa:2026-04-26",
"parties": [
{"stakeholder_id": "stk_priya_W4tJh3z", "role": "covenantor"},
{"stakeholder_id": "stk_jane_F0und3r", "role": "covenantee_officer", "title": "CEO"}
]
}Add to the same envelope's document_ids[] — five documents now flow
through one signing event.
Related
- Stakeholders endpoint — the underlying primitive
- Documents endpoint —
attaches_to + attachment_kindgrammar - Signing envelopes — multi-document, multi-party signing
- Establish your governance baseline — the prerequisite
- Onboard an advisor — different role, different equity, different tax form
- Grant employee equity — when the contractor takes options
- Sign with human — signing primitive details