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
Known 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
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp