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

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 fields in the JSON request body:

Field	Required	Description
`apiKeyId`	Yes	API key identifier (URN format)
`apiKeySecret`	Yes	API key secret

Obtain credentials

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

OnBo validates the key and uses its bound company and journey. The job is always created for the key’s company.

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, including apiKeyId and apiKeySecret:


{
  "apiKeyId": "urn:apikeysv1:prod:region:company:YOUR_KEY_UUID",
  "apiKeySecret": "YOUR_API_KEY_SECRET",
  "name": "Jane Doe",
  "phone": "+15551234567",
  "email": "jane@example.com",
  "campaignToken": "campaign-abc-123",
  "firstDayOfEmployment": "03/15/2026",
  "channel": ["sms", "email"]
}

Fields

Field	Required	Notes
`apiKeyId`	Yes	API key identifier from the dashboard
`apiKeySecret`	Yes	API key secret paired with `apiKeyId`
`name`	Yes*	Candidate full name
`phone`	Yes*	Contact phone number
`email`	No	Optional contact email
`campaignToken`	No	Optional campaign or tracking identifier
`firstDayOfEmployment`	Yes for I-9*	Required for I-9 onboarding journeys
`channel`	No	Notification channels; only `"sms"` and/or `"email"` allowed

* 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 apiKeyId, apiKeySecret, name, and phone. 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"
}

Field	Description
`onboardingLink`	URL to send the end user — available immediately
`jobId`	Created job identifier

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

Error responses

Status	Meaning
400	Invalid request — missing required fields or invalid field values
401	Invalid or missing API key ID / secret
403	Key not authorized for this operation
500	Server error — retry with backoff; contact support if persistent

Common validation errors (400)

Issue	Action
Missing `apiKeyId` or `apiKeySecret`	Include both fields in the request body
Missing `name`	Include candidate full name
Missing `phone`	Include phone in E.164 or accepted format
Missing `firstDayOfEmployment` for I-9	Required for I-9 onboarding journeys
Invalid `channel`	Use only `"sms"` and/or `"email"`

Example (curl)


curl -X POST "https://portal.idmission.com/api/create-onboarding-link" \
  -H "Content-Type: application/json" \
  -d '{
    "apiKeyId": "urn:apikeysv1:prod:region:company:YOUR_KEY_UUID",
    "apiKeySecret": "YOUR_API_KEY_SECRET",
    "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 apiKeyId and apiKeySecret in the JSON request body
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 direct API key + secret in the request body (no session cache or re-mint on 401).
Validation — always include apiKeyId, apiKeySecret, name, and phone; include firstDayOfEmployment for I-9 journeys. Invalid requests return 400.
Journey from key — use the correct API key per journey.