From b192031485f0c77e5f3db7e6e128109d2ca4b0de Mon Sep 17 00:00:00 2001 From: Jesse Ouellette Date: Thu, 3 Sep 2026 14:44:10 -0400 Subject: [PATCH] docs(openapi): add job-change-detector statuses and resolution_reason MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Sync the Job Change Detector snapshot with the live API contract: - status enum gains AMBIGUOUS_CURRENT_EMPLOYMENT, CURRENT_EMPLOYMENT_UNKNOWN (matched employer, undated role — unknown, not a change) and PROFILE_NOT_FOUND (profile URL did not resolve — credits_consumed is 0) - add the resolution_reason enum - document that job_change_detected is true only for JOB_CHANGE_DETECTED and that an absent expected employer with another primary current role is JOB_CHANGE_DETECTED (NEVER_WORKED_THERE only when nothing is current) - credits_consumed example corrected from 2 to 3 YAML and JSON stay in sync (deep-equal verified). --- CHANGELOG.md | 1 + leadmagic-openapi-3.1.json | 28 +++++++++++++++++++++++++--- leadmagic-openapi-3.1.yaml | 23 +++++++++++++++++++++-- 3 files changed, 47 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index afa4f7a..ead31c3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] ### Changed +- `POST /v1/people/job-change-detector`: `status` enum now includes `AMBIGUOUS_CURRENT_EMPLOYMENT`, `CURRENT_EMPLOYMENT_UNKNOWN` (expected employer matched but the role carries no dates — unknown, not a change), and `PROFILE_NOT_FOUND` (profile URL did not resolve — `credits_consumed` is `0`); added the `resolution_reason` enum; documented that `job_change_detected` is `true` only for `JOB_CHANGE_DETECTED` and that an absent expected employer with another primary current role is `JOB_CHANGE_DETECTED` (`NEVER_WORKED_THERE` only when nothing is current); `credits_consumed` example corrected to `3` - README: companion-surfaces table and pairing copy for [leadmagic-cursor-plugin](https://github.com/LeadMagic/leadmagic-cursor-plugin) (skills, rules, agent, commands, OAuth MCP); contrast with local stdio plugins (e.g. Encore); hosted MCP section lists **10 tools** with REST hints and jobs/ads API-only note - Synced top-level repository docs to the current `leadmagic.io/docs` route layout under `/v1/...` - Reworked the smoke-test utility as `test-api.ts` with typed test cases, secure interactive API-key entry, compact output previews, and pass/fail reporting against current documented endpoints diff --git a/leadmagic-openapi-3.1.json b/leadmagic-openapi-3.1.json index 2afc3f9..c636e1e 100644 --- a/leadmagic-openapi-3.1.json +++ b/leadmagic-openapi-3.1.json @@ -4052,7 +4052,7 @@ "/v1/people/job-change-detector": { "post": { "summary": "Job Change Detector", - "description": "Monitor employee transitions and detect when someone has changed jobs.", + "description": "Monitor employee transitions and detect when someone has changed jobs. Costs 3 credits per check. The submitted company_name is authoritative; a company_domain lookup only adds matcher aliases. job_change_detected is true only when status is JOB_CHANGE_DETECTED. When the profile URL does not resolve, the response is status PROFILE_NOT_FOUND with resolution_reason PROFILE_NOT_FOUND and credits_consumed 0 — nothing is charged.", "operationId": "job-change-detector", "tags": [ "Jobs Data" @@ -4103,21 +4103,42 @@ "properties": { "job_change_detected": { "type": "boolean", + "description": "true only when status is JOB_CHANGE_DETECTED.", "examples": [ false ] }, "status": { "type": "string", + "description": "NO_CHANGE — the expected employer is a current role. JOB_CHANGE_DETECTED — a different primary employer is current, or the matched role has an explicit end date with nothing current, or the expected employer is absent from history while another primary employer is current. NEVER_WORKED_THERE — the expected employer is absent from history and no primary current role is listed. AMBIGUOUS_CURRENT_EMPLOYMENT — multiple substantive current roles; not safe to call. CURRENT_EMPLOYMENT_UNKNOWN — the expected employer matched but the role carries no dates; unknown, not a change. PROFILE_NOT_FOUND — the profile URL did not resolve; credits_consumed is 0.", "enum": [ "NO_CHANGE", "JOB_CHANGE_DETECTED", - "NEVER_WORKED_THERE" + "NEVER_WORKED_THERE", + "AMBIGUOUS_CURRENT_EMPLOYMENT", + "CURRENT_EMPLOYMENT_UNKNOWN", + "PROFILE_NOT_FOUND" ], "examples": [ "NEVER_WORKED_THERE" ] }, + "resolution_reason": { + "type": "string", + "description": "Why the status was chosen. PROFILE_NOT_FOUND accompanies status PROFILE_NOT_FOUND.", + "enum": [ + "CURRENT_COMPANY_MATCHES_EXPECTED", + "CURRENT_COMPANY_DIFFERS_FROM_EXPECTED", + "EXPECTED_COMPANY_NOT_FOUND_IN_HISTORY", + "NO_CURRENT_POSITION_FOUND", + "NO_EXPERIENCE_HISTORY_FOUND", + "MULTIPLE_CURRENT_POSITIONS_FOUND", + "PROFILE_NOT_FOUND" + ], + "examples": [ + "EXPECTED_COMPANY_NOT_FOUND_IN_HISTORY" + ] + }, "summary": { "type": "string", "examples": [ @@ -4310,8 +4331,9 @@ }, "credits_consumed": { "type": "integer", + "description": "3 per check; 0 when status is PROFILE_NOT_FOUND.", "examples": [ - 2 + 3 ] } } diff --git a/leadmagic-openapi-3.1.yaml b/leadmagic-openapi-3.1.yaml index 7d78b57..0d13ae8 100644 --- a/leadmagic-openapi-3.1.yaml +++ b/leadmagic-openapi-3.1.yaml @@ -2779,7 +2779,7 @@ paths: /v1/people/job-change-detector: post: summary: Job Change Detector - description: Monitor employee transitions and detect when someone has changed jobs. + description: Monitor employee transitions and detect when someone has changed jobs. Costs 3 credits per check. The submitted company_name is authoritative; a company_domain lookup only adds matcher aliases. job_change_detected is true only when status is JOB_CHANGE_DETECTED. When the profile URL does not resolve, the response is status PROFILE_NOT_FOUND with resolution_reason PROFILE_NOT_FOUND and credits_consumed 0 — nothing is charged. operationId: job-change-detector tags: - Jobs Data @@ -2817,16 +2817,34 @@ paths: properties: job_change_detected: type: boolean + description: true only when status is JOB_CHANGE_DETECTED. examples: - false status: type: string + description: NO_CHANGE — the expected employer is a current role. JOB_CHANGE_DETECTED — a different primary employer is current, or the matched role has an explicit end date with nothing current, or the expected employer is absent from history while another primary employer is current. NEVER_WORKED_THERE — the expected employer is absent from history and no primary current role is listed. AMBIGUOUS_CURRENT_EMPLOYMENT — multiple substantive current roles; not safe to call. CURRENT_EMPLOYMENT_UNKNOWN — the expected employer matched but the role carries no dates; unknown, not a change. PROFILE_NOT_FOUND — the profile URL did not resolve; credits_consumed is 0. enum: - NO_CHANGE - JOB_CHANGE_DETECTED - NEVER_WORKED_THERE + - AMBIGUOUS_CURRENT_EMPLOYMENT + - CURRENT_EMPLOYMENT_UNKNOWN + - PROFILE_NOT_FOUND examples: - NEVER_WORKED_THERE + resolution_reason: + type: string + description: Why the status was chosen. PROFILE_NOT_FOUND accompanies status PROFILE_NOT_FOUND. + enum: + - CURRENT_COMPANY_MATCHES_EXPECTED + - CURRENT_COMPANY_DIFFERS_FROM_EXPECTED + - EXPECTED_COMPANY_NOT_FOUND_IN_HISTORY + - NO_CURRENT_POSITION_FOUND + - NO_EXPERIENCE_HISTORY_FOUND + - MULTIPLE_CURRENT_POSITIONS_FOUND + - PROFILE_NOT_FOUND + examples: + - EXPECTED_COMPANY_NOT_FOUND_IN_HISTORY summary: type: string examples: @@ -2953,8 +2971,9 @@ paths: - alex-rivera credits_consumed: type: integer + description: 3 per check; 0 when status is PROFILE_NOT_FOUND. examples: - - 2 + - 3 "400": $ref: "#/components/responses/BadRequest" "401":