Testing & Sandbox
Sandbox

Set job title eligibility verdict

Changed on

Sets the job title eligibility verdict the employment's next contract-details submission will act on, so the flow that verdict drives can be tested without an AI call deciding the outcome.

Use it to reach an outcome on demand: a submission that passes, one rejected as not eligible, one that must carry employer_acknowledges_risk, or one that places the employment into a human review and emits the review webhooks.

The response is the same as the real job title eligibility check endpoint. Send the returned check_id back as additional_job_title_eligibility_check_slug when submitting contract details, exactly as you would in production.

role_description, role_is_onsite and role_requires_license must be the answers the job title eligibility check and the submission will carry, since both reuse the recorded verdict only while it still describes what was sent. A role question the employment's country does not ask is ignored.

A not_assessed verdict means the check does not apply to this employment at all — not a draft, a PEO employment, a country or hiring model that does not screen job titles, or an integration that bypasses the check — and nothing was recorded.

The stage of the check that screens the job title alone is shared by every company in the environment, so setting a verdict takes over that job title's screen for all of them.

This endpoint is only available in Sandbox, otherwise it will respond with a 404.

Authentication

This endpoint accepts any one of the following token types:

  • Company-scoped access token (OAuth2AuthorizationCode) — obtained through the Authorization Code flow or the Refresh Token flow. See Authentication for partners.
  • Customer API token (CustomerAPIToken) — generated by the customer on their Integration Settings page. See Authorization for customers.
post/v1/sandbox/employments/{employment_id}/job-title-eligibility-check

Request

  • Base URL: https://gateway.remote.com
  • URL: https://gateway.remote.com/v1/sandbox/employments/{employment_id}/job-title-eligibility-check
  • Auth: HTTP bearer and OAuth 2 (authorization code, authorization URL /auth/oauth2/authorize, token URL /auth/oauth2/token)

Path parameters

employment_idstring required

Employment ID

Request body

job_titlestring

The job title to record the verdict against. Defaults to the employment's current one.

role_descriptionstring required

The role description the submission will carry. A submission carrying a different one is rejected, because the recorded verdict no longer describes what was sent.

role_is_onsite'yes' | 'no'

The answer the job title eligibility check will be sent for whether the role is onsite. Required when the employment's country asks the question, and ignored when it does not.

role_requires_license'yes' | 'no'

The answer the job title eligibility check will be sent for whether the role requires a license. Required when the employment's country asks the question, and ignored when it does not.

verdict'eligible' | 'not_eligible' | 'needs_review' | 'eligible_with_risk_acknowledgement' required

The verdict the employment's next contract-details submission should act on.

Example request

{
  "role_description": "Provides bedside care on a hospital ward",
  "role_is_onsite": "yes",
  "role_requires_license": "no",
  "verdict": "needs_review"
}

Response

Success

Example response

{
  "data": {
    "job_title_eligibility_check": {
      "check_id": "8f2c1a7e-2b64-4f4e-9c1a-5d0f2a9b7c33",
      "verdict": "needs_review"
    }
  }
}

Changes