useContractorSignatureForm

useContractorSignatureForm(props: UseContractorSignatureFormProps): UseContractorSignatureFormResult

Headless hook for signing a contractor document — collects the document's fields plus a typed signature and consent.

Remarks

This hook implements the W-9 — the only signable contractor document the API exposes today (taxpayer_identification_form_w_9). The field surface is declared statically (form.Fields), like the other SDK form hooks: core fields are always present, while variable fields are exposed only when the API returns them (otherwise undefined) — a presence-based safety check, so a field the API drops is skipped rather than rendered as an orphan. The seven federal tax-classification checkboxes are collapsed into a single required radio group with conditional LLC-code and "Other" sub-fields, and on submit the selection is mapped back to the W-9 wire format. Pre-filled values (name, address, TIN, etc.) are editable inputs; the signing date is omitted so the API auto-fills it. A document that returns no recognized W-9 fields renders as acknowledge-only (data.hasFields is false). Consult form.fieldsMetadata for per-field required flags and select/radio options.

Example

Example

import {
  useContractorSignatureForm,
  SDKFormProvider,
  type UseContractorSignatureFormReady,
} from '@gusto/embedded-react-sdk'

function SignDocumentPage({ documentId }: { documentId: string }) {
  const signatureForm = useContractorSignatureForm({ documentId })

  if (signatureForm.isLoading) return <div>Loading...</div>

  return <SignDocumentReady signatureForm={signatureForm} />
}

function SignDocumentReady({
  signatureForm,
}: {
  signatureForm: UseContractorSignatureFormReady
}) {
  const { Fields } = signatureForm.form

  const handleSubmit = async () => {
    await signatureForm.actions.onSubmit()
  }

  return (
    <SDKFormProvider {...signatureForm.form.methods}>
      {Fields.Name ? <Fields.Name /> : null}
      {Fields.SignatureText ? <Fields.SignatureText /> : null}
      <Fields.Agree />
      <button onClick={handleSubmit}>Sign</button>
    </SDKFormProvider>
  )
}

Props

UseContractorSignatureFormProps

Props for useContractorSignatureForm.

Property	Type	Description
documentUuid	string	UUID of the contractor document to sign.
optionalFieldsToRequire?	ContractorSignatureOptionalFieldsToRequire	Promote optional W-9 fields to required (e.g. { create: ['businessName'] }).
shouldFocusError?	boolean	Auto-focus the first invalid field on submit. Defaults to true; set to false when using composeSubmitHandler.
validationMode?	"onChange" | "onBlur" | "onSubmit" | "onTouched" | "all"	When validation runs. Passed through to react-hook-form; defaults to 'onSubmit'.

Returns

UseContractorSignatureFormResult

A HookLoadingResult while loading, or a UseContractorSignatureFormReady once loaded.

UseContractorSignatureFormResult

UseContractorSignatureFormResult = HookLoadingResult | UseContractorSignatureFormReady

Result of useContractorSignatureForm — a discriminated union on isLoading.

---

UseContractorSignatureFormReady

Ready-state shape returned by useContractorSignatureForm once the document metadata has loaded.

Property	Type	Description
actions	object	Imperative actions exposed by the hook.
actions.onSubmit	() => Promise<HookSubmitResult<DocumentSigned> | undefined>	Validates the form and submits the signature. Resolves with the signed document on success, or undefined on validation or API failure.
data	object	Loaded data — the document being signed and a downloadable PDF URL.
data.document	Document	The document entity fetched from the API.
data.hasFields	boolean	Whether the document carries signable fields (vs. acknowledge-only).
data.pdfUrl	string | null	URL to the document's PDF, or null when unavailable.
errorHandling	HookErrorHandling	Error state and recovery actions.
form	object	Form bindings: pre-bound field components, per-field metadata, submission values, and react-hook-form internals.
form.Fields	ContractorSignatureFormFieldComponents	-
form.fieldsMetadata	ContractorSignatureFieldsMetadata	-
form.getFormSubmissionValues	() => ContractorSignatureFormData | undefined	-
form.hookFormInternals	HookFormInternals<ContractorSignatureFormData>	-
isLoading	false	Always false in this branch; discriminates from HookLoadingResult.
status	object	Submit-state flags.
status.isPending	boolean	true while the sign mutation is in flight.
status.mode	"create"	Always 'create'; the hook always submits as a signing operation.

Fields

ContractorSignatureFormFieldComponents

Field components exposed by useContractorSignatureForm on form.Fields.

Remarks

Every field is presence-gated against the API response and is undefined when the document didn't return its backing field — always null-check before rendering. This guards against the document API diverging (dropping or renaming a field) by skipping fields it no longer returns, mirroring the stable signing flow. Agree is the sole exception: it's a synthesized electronic-signature consent checkbox with no API field, so it's always present.

Property	Type	Description
Agree	ComponentType<AgreeFieldProps>	Electronic-signature consent checkbox; always present (synthesized, not an API field).
AccountNumber	ComponentType<AccountNumberFieldProps> | undefined	Account number(s); defined only when the API returns account_number.
BusinessName	ComponentType<BusinessNameFieldProps> | undefined	Business name; defined only when the API returns business_name.
CompanyName	ComponentType<CompanyNameFieldProps> | undefined	Requester's name and address; defined only when the API returns company_name.
Ein	ComponentType<EinFieldProps> | undefined	Employer Identification Number; defined only when the API returns ein.
ExemptionFromFatca	ComponentType<ExemptionFromFatcaFieldProps> | undefined	FATCA exemption code; defined only when the API returns exemption_from_FATCA.
ExemptPayeeCode	ComponentType<ExemptPayeeCodeFieldProps> | undefined	Exempt payee code; defined only when the API returns exempt_payee_code.
ForeignPartners	ComponentType<ForeignPartnersFieldProps> | undefined	Foreign partners checkbox; defined only when the API returns foreign_partners.
HomeAddressCity	ComponentType<HomeAddressCityFieldProps> | undefined	City; defined only when the API returns home_address_city.
HomeAddressState	ComponentType<HomeAddressStateFieldProps> | undefined	State; defined only when the API returns home_address_state.
HomeAddressStreet1	ComponentType<HomeAddressStreet1FieldProps> | undefined	Street address line 1; defined only when the API returns home_address_street_1.
HomeAddressStreet2	ComponentType<HomeAddressStreet2FieldProps> | undefined	Street address line 2; defined only when the API returns home_address_street_2.
HomeAddressZip	ComponentType<HomeAddressZipFieldProps> | undefined	ZIP code; defined only when the API returns home_address_zip.
LlcClassificationCode	ComponentType<LlcClassificationCodeFieldProps> | undefined	LLC tax classification code select; defined only when classification checkboxes are present.
Name	ComponentType<NameFieldProps> | undefined	Entity or individual name; defined only when the API returns name.
OtherText	ComponentType<OtherTextFieldProps> | undefined	"Other" free-text classification; defined only when the API returns other_text.
SignatureText	ComponentType<SignatureTextFieldProps> | undefined	Typed signature; defined only when the API returns signature_text.
Ssn	ComponentType<SsnFieldProps> | undefined	Social Security Number; defined only when the API returns ssn.
TaxClassification	ComponentType<TaxClassificationFieldProps> | undefined	Federal tax classification radio group; defined only when the document carries classification checkboxes.

---

AccountNumber

Account number(s); defined only when the API returns account_number.

{form.Fields.AccountNumber && (
  <form.Fields.AccountNumber
    label="Account number"
    validationMessages={{ REQUIRED: '…' }}
  />
)}

ContractorSignatureAccountNumberFieldProps

HookFieldProps<TextInputHookFieldProps<ContractorSignatureRequiredValidation>>

Props accepted by useContractorSignatureForm's Fields.AccountNumber component.

Property	Type	Description
label	string	Visible label rendered above the field.
FieldComponent?	ComponentType<TextInputProps>	Replaces the default text input UI component; must accept the same props as TextInputProps.
validationMessages?	ValidationMessages<ContractorSignatureRequiredValidation>	Custom error text keyed by validation error code.

Also accepts description, formHookResult, placeholder, transform from TextInputHookFieldProps.

---

Agree

Electronic-signature consent checkbox; always present (synthesized, not an API field).

<form.Fields.Agree
  label="Agree"
  validationMessages={{ AGREE_REQUIRED: '…' }}
/>

ContractorSignatureAgreeFieldProps

HookFieldProps<CheckboxHookFieldProps<ContractorSignatureAgreeValidation>>

Props accepted by useContractorSignatureForm's Fields.Agree component.

Property	Type	Description
label	string	Visible label rendered above the field.
FieldComponent?	ComponentType<CheckboxProps>	Replaces the default checkbox UI component; must accept the same props as CheckboxProps.
validationMessages?	ValidationMessages<ContractorSignatureAgreeValidation>	Custom error text keyed by validation error code.

Also accepts description, formHookResult from CheckboxHookFieldProps.

---

BusinessName

Business name; defined only when the API returns business_name.

{form.Fields.BusinessName && (
  <form.Fields.BusinessName
    label="Business name"
    validationMessages={{ REQUIRED: '…' }}
  />
)}

ContractorSignatureBusinessNameFieldProps

HookFieldProps<TextInputHookFieldProps<ContractorSignatureRequiredValidation>>

Props accepted by useContractorSignatureForm's Fields.BusinessName component.

Property	Type	Description
label	string	Visible label rendered above the field.
FieldComponent?	ComponentType<TextInputProps>	Replaces the default text input UI component; must accept the same props as TextInputProps.
validationMessages?	ValidationMessages<ContractorSignatureRequiredValidation>	Custom error text keyed by validation error code.

Also accepts description, formHookResult, placeholder, transform from TextInputHookFieldProps.

---

CompanyName

Requester's name and address; defined only when the API returns company_name.

{form.Fields.CompanyName && (
  <form.Fields.CompanyName
    label="Company name"
    validationMessages={{ REQUIRED: '…' }}
  />
)}

ContractorSignatureCompanyNameFieldProps

HookFieldProps<TextInputHookFieldProps<ContractorSignatureRequiredValidation>>

Props accepted by useContractorSignatureForm's Fields.CompanyName component.

Property	Type	Description
label	string	Visible label rendered above the field.
FieldComponent?	ComponentType<TextInputProps>	Replaces the default text input UI component; must accept the same props as TextInputProps.
validationMessages?	ValidationMessages<ContractorSignatureRequiredValidation>	Custom error text keyed by validation error code.

Also accepts description, formHookResult, placeholder, transform from TextInputHookFieldProps.

---

Ein

Employer Identification Number; defined only when the API returns ein.

{form.Fields.Ein && (
  <form.Fields.Ein
    label="Ein"
    validationMessages={{ INVALID_EIN: '…', REQUIRED: '…' }}
  />
)}

ContractorSignatureEinFieldProps

HookFieldProps<TextInputHookFieldProps<ContractorSignatureEinValidation, ContractorSignatureRequiredValidation>>

Props accepted by useContractorSignatureForm's Fields.Ein component.

Property	Type	Description
label	string	Visible label rendered above the field.
FieldComponent?	ComponentType<TextInputProps>	Replaces the default text input UI component; must accept the same props as TextInputProps.
validationMessages?	ValidationMessages<ContractorSignatureEinValidation, ContractorSignatureRequiredValidation>	Custom error text keyed by validation error code.

Also accepts description, formHookResult, placeholder, transform from TextInputHookFieldProps.

---

ExemptionFromFatca

FATCA exemption code; defined only when the API returns exemption_from_FATCA.

{form.Fields.ExemptionFromFatca && (
  <form.Fields.ExemptionFromFatca
    label="Exemption from fatca"
    validationMessages={{ REQUIRED: '…' }}
  />
)}

ContractorSignatureExemptionFromFatcaFieldProps

HookFieldProps<TextInputHookFieldProps<ContractorSignatureRequiredValidation>>

Props accepted by useContractorSignatureForm's Fields.ExemptionFromFatca component.

Property	Type	Description
label	string	Visible label rendered above the field.
FieldComponent?	ComponentType<TextInputProps>	Replaces the default text input UI component; must accept the same props as TextInputProps.
validationMessages?	ValidationMessages<ContractorSignatureRequiredValidation>	Custom error text keyed by validation error code.

Also accepts description, formHookResult, placeholder, transform from TextInputHookFieldProps.

---

ExemptPayeeCode

Exempt payee code; defined only when the API returns exempt_payee_code.

{form.Fields.ExemptPayeeCode && (
  <form.Fields.ExemptPayeeCode
    label="Exempt payee code"
    validationMessages={{ REQUIRED: '…' }}
  />
)}

ContractorSignatureExemptPayeeCodeFieldProps

HookFieldProps<TextInputHookFieldProps<ContractorSignatureRequiredValidation>>

Props accepted by useContractorSignatureForm's Fields.ExemptPayeeCode component.

Property	Type	Description
label	string	Visible label rendered above the field.
FieldComponent?	ComponentType<TextInputProps>	Replaces the default text input UI component; must accept the same props as TextInputProps.
validationMessages?	ValidationMessages<ContractorSignatureRequiredValidation>	Custom error text keyed by validation error code.

Also accepts description, formHookResult, placeholder, transform from TextInputHookFieldProps.

---

ForeignPartners

Foreign partners checkbox; defined only when the API returns foreign_partners.

{form.Fields.ForeignPartners && (
  <form.Fields.ForeignPartners label="Foreign partners" />
)}

ContractorSignatureForeignPartnersFieldProps

HookFieldProps<CheckboxHookFieldProps>

Props accepted by useContractorSignatureForm's Fields.ForeignPartners component.

Property	Type	Description
label	string	Visible label rendered above the field.
FieldComponent?	ComponentType<CheckboxProps>	Replaces the default checkbox UI component; must accept the same props as CheckboxProps.

Also accepts description, formHookResult from CheckboxHookFieldProps.

---

HomeAddressCity

City; defined only when the API returns home_address_city.

{form.Fields.HomeAddressCity && (
  <form.Fields.HomeAddressCity
    label="Home address city"
    validationMessages={{ REQUIRED: '…' }}
  />
)}

ContractorSignatureHomeAddressCityFieldProps

HookFieldProps<TextInputHookFieldProps<ContractorSignatureRequiredValidation>>

Props accepted by useContractorSignatureForm's Fields.HomeAddressCity component.

Property	Type	Description
label	string	Visible label rendered above the field.
FieldComponent?	ComponentType<TextInputProps>	Replaces the default text input UI component; must accept the same props as TextInputProps.
validationMessages?	ValidationMessages<ContractorSignatureRequiredValidation>	Custom error text keyed by validation error code.

Also accepts description, formHookResult, placeholder, transform from TextInputHookFieldProps.

---

HomeAddressState

State; defined only when the API returns home_address_state.

{form.Fields.HomeAddressState && (
  <form.Fields.HomeAddressState
    label="Home address state"
    validationMessages={{ REQUIRED: '…' }}
  />
)}

ContractorSignatureHomeAddressStateFieldProps

HookFieldProps<TextInputHookFieldProps<ContractorSignatureRequiredValidation>>

Props accepted by useContractorSignatureForm's Fields.HomeAddressState component.

Property	Type	Description
label	string	Visible label rendered above the field.
FieldComponent?	ComponentType<TextInputProps>	Replaces the default text input UI component; must accept the same props as TextInputProps.
validationMessages?	ValidationMessages<ContractorSignatureRequiredValidation>	Custom error text keyed by validation error code.

Also accepts description, formHookResult, placeholder, transform from TextInputHookFieldProps.

---

HomeAddressStreet1

Street address line 1; defined only when the API returns home_address_street_1.

{form.Fields.HomeAddressStreet1 && (
  <form.Fields.HomeAddressStreet1
    label="Home address street1"
    validationMessages={{ REQUIRED: '…' }}
  />
)}

ContractorSignatureHomeAddressStreet1FieldProps

HookFieldProps<TextInputHookFieldProps<ContractorSignatureRequiredValidation>>

Props accepted by useContractorSignatureForm's Fields.HomeAddressStreet1 component.

Property	Type	Description
label	string	Visible label rendered above the field.
FieldComponent?	ComponentType<TextInputProps>	Replaces the default text input UI component; must accept the same props as TextInputProps.
validationMessages?	ValidationMessages<ContractorSignatureRequiredValidation>	Custom error text keyed by validation error code.

Also accepts description, formHookResult, placeholder, transform from TextInputHookFieldProps.

---

HomeAddressStreet2

Street address line 2; defined only when the API returns home_address_street_2.

{form.Fields.HomeAddressStreet2 && (
  <form.Fields.HomeAddressStreet2
    label="Home address street2"
    validationMessages={{ REQUIRED: '…' }}
  />
)}

ContractorSignatureHomeAddressStreet2FieldProps

HookFieldProps<TextInputHookFieldProps<ContractorSignatureRequiredValidation>>

Props accepted by useContractorSignatureForm's Fields.HomeAddressStreet2 component.

Property	Type	Description
label	string	Visible label rendered above the field.
FieldComponent?	ComponentType<TextInputProps>	Replaces the default text input UI component; must accept the same props as TextInputProps.
validationMessages?	ValidationMessages<ContractorSignatureRequiredValidation>	Custom error text keyed by validation error code.

Also accepts description, formHookResult, placeholder, transform from TextInputHookFieldProps.

---

HomeAddressZip

ZIP code; defined only when the API returns home_address_zip.

{form.Fields.HomeAddressZip && (
  <form.Fields.HomeAddressZip
    label="Home address zip"
    validationMessages={{ REQUIRED: '…' }}
  />
)}

ContractorSignatureHomeAddressZipFieldProps

HookFieldProps<TextInputHookFieldProps<ContractorSignatureRequiredValidation>>

Props accepted by useContractorSignatureForm's Fields.HomeAddressZip component.

Property	Type	Description
label	string	Visible label rendered above the field.
FieldComponent?	ComponentType<TextInputProps>	Replaces the default text input UI component; must accept the same props as TextInputProps.
validationMessages?	ValidationMessages<ContractorSignatureRequiredValidation>	Custom error text keyed by validation error code.

Also accepts description, formHookResult, placeholder, transform from TextInputHookFieldProps.

---

LlcClassificationCode

LLC tax classification code select; defined only when classification checkboxes are present.

{form.Fields.LlcClassificationCode && (
  <form.Fields.LlcClassificationCode
    label="Llc classification code"
    validationMessages={{ REQUIRED: '…' }}
  />
)}

ContractorSignatureLlcClassificationCodeFieldProps

HookFieldProps<SelectHookFieldProps<ContractorSignatureRequiredValidation, string>>

Props accepted by useContractorSignatureForm's Fields.LlcClassificationCode component.

Property	Type	Description
label	string	Visible label rendered above the field.
placeholder	string	Placeholder text displayed when no option is selected. Required so empty dropdowns always communicate the action — pass an empty string only when a default value is guaranteed.
FieldComponent?	ComponentType<SelectProps>	Replaces the default select UI component; must accept the same props as SelectProps.
getOptionLabel?	(entry: string) => string	Maps a raw option entry to its display label; when omitted, options use the labels provided by the hook.
validationMessages?	ValidationMessages<ContractorSignatureRequiredValidation>	Custom error text keyed by validation error code.

Also accepts description, formHookResult, portalContainer from SelectHookFieldProps.

---

Name

Entity or individual name; defined only when the API returns name.

{form.Fields.Name && (
  <form.Fields.Name
    label="Name"
    validationMessages={{ REQUIRED: '…' }}
  />
)}

ContractorSignatureNameFieldProps

HookFieldProps<TextInputHookFieldProps<ContractorSignatureRequiredValidation>>

Props accepted by useContractorSignatureForm's Fields.Name component.

Property	Type	Description
label	string	Visible label rendered above the field.
FieldComponent?	ComponentType<TextInputProps>	Replaces the default text input UI component; must accept the same props as TextInputProps.
validationMessages?	ValidationMessages<ContractorSignatureRequiredValidation>	Custom error text keyed by validation error code.

Also accepts description, formHookResult, placeholder, transform from TextInputHookFieldProps.

---

OtherText

"Other" free-text classification; defined only when the API returns other_text.

{form.Fields.OtherText && (
  <form.Fields.OtherText
    label="Other text"
    validationMessages={{ REQUIRED: '…' }}
  />
)}

ContractorSignatureOtherTextFieldProps

HookFieldProps<TextInputHookFieldProps<ContractorSignatureRequiredValidation>>

Props accepted by useContractorSignatureForm's Fields.OtherText component.

Property	Type	Description
label	string	Visible label rendered above the field.
FieldComponent?	ComponentType<TextInputProps>	Replaces the default text input UI component; must accept the same props as TextInputProps.
validationMessages?	ValidationMessages<ContractorSignatureRequiredValidation>	Custom error text keyed by validation error code.

Also accepts description, formHookResult, placeholder, transform from TextInputHookFieldProps.

---

SignatureText

Typed signature; defined only when the API returns signature_text.

{form.Fields.SignatureText && (
  <form.Fields.SignatureText
    label="Signature text"
    validationMessages={{ REQUIRED: '…' }}
  />
)}

ContractorSignatureSignatureTextFieldProps

HookFieldProps<TextInputHookFieldProps<ContractorSignatureRequiredValidation>>

Props accepted by useContractorSignatureForm's Fields.SignatureText component.

Property	Type	Description
label	string	Visible label rendered above the field.
FieldComponent?	ComponentType<TextInputProps>	Replaces the default text input UI component; must accept the same props as TextInputProps.
validationMessages?	ValidationMessages<ContractorSignatureRequiredValidation>	Custom error text keyed by validation error code.

Also accepts description, formHookResult, placeholder, transform from TextInputHookFieldProps.

---

Ssn

Social Security Number; defined only when the API returns ssn.

{form.Fields.Ssn && (
  <form.Fields.Ssn
    label="Ssn"
    validationMessages={{ INVALID_SSN: '…', REQUIRED: '…' }}
  />
)}

ContractorSignatureSsnFieldProps

HookFieldProps<TextInputHookFieldProps<ContractorSignatureSsnValidation, ContractorSignatureRequiredValidation>>

Props accepted by useContractorSignatureForm's Fields.Ssn component.

Property	Type	Description
label	string	Visible label rendered above the field.
FieldComponent?	ComponentType<TextInputProps>	Replaces the default text input UI component; must accept the same props as TextInputProps.
validationMessages?	ValidationMessages<ContractorSignatureSsnValidation, ContractorSignatureRequiredValidation>	Custom error text keyed by validation error code.

Also accepts description, formHookResult, placeholder, transform from TextInputHookFieldProps.

---

TaxClassification

Federal tax classification radio group; defined only when the document carries classification checkboxes.

{form.Fields.TaxClassification && (
  <form.Fields.TaxClassification
    label="Tax classification"
    validationMessages={{ REQUIRED: '…' }}
  />
)}

ContractorSignatureTaxClassificationFieldProps

HookFieldProps<RadioGroupHookFieldProps<ContractorSignatureRequiredValidation, string>>

Props accepted by useContractorSignatureForm's Fields.TaxClassification component.

Property	Type	Description
label	string	Visible label rendered above the field.
FieldComponent?	ComponentType<RadioGroupProps>	Replaces the default radio group UI component; must accept the same props as RadioGroupProps.
getOptionLabel?	(entry: string) => string	Maps a raw option entry to its display label; when omitted, options use the labels provided by the hook.
validationMessages?	ValidationMessages<ContractorSignatureRequiredValidation>	Custom error text keyed by validation error code.

Also accepts description, formHookResult from RadioGroupHookFieldProps.

Validations

ContractorSignatureAgreeValidation

ContractorSignatureAgreeValidation = "AGREE_REQUIRED"

Validation error code emitted by the Agree consent checkbox.

Remarks

Use as a key in validationMessages on Fields.Agree. See ContractorSignatureFormErrorCodes.

---

ContractorSignatureEinValidation

ContractorSignatureEinValidation = "INVALID_EIN"

The format-validation error code emitted by the ein field of useContractorSignatureForm.

Remarks

Use as a key in validationMessages on Fields.Ein. See ContractorSignatureFormErrorCodes.

---

ContractorSignatureRequiredValidation

ContractorSignatureRequiredValidation = "REQUIRED"

The required-field error code emitted by most useContractorSignatureForm fields.

Remarks

Use as a key in validationMessages for text inputs, selects, and radio groups that only emit the REQUIRED error. See ContractorSignatureFormErrorCodes.

---

ContractorSignatureSsnValidation

ContractorSignatureSsnValidation = "INVALID_SSN"

The format-validation error code emitted by the ssn field of useContractorSignatureForm.

Remarks

Use as a key in validationMessages on Fields.Ssn. See ContractorSignatureFormErrorCodes.

Utility types

ContractorSignatureFieldsMetadata

Field	Type
accountNumber	FieldMetadata
agree	FieldMetadata
businessName	FieldMetadata
companyName	FieldMetadata
ein	FieldMetadata
exemptionFromFatca	FieldMetadata
exemptPayeeCode	FieldMetadata
foreignPartners	FieldMetadata
homeAddressCity	FieldMetadata
homeAddressState	FieldMetadata
homeAddressStreet1	FieldMetadata
homeAddressStreet2	FieldMetadata
homeAddressZip	FieldMetadata
llcClassificationCode	FieldMetadataWithOptions<"c" | "s" | "p">
name	FieldMetadata
otherText	FieldMetadata
signatureText	FieldMetadata
ssn	FieldMetadata
taxClassification	FieldMetadataWithOptions<"other" | "individual_proprietor" | "c_corporation" | "s_corporation" | "partnership" | "trust_estate" | "limited_liability_company">

Per-field metadata exposed by useContractorSignatureForm as form.fieldsMetadata.

Remarks

Extracted from the ready-state result for standalone use when a partner needs to type-check or reference the metadata shape independently.

---

ContractorSignatureFormData

Shape of the values managed by useContractorSignatureForm.

Remarks

Keys are the camelCase react-hook-form field names. taxClassification and llcClassificationCode are synthesized (they have no single API field), and agree is the electronic-signature consent; all other keys map to a W-9 API field via the hook's serializer.

Properties

Property	Type	Description
accountNumber	string	Account number(s) (W-9 line 7).
agree	boolean	Electronic-signature consent; must be checked to submit.
businessName	string	Business name, if different (W-9 line 2).
companyName	string	Requester's name and address.
ein	string	Employer Identification Number. Accepts a formatted EIN (NN-NNNNNNN) or the N/A sentinel the API uses when the W-9 collects an SSN instead. A redacted value left untouched (empty) is valid — the server keeps the EIN on file.
exemptionFromFatca	string	Exemption from FATCA reporting code (W-9 line 4b).
exemptPayeeCode	string	Exempt payee code (W-9 line 4a).
foreignPartners	boolean	Whether the payee has foreign partners/owners/beneficiaries (W-9 line 3b).
homeAddressCity	string	City (W-9 line 6).
homeAddressState	string	State (W-9 line 6).
homeAddressStreet1	string	Street address line 1 (W-9 line 5).
homeAddressStreet2	string	Street address line 2 (W-9 line 5).
homeAddressZip	string	ZIP code (W-9 line 6).
llcClassificationCode	string	LLC tax classification code, set only when the LLC classification is selected.
name	string	Entity or individual name (W-9 line 1).
otherText	string	Free-text classification entry, used only when the "Other" classification is selected.
signatureText	string	Typed signature.
ssn	string	Social Security Number. Accepts a 9-digit SSN (validated digits-only) or the N/A sentinel the API uses when the W-9 collects an EIN instead. A redacted value left untouched (empty) is valid — the server keeps the SSN on file.
taxClassification	string	Selected federal tax classification option key (W-9 line 3).

---

ContractorSignatureFormErrorCode

ContractorSignatureFormErrorCode = "REQUIRED" | "INVALID_SSN" | "INVALID_EIN" | "AGREE_REQUIRED"

Union of validation error code strings emitted by the contractor signature form schema.

---

ContractorSignatureFormErrorCodes

const ContractorSignatureFormErrorCodes: object

Validation error codes produced by the contractor signature form schema.

Remarks

Use these constants as the keys in a field's validationMessages prop to map an error code to a user-facing message.

Type Declaration

Name	Type	Description
AGREE_REQUIRED	"AGREE_REQUIRED"	The electronic-signature consent checkbox was not checked.
INVALID_EIN	"INVALID_EIN"	The Employer Identification Number is not a valid EIN.
INVALID_SSN	"INVALID_SSN"	The Social Security Number is not a valid SSN.
REQUIRED	"REQUIRED"	A required field was left empty.

---

ContractorSignatureOptionalFieldsToRequire

ContractorSignatureOptionalFieldsToRequire = OptionalFieldsToRequire<typeof requiredFieldsConfig>

Optional W-9 fields a partner can promote to required.

---

Endpoints

Method	Path
GET	/v1/documents/:documentUuid
GET	/v1/documents/:documentUuid/pdf
PUT	/v1/documents/:documentUuid/sign