Create Onboarding Job API

Creates an onboarding job and returns the end-user onboarding link in the same response.

Endpoint

POST https://portal.idmission.com/api/create-onboarding-link
Content-Type: application/json
X-Api-Key-Id: urn:apikeysv1:prod:region:company:YOUR_KEY_UUID
X-Api-Key-Secret: YOUR_API_KEY_SECRET

Call this endpoint from your server only. Never expose the API key secret in client-side code or mobile apps.

Authentication

Send the API key as two request headers:

Credentials are not accepted in the request body. Sending them there returns HTTP 401.

Breaking change. Earlier versions of this API took apiKeyId and apiKeySecret as JSON body fields. Move them to the headers above — the body form is no longer supported.

Obtain credentials

1. Sign in to https://dashboard.idmission.com 
2. Go to Journey Settings → Credentials
3. Click Create keys to generate an API key ID and secret

OnBo validates the key and uses its bound journey. The job is filed under the key’s own account unless you send companySlug naming a company beneath it.

Keys created before September 2026 carry no account and are rejected. Create a new key from Journey Settings → Credentials.

API keys must be journey-bound — create keys from Journey Settings → Credentials in the dashboard for each journey you integrate.

Request body

Send flat top-level fields. Credentials go in the headers, never here:

{
  "name": "Jane Doe",
  "phone": "+15551234567",
  "email": "jane@example.com",
  "campaignToken": "campaign-abc-123",
  "firstDayOfEmployment": "03/15/2026",
  "channel": ["sms", "email"],
  "companySlug": "thornbury-south"
}

Fields

* Required fields are enforced server-side. Missing or invalid values return HTTP 400.

Input validation

Every request is validated before a job is created. Always send the X-Api-Key-Id and X-Api-Key-Secret headers, and name and phone in the body. For I-9 onboarding journeys, also include firstDayOfEmployment. If you set channel, use only "sms" and/or "email".

If validation fails, the API returns HTTP 400 with an error describing what to fix.

Success response (200)

{
  "onboardingLink": "https://onbo.idmiss.io/abc123",
  "jobId": "job_xxxxxxxx"
}

Redirect the user to onboardingLink, or deliver it via your own SMS/email flow.

Error responses

Common validation errors (400)

Example (curl)

curl -X POST "https://portal.idmission.com/api/create-onboarding-link" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key-Id: urn:apikeysv1:prod:region:company:YOUR_KEY_UUID" \
  -H "X-Api-Key-Secret: YOUR_API_KEY_SECRET" \
  -d '{
    "name": "Jane Doe",
    "phone": "+15551234567",
    "email": "jane@example.com",
    "firstDayOfEmployment": "03/15/2026",
    "channel": ["sms", "email"]
  }'

Example success

{
  "onboardingLink": "https://onbo.idmiss.io/session/xyz",
  "jobId": "019fd6b7-3def-7ece-bd47-788508d3424d"
}

Integration checklist

• Create production API keys in the dashboard (Journey Settings → Credentials → Create keys)
• Call the API from your backend only
• Send X-Api-Key-Id and X-Api-Key-Secret as request headers
• Include name and phone for every request
• Include firstDayOfEmployment when using an I-9 journey key
• Restrict channel to sms and/or email if provided
• Deliver onboardingLink to the end user

Behavior notes

• No session minting — authentication is a direct API key ID + secret sent as headers (no session cache or re-mint on 401).
• Validation — always send the X-Api-Key-Id and X-Api-Key-Secret headers plus name and phone; include firstDayOfEmployment for I-9 journeys. Invalid requests return 400.
• Journey from key — use the correct API key per journey.

See also

• Overview — quick start and prerequisites