docs(openapi): add job-change-detector statuses and resolution_reason

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

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
                       ]
                     }
                   }

leadmagic-openapi-3.1.yaml

@@ -205,7 +205,7 @@
           meta:
             request_id: ea6e3248-f4d2-437d-bca3-20881b529129
             timestamp: 2024-02-01T12:00:00.000Z
     MissingFieldError:
       allOf:
         - $ref: "#/components/schemas/ErrorResponse"
       examples:
@@ -221,7 +221,7 @@
           meta:
             request_id: ea6e3248-f4d2-437d-bca3-20881b529129
             timestamp: 2024-02-01T12:00:00.000Z
     InvalidJsonError:
       allOf:
         - $ref: "#/components/schemas/ErrorResponse"
       examples:
@@ -235,7 +235,7 @@
           meta:
             request_id: ea6e3248-f4d2-437d-bca3-20881b529129
             timestamp: 2024-02-01T12:00:00.000Z
     InvalidParameterError:
       allOf:
         - $ref: "#/components/schemas/ErrorResponse"
       examples:
@@ -421,38 +421,38 @@
           meta:
             request_id: ea6e3248-f4d2-437d-bca3-20881b529129
             timestamp: 2024-02-01T12:00:00.000Z
     EmailValidationMessages:
       type: string
       description: Possible success messages for email validation
       enum:
         - Email is valid.
         - Email is invalid.
         - Unable to determine email validity.
     EmailFinderMessages:
       type: string
       description: Possible success messages for email finder
       enum:
         - Valid email found.
         - No email found for this person at this company.
     MobileFinderMessages:
       type: string
       description: Possible success messages for mobile finder
       enum:
         - Mobile number found.
         - No mobile number found for this contact.
     ProfileSearchMessages:
       type: string
       description: Possible success messages for profile search
       enum:
         - Profile found.
         - Profile not found or not accessible.
     CompanySearchMessages:
       type: string
       description: Possible success messages for company search
       enum:
         - Company found.
         - Company not found
     RoleFinderMessages:
       type: string
       description: Possible success messages for role finder
       enum:
@@ -464,7 +464,7 @@
       enum:
         - Employees found.
         - No employees found for this company.
     JobChangeDetectorMessages:
       type: string
       description: Possible success messages for job change detector
       enum:
@@ -2779,7 +2779,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
@@ -2817,16 +2817,34 @@
                 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 @@
                       - 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":