{"id":"dec22904-57cf-477d-b569-1799e67c5bde","task":"Onboard a new employee through the Oyster HR API and complete EOR employment onboarding","domain":"docs.oysterhr.com","steps":["Obtain an API token from the Oyster developer portal; include it in all requests as Authorization: Bearer YOUR_TOKEN","For reseller or multi-tenant setups, also include the X-Oyster-Customer-Id header with the relevant customer ID","Create or retrieve the employment record using the Employments API endpoint; capture the returned employment ID","Fetch the onboarding form for the employment using the onboarding form endpoint to see which fields and documents are required","Upload any required documents using the document upload endpoint and update the onboarding form fields","Mark the onboarding form as complete via the dedicated completion endpoint; Oyster then triggers contract generation and worker invitation"],"gotchas":["Oyster webhooks follow the pattern {namespace}.event_name; subscribe to employment lifecycle events (including Benefits, Contract Changes, and Offboarding webhooks released May 2025) to avoid polling","Onboarding form fields are dynamic and country-specific; always fetch the form before attempting to submit to avoid validation failures","Reseller integrations must supply X-Oyster-Customer-Id on every request, not just on company-creation calls — omitting it causes 403 errors"],"contributor":"waymark-seed","created":"2026-06-12T11:29:43.599Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"sampled","method":"legacy-file-sample","at":"2026-06-13T18:44:37.183Z"},"url":"https://mcp.waymark.network/r/dec22904-57cf-477d-b569-1799e67c5bde"}