Where contract fields come from
A signing request is more than a document and an email address. Keep three sources separate: customer profiles maintained by the club, published template content, and values/evidence collected during signing.
Ownership and access
| Data | Source and maintenance | What the integration does |
|---|---|---|
| Person ID | Assigned when SportsX creates the person; your business ID is a separate identifier | Store data.contactId; match existing people first and always pass IDs as strings |
| Name, phone, birthday | Club-specific profiles maintained by the merchant; birthday is not an age number uploaded with each send | Check GET /v1/club/contacts/{id}; use PATCH /v1/club/contacts/{id} for supported updates |
| Recipient email | The signer's contact email, resolved by the server into a recipient record | Verify the signer's profile before sending. Contact PATCH can set the identity email only while the contact has none; an existing one cannot be changed |
| Parent-child relationship | Existing household membership and relations, not inferred from names | Check relation and contactId through GET /v1/club/contacts/{id}/households; use household endpoints for maintenance |
| Club legal name, address, privacy contact | Merchant compliance profile; contact email and phone come from organization data | These are not signing-request inputs; fix missing or incorrect values in the console |
| Program, schedule, price and contract terms | Template authoringInputs and the published version prepared by the merchant | Inspect template details; do not send price or schedule overrides in the signing POST |
| Jurisdiction and document-selection rules | Club compliance settings, template-version jurisdictionProfile and companion-document rules | Use resolve-waivers to help select documents; do not hard-code a statute's age threshold in your integration |
| Field definitions and signing requirements | fields and signingRequirements in template details | Check required input, acknowledgment, initials and signature requirements; do not assume every template is the same |
| Typed name, signature, initials and consent actions | Collected on the SportsX signing page according to document requirements | The Partner API initiates and queries requests; it does not sign on the user's behalf |
| Open/sign timestamps, IP, User-Agent and file evidence | Recorded by the signing service; some values may be unavailable | Read events, request details and files. Do not fabricate missing values or treat an IP as identity verification |
Full profiles require club.contacts.read_pii; profile updates require club.contacts.write. Minimize locally retained personal data and avoid putting real profiles in support tickets or debug logs.
contactId depends on the endpoint
| Endpoint | Meaning of contactId | Parent signing for a child |
|---|---|---|
POST /v1/club/compliance/signing-requests/resolve-waivers | Participant whose document applicability is evaluated | Child 3102 |
POST /v1/club/compliance/signing-requests/preview | Signer | Parent 3101, plus dependentContactId: "3102" |
POST /v1/club/compliance/signing-requests | Person receiving the invitation and signing | Parent 3101, plus dependentContactId: "3102" |
For an adult signing for themselves, omit dependentContactId. An ordinary parent-on-behalf-of-child agreement can use flowFlavor: "standard". parental_consent selects a specialized flow; it is not a general parent-signer flag.
If a relationship is missing, more than one signer could apply, or profiles disagree, ask the merchant to confirm. Accepting two IDs does not mean the API has confirmed signing authority for you.
Templates, versions and variables
In template details, id identifies the template. currentVersion is a version number; currentVersionId is the ID needed by items[].templateVersionId when sending. Read documentKind from the selected template rather than guessing from its title.
fields defines the template's fields. Inspect fieldKey, fieldType, sourceType, sourceRef, required and editableBySigner. These definitions do not mean every value is already filled in the preview. Field-level required is also different from items[].required, which says whether the entire document must be signed.
The current Partner preview/create endpoints have no variables, fieldValues or arbitrary merge-fields input. Adding those keys cannot override contract text, price or a child's birthday. Correct profiles first; for contract changes, ask the merchant to prepare and publish the appropriate version before previewing and sending.
Age and companion documents
The current companion-document resolver reads the birthday from this club's profile, calculates age at the time of the call, and considers the club's jurisdiction when determining majority. It does not accept a caller-supplied age: 26, and different legal requirements do not all share one age rule.
A missing birthday is reported through dobMissing; an unresolved sport appendix is reported through appendixMatch. Keep that uncertainty visible for merchant review. Do not label an unchecked default as “not required.”
Legal text and jurisdiction-specific rules belong to templates and configuration. This page describes API behavior, not the legal requirements for an individual program, jurisdiction or signer.
Verify preview and evidence separately
The merchant preview mainly merges template content and organization details. Signer fields may still be placeholders; actual signatures, initials and signing timestamps exist only later.
Do not archive preview Markdown as the final contract, or assume that passing the correct contactId guarantees a fully populated final file. During acceptance, open the actual signed file and verify:
- The parent and child are correct; names, birthday and relationship match the confirmed profiles.
- Program, price and selected template versions are correct, and required items are completed.
- Signing times, events, signed files and completion certificates correspond. Leave unavailable evidence empty or report it rather than inventing it.
Specifically test a birthday maintained only on the club profile and a parent signing through the standard flow. These cases can reveal final-file rendering problems that API type checks cannot catch.