{ "openapi": "3.1.1", "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "info": { "title": "Wrangle Developer API", "summary": "People search, enrichment, credit visibility, and workspace polling for recruiting agents.", "description": "Wrangle exposes recruiting data and paid search/enrichment operations to API clients and agents.\nCreate API keys from the authenticated Wrangle developer settings.\n\n**Authorization boundary:** keys are issued for a personal or workspace billing context. Current developer API keys are not OAuth capability-scoped; a valid key can call the developer endpoints available to its context. Workspace collection and sequence reads still verify resource access on the server.\n\n**Billing and plan access:** search and enrichment can spend available trial or paid credits. Workspace polling additionally requires a paid plan or billing exemption; trial credits alone do not unlock it. Polling reads cost 5 credits per call and failed calls are refunded. Use the estimate and credit snapshot operations before paid calls when cost matters.", "termsOfService": "https://wrangle.ai/legal/terms-of-service", "contact": { "name": "Wrangle", "url": "https://wrangle.ai/developers" }, "version": "2026-09-29" }, "servers": [ { "url": "https://app.usewrangle.com", "description": "Production API" } ], "externalDocs": { "description": "Developer and Recruiting MCP overview", "url": "https://wrangle.ai/developers" }, "tags": [ { "name": "Search", "description": "Paid natural-language people search." }, { "name": "Enrichment", "description": "Paid LinkedIn and personal-email enrichment." }, { "name": "Credits", "description": "Read-only cost estimates and credit balances." }, { "name": "Collections", "description": "Read-only workspace collection polling. Requires a paid plan or billing exemption and costs 5 credits per call; failed calls are refunded." }, { "name": "Sequences", "description": "Read-only workspace outreach polling. Requires a paid plan or billing exemption and costs 5 credits per call; failed calls are refunded." } ], "security": [ { "xApiKey": [] }, { "bearerApiKey": [] } ], "paths": { "/api/developers/search": { "post": { "operationId": "peopleSearch", "tags": [ "Search" ], "summary": "Search for people from a natural-language recruiting brief", "description": "Each query can return 25–200 ranked profiles in every mode. Each candidate starts with the shared slim identity and current-role projection, followed by the backwards-compatible REST search fields, including summary, skills, experience, education, and evaluation. The requested limit is clamped into that range. Credits are charged for profiles actually returned; mode controls the per-profile cost. Omit connectorIds or send [] to search the base Wrangle dataset. In every mode, pass IDs from poll_connectors to search accessible networks, ATS, or library sources; collection connectorIds from collection reads are also accepted. Access is derived from the authenticated key. If any requested ID is unavailable to that account, the entire search falls back to the base dataset and meta.connectors.fallback is unavailable_connectors. Accessible but empty sources return no candidates.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional stable key for safely retrying a paid operation.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PeopleSearchRequest" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PeopleSearchResponse" } } } }, "400": { "description": "The request is malformed or contains unsupported values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The API key is missing, invalid, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "The account needs paid feature access, does not have enough credits, or reached a spend cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential cannot access this resource or requires a workspace key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "A request, concurrency, or provider rate limit was reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The request failed unexpectedly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Search is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/developers/poll_connectors": { "get": { "operationId": "poll_connectors", "tags": [ "Search" ], "summary": "List accessible search connectors", "description": "Free. Lists the base dataset (wrangle), personal network (network), workspace network (org-network), connected ATS, and accessible library/shared-network sources. Workspace network and ATS use the authenticated key’s bound workspace; personal/shared sources use the key owner’s access. Prepaid keys expose only wrangle. Saved collections are discovered through collection reads. Pass returned IDs to search.connectorIds. Counts may be null when unavailable; pagination bounds the response, not the underlying catalog lookup.", "parameters": [ { "name": "type", "in": "query", "schema": { "type": "string", "enum": [ "ats", "database", "your_network", "joint_network" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorsResponse" } } } }, "400": { "description": "The request is malformed or contains unsupported values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The API key is missing, invalid, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "A request, concurrency, or provider rate limit was reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The request failed unexpectedly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/developers/enrich/email": { "post": { "operationId": "enrichEmail", "tags": [ "Enrichment" ], "summary": "Find personal or work email addresses", "description": "Accepts LinkedIn URLs or Wrangle person IDs for up to 100 people. Supports personal and work email. Costs 5 credits per attempted person, including successful cache hits. Credits are refunded when no usable email is returned.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional stable key for safely retrying a paid operation.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailEnrichmentRequest" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailEnrichmentResponse" } } } }, "400": { "description": "The request is malformed or contains unsupported values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The API key is missing, invalid, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "The account needs paid feature access, does not have enough credits, or reached a spend cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential cannot access this resource or requires a workspace key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "A request, concurrency, or provider rate limit was reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The request failed unexpectedly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The enrichment provider failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Enrichment is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/developers/enrich/linkedin": { "post": { "operationId": "enrichLinkedIn", "tags": [ "Enrichment" ], "summary": "Enrich full LinkedIn profile data", "description": "Accepts one LinkedIn profile URL or an array of up to 50. Returns full normalized person, experience, education, and skills data. Billing is call-level: 0.25 credits per unique returned profile with a 5-credit minimum when at least one profile is returned. Calls returning no profiles release the full precharge.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional stable key for safely retrying a paid operation.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkedInEnrichmentRequest" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkedInEnrichmentResponse" } } } }, "400": { "description": "The request is malformed or contains unsupported values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The API key is missing, invalid, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "The account needs paid feature access, does not have enough credits, or reached a spend cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential cannot access this resource or requires a workspace key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No matching LinkedIn profile was found; charged credits are refunded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "A request, concurrency, or provider rate limit was reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The request failed unexpectedly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Enrichment is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/developers/estimate": { "post": { "operationId": "estimateCredits", "tags": [ "Credits" ], "summary": "Estimate credits before a paid operation", "description": "Read-only. Returns estimated credits, current balances, and whether the balance is sufficient.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditEstimateRequest" } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditEstimateResponse" } } } }, "400": { "description": "The request is malformed or contains unsupported values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The API key is missing, invalid, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "A request, concurrency, or provider rate limit was reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The request failed unexpectedly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/developers/credit_snapshot": { "get": { "operationId": "getCreditSnapshot", "tags": [ "Credits" ], "summary": "Read current API and MCP credit usage", "parameters": [ { "name": "surface", "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/CreditSurface" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditSnapshot" } } } }, "400": { "description": "The request is malformed or contains unsupported values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The API key is missing, invalid, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "A request, concurrency, or provider rate limit was reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The request failed unexpectedly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "postCreditSnapshot", "tags": [ "Credits" ], "summary": "Read current API and MCP credit usage", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "surface": { "$ref": "#/components/schemas/CreditSurface" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditSnapshot" } } } }, "400": { "description": "The request is malformed or contains unsupported values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The API key is missing, invalid, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "A request, concurrency, or provider rate limit was reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The request failed unexpectedly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/developers/collections": { "get": { "operationId": "listCollections", "tags": [ "Collections" ], "summary": "List collections visible to a workspace credential", "description": "Read-only operation. Requires a workspace key plus a paid plan or billing exemption; trial credits alone do not unlock polling. Returns owned plus project-shared collection metadata. Costs 5 credits per call; failed calls are refunded.", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "timeSince", "in": "query", "required": false, "description": "ISO 8601 date or datetime. Defaults to two months before the request.", "schema": { "oneOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionList" } } } }, "400": { "description": "The request is malformed or contains unsupported values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The API key is missing, invalid, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "The account needs paid feature access, does not have enough credits, or reached a spend cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential cannot access this resource or requires a workspace key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "A request, concurrency, or provider rate limit was reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The request failed unexpectedly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The service could not verify the required plan or is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/developers/collections/{collectionId}": { "get": { "operationId": "getCollection", "tags": [ "Collections" ], "summary": "Read collection metadata, analytics, and one candidate page", "description": "Requires a paid plan or billing exemption; trial credits alone do not unlock polling. Costs 5 credits per call; failed calls are refunded. Access is verified server-side. Candidate rows are ordered by added time. Pass the returned final-personId cursor to continue; the opaque pageToken remains accepted for compatibility.", "parameters": [ { "name": "collectionId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "ownerId", "in": "query", "required": false, "description": "Owner ID for a teammate collection shared through a project.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "Final personId returned by the previous page. Do not combine with pageToken.", "schema": { "type": "string" } }, { "name": "pageToken", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "addedAfter", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionDetail" } } } }, "400": { "description": "The request is malformed or contains unsupported values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The API key is missing, invalid, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "The account needs paid feature access, does not have enough credits, or reached a spend cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential cannot access this resource or requires a workspace key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The collection does not exist or is not available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "A request, concurrency, or provider rate limit was reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The request failed unexpectedly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The service could not verify the required plan or is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/developers/sequences": { "get": { "operationId": "listSequences", "tags": [ "Sequences" ], "summary": "List outreach sequences visible to a workspace credential", "description": "Read-only operation. Requires a workspace key plus a paid plan or billing exemption; trial credits alone do not unlock polling. Archived sequences are excluded. Costs 5 credits per call; failed calls are refunded.", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "timeSince", "in": "query", "required": false, "description": "ISO 8601 date or datetime. Defaults to two months before the request.", "schema": { "oneOf": [ { "type": "string", "format": "date" }, { "type": "string", "format": "date-time" } ] } }, { "name": "projectId", "in": "query", "required": false, "description": "Limit the result to one accessible project.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SequenceList" } } } }, "400": { "description": "The request is malformed or contains unsupported values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The API key is missing, invalid, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "The account needs paid feature access, does not have enough credits, or reached a spend cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential cannot access this resource or requires a workspace key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "A request, concurrency, or provider rate limit was reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The request failed unexpectedly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The service could not verify the required plan or is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/developers/sequences/{sequenceId}": { "get": { "operationId": "getSequence", "tags": [ "Sequences" ], "summary": "Read selected data scopes for one outreach sequence", "description": "Requires a paid plan or billing exemption; trial credits alone do not unlock polling. Costs 5 credits per call; failed calls are refunded. Defaults to metadata and up to 50 candidates with personId, name, and LinkedIn URL. Pass the returned final-personId cursor to continue. Query scopes select which response sections are returned; these are response data scopes, not API-key authorization scopes.", "parameters": [ { "name": "sequenceId", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "scopes", "in": "query", "required": false, "description": "Comma-separated response sections. Defaults to meta.", "schema": { "type": "string", "example": "meta,performance" } }, { "name": "full", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "recipient", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "statuses", "in": "query", "required": false, "description": "Comma-separated scheduled-action statuses.", "schema": { "type": "string" } }, { "name": "channel", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "all", "email", "linkedin" ], "default": "all" } }, { "name": "stepIndex", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "Final personId returned by the prior meta page. Requires meta and cannot be combined with offset.", "schema": { "type": "string" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "includeBodies", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "includeEvents", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "includeReplies", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SequenceDetail" } } } }, "400": { "description": "The request is malformed or contains unsupported values.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "The API key is missing, invalid, or revoked.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "The account needs paid feature access, does not have enough credits, or reached a spend cap.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The credential cannot access this resource or requires a workspace key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The sequence does not exist or is archived.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "A request, concurrency, or provider rate limit was reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The request failed unexpectedly.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The service could not verify the required plan or is temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "xApiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Wrangle API key beginning with `wrgl_`." }, "bearerApiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "Wrangle API key (wrgl_...)", "description": "The same Wrangle API key sent through the Authorization header." } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "code": { "type": [ "string", "null" ] }, "details": { "type": [ "object", "null" ], "additionalProperties": true }, "requestId": { "type": [ "string", "null" ] }, "failureId": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "CreditSurface": { "type": "string", "enum": [ "api", "mcp", "all" ], "default": "all" }, "SearchMode": { "type": "string", "enum": [ "turbo", "fast", "normal", "deep" ], "default": "fast" }, "PeopleSearchRequest": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 20000 }, "limit": { "type": "integer", "minimum": 25, "maximum": 200, "default": 50, "description": "Out-of-range values are clamped by the service." }, "mode": { "$ref": "#/components/schemas/SearchMode" }, "connectorIds": { "type": "array", "maxItems": 100, "items": { "type": "string", "minLength": 1, "maxLength": 512 }, "default": [], "description": "Supported in turbo, fast, normal, and deep. Omit or send [] for the base dataset. Use IDs from poll_connectors or collection reads; multiple accessible sources form a union. Including wrangle selects the base dataset. If any ID is unavailable, the entire REST search falls back to base and reports meta.connectors.fallback=unavailable_connectors. Empty accessible sources stay empty." }, "minimumMatchThreshold": { "type": "number", "default": 50, "deprecated": true, "description": "Accepted for compatibility and ignored. Put required criteria directly in query." }, "dedupe": { "type": "object", "properties": { "excludeIds": { "type": "array", "items": { "type": "string" }, "maxItems": 10000, "description": "Applied before retrieval. For more matches, repeat the query and connectorIds with cumulative candidate id values from previous responses. Use a new Idempotency-Key when exclusions change. Results remain relevance-ranked; this is not a full-network export or connection-date cursor." }, "excludeSavedOrHidden": { "type": "boolean" }, "excludeAccountSavedOrHidden": { "type": "boolean" }, "excludeHidden": { "type": "boolean" }, "excludeSaved": { "type": "boolean" }, "excludeShortlisted": { "type": "boolean" } }, "additionalProperties": false } }, "additionalProperties": false }, "Candidate": { "type": "object", "description": "Backwards-compatible REST search candidate with the shared slim projection first.", "properties": { "id": { "type": [ "string", "null" ] }, "personId": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "company": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] }, "headline": { "type": [ "string", "null" ] }, "linkedinUrl": { "type": [ "string", "null" ], "format": "uri" }, "linkedinUrlStable": { "type": [ "string", "null" ], "format": "uri" }, "summary": { "type": [ "string", "null" ] }, "skills": { "type": [ "array", "null" ], "items": { "type": "string" } }, "yearsExperience": { "type": [ "number", "null" ] }, "experience": { "type": [ "array", "null" ], "items": {} }, "education": { "type": [ "array", "null" ], "items": {} }, "matchScore": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100, "description": "0-100 search match score, rounded to two decimal places. Turbo/Fast/Normal use direct relevance scores from Jev or its fallback; Deep uses candidate rubric post-evaluation scores." } }, "additionalProperties": true }, "PeopleSearchResponse": { "type": "object", "required": [ "searchId", "query", "candidates", "totalCount", "creditsUsed", "creditBreakdown", "meta" ], "properties": { "searchId": { "type": "string", "format": "uuid" }, "query": { "type": "string" }, "candidates": { "type": "array", "items": { "$ref": "#/components/schemas/Candidate" } }, "totalCount": { "type": "integer", "minimum": 0 }, "creditsUsed": { "type": "number", "minimum": 0 }, "creditBreakdown": { "type": "object", "required": [ "plan" ], "properties": { "plan": { "type": "number", "minimum": 0 } } }, "meta": { "type": "object", "required": [ "projection", "candidateProjection" ], "properties": { "projection": { "type": "string", "const": "slim" }, "candidateProjection": { "type": "string", "const": "slim_plus_legacy_rest_v1" }, "connectors": { "type": [ "object", "null" ], "description": "Null when connectorIds is omitted or empty. Otherwise records the requested IDs and effective search scope.", "properties": { "requested": { "type": "array", "items": { "type": "string" } }, "selected": { "type": "array", "items": { "$ref": "#/components/schemas/SearchConnector" } }, "personIdCount": { "type": "integer", "minimum": 0 }, "unrestricted": { "type": "boolean" }, "fallback": { "type": "string", "const": "unavailable_connectors" } } } }, "additionalProperties": true } } }, "SearchConnector": { "type": "object", "required": [ "id", "rawId", "type", "name", "candidateCount", "active" ], "properties": { "id": { "type": "string" }, "rawId": { "type": "string" }, "type": { "type": "string", "enum": [ "ats", "database", "your_network", "joint_network", "collection" ] }, "name": { "type": "string" }, "candidateCount": { "type": [ "integer", "null" ], "minimum": 0 }, "candidateCountApproximate": { "type": "boolean" }, "active": { "type": "boolean" }, "provider": { "type": "string" } }, "additionalProperties": true }, "ConnectorsResponse": { "type": "object", "required": [ "connectors", "returned", "total", "offset", "limit", "nextOffset", "type", "creditsUsed" ], "properties": { "connectors": { "type": "array", "items": { "$ref": "#/components/schemas/SearchConnector" } }, "returned": { "type": "integer", "minimum": 0 }, "total": { "type": "integer", "minimum": 0 }, "offset": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "nextOffset": { "type": [ "integer", "null" ], "minimum": 0 }, "type": { "type": [ "string", "null" ], "enum": [ "ats", "database", "your_network", "joint_network", null ] }, "creditsUsed": { "type": "integer", "const": 0 } } }, "EmailEnrichmentRequest": { "type": "object", "properties": { "linkedinUrl": { "type": "string", "format": "uri" }, "linkedinUrls": { "type": "array", "maxItems": 100, "items": { "type": "string", "format": "uri" } }, "personId": { "type": "string" }, "personIds": { "type": "array", "maxItems": 100, "items": { "type": "string" } }, "candidateId": { "type": "string", "description": "Legacy single-value alias for personId." }, "emailType": { "type": "string", "enum": [ "personal", "work" ], "default": "personal" }, "currentCompany": { "type": "string", "maxLength": 300, "description": "Current company for work-email cache matching; omitted values are resolved from profile data." }, "currentCompanies": { "type": "array", "maxItems": 100, "items": { "type": "string", "maxLength": 300 }, "description": "Current companies aligned with the request targets." } }, "anyOf": [ { "required": [ "linkedinUrl" ] }, { "required": [ "linkedinUrls" ] }, { "required": [ "personId" ] }, { "required": [ "personIds" ] }, { "required": [ "candidateId" ] } ], "additionalProperties": false }, "LinkedInEnrichmentRequest": { "type": "object", "properties": { "linkedinUrl": { "type": "string", "format": "uri" }, "linkedinUrls": { "type": "array", "maxItems": 50, "items": { "type": "string", "format": "uri" } } }, "anyOf": [ { "required": [ "linkedinUrl" ] }, { "required": [ "linkedinUrls" ] } ], "additionalProperties": false }, "EnrichmentResult": { "type": "object", "properties": { "identifier": { "type": [ "string", "null" ] }, "identifierType": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "email": { "type": [ "string", "null" ], "format": "email" }, "profile": { "type": [ "object", "null" ], "additionalProperties": true }, "creditsUsed": { "type": "number", "minimum": 0 }, "refundedCredits": { "type": "number", "minimum": 0 } }, "additionalProperties": true }, "LinkedInProfile": { "type": "object", "required": [ "id", "personId", "linkedinUrl", "fullName", "experience", "education", "skills" ], "properties": { "id": { "type": "string" }, "personId": { "type": "string" }, "linkedinUrl": { "type": "string", "format": "uri" }, "linkedinUrlStable": { "type": [ "string", "null" ], "format": "uri" }, "fullName": { "type": [ "string", "null" ] }, "firstName": { "type": [ "string", "null" ] }, "lastName": { "type": [ "string", "null" ] }, "headline": { "type": [ "string", "null" ] }, "summary": { "type": [ "string", "null" ] }, "profilePicture": { "type": [ "string", "null" ], "format": "uri" }, "location": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "company": { "type": [ "string", "null" ] }, "yearsExperience": { "type": [ "number", "null" ] }, "experience": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "education": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "skills": { "type": "array", "items": { "type": "string" } }, "source": { "type": "string" } }, "additionalProperties": false }, "LinkedInEnrichmentResult": { "type": "object", "required": [ "identifier", "identifierType", "linkedinUrl", "status", "profile", "match" ], "properties": { "identifier": { "type": "string" }, "identifierType": { "type": "string", "const": "linkedinUrl" }, "linkedinUrl": { "type": "string", "format": "uri" }, "status": { "type": "string", "enum": [ "found", "not_found" ] }, "code": { "type": "string" }, "error": { "type": "string" }, "profile": { "anyOf": [ { "$ref": "#/components/schemas/LinkedInProfile" }, { "type": "null" } ] }, "match": { "type": [ "object", "null" ], "additionalProperties": true } }, "additionalProperties": false }, "EmailEnrichmentResponse": { "type": "object", "required": [ "requestId", "status", "results", "creditsUsed", "refundedCredits" ], "properties": { "requestId": { "type": "string" }, "status": { "type": "string", "enum": [ "found", "partial", "not_found", "bounced", "rate_limited", "error", "timeout" ] }, "emailType": { "type": "string", "enum": [ "personal", "work" ] }, "email": { "type": [ "string", "null" ], "format": "email" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/EnrichmentResult" } }, "creditsUsed": { "type": "number", "minimum": 0 }, "refundedCredits": { "type": "number", "minimum": 0 }, "creditBreakdown": { "type": "object", "additionalProperties": { "type": "number" } }, "meta": { "type": "object", "additionalProperties": true } }, "additionalProperties": true }, "LinkedInEnrichmentResponse": { "type": "object", "required": [ "requestId", "status", "results", "creditsUsed", "refundedCredits" ], "properties": { "requestId": { "type": "string" }, "status": { "type": "string", "enum": [ "found", "partial", "not_found" ] }, "profile": { "anyOf": [ { "$ref": "#/components/schemas/LinkedInProfile" }, { "type": "null" } ] }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedInEnrichmentResult" } }, "creditsUsed": { "type": "number", "minimum": 0 }, "refundedCredits": { "type": "number", "minimum": 0 }, "idempotentReplay": { "type": "boolean" }, "operationCredits": { "type": "number", "minimum": 0 }, "creditBreakdown": { "type": "object", "additionalProperties": { "type": "number" } }, "meta": { "type": "object", "additionalProperties": true } }, "additionalProperties": true }, "CreditEstimateRequest": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "search", "enrich", "enrich_email", "enrich_linkedin", "linkedin_enrich" ], "default": "search" }, "mode": { "$ref": "#/components/schemas/SearchMode" }, "limit": { "type": "integer", "minimum": 25, "maximum": 200, "default": 50 }, "count": { "type": "integer", "minimum": 1, "maximum": 100, "default": 1 }, "batchSize": { "type": "integer", "minimum": 1, "maximum": 100 }, "peopleCount": { "type": "integer", "minimum": 1, "maximum": 100 } }, "allOf": [ { "if": { "properties": { "type": { "enum": [ "enrich_linkedin", "linkedin_enrich" ] } }, "required": [ "type" ] }, "then": { "properties": { "count": { "maximum": 50 }, "batchSize": { "maximum": 50 }, "peopleCount": { "maximum": 50 } } } } ], "additionalProperties": false }, "CreditEstimateResponse": { "type": "object", "required": [ "estimatedCredits", "count", "sufficient", "shortfall", "balances", "pricing" ], "properties": { "estimatedCredits": { "type": "number", "minimum": 0 }, "breakdown": { "type": "object", "additionalProperties": { "type": "number" } }, "count": { "type": "integer", "minimum": 1 }, "sufficient": { "type": "boolean" }, "shortfall": { "type": "number", "minimum": 0 }, "balances": { "type": "object", "additionalProperties": true }, "pricing": { "type": "object", "additionalProperties": true } } }, "CreditSnapshot": { "type": "object", "required": [ "generatedAt", "requestedSurface", "surfaces" ], "properties": { "generatedAt": { "type": "string", "format": "date-time" }, "requestedSurface": { "$ref": "#/components/schemas/CreditSurface" }, "surfaces": { "type": "array", "items": { "type": "string", "enum": [ "api", "mcp" ] } }, "api": { "type": [ "object", "null" ], "additionalProperties": true }, "mcp": { "type": [ "object", "null" ], "additionalProperties": true } }, "additionalProperties": true }, "CollectionSummary": { "type": "object", "required": [ "collectionId", "ownerId", "name" ], "properties": { "collectionId": { "type": "string" }, "connectorId": { "type": [ "string", "null" ] }, "ownerId": { "type": "string" }, "ownedByViewer": { "type": "boolean" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "candidateCount": { "type": [ "integer", "null" ], "minimum": 0 }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "accessSource": { "type": [ "string", "null" ] }, "projectId": { "type": [ "string", "null" ] }, "projectName": { "type": [ "string", "null" ] }, "url": { "type": "string", "format": "uri" } }, "additionalProperties": true }, "CollectionList": { "type": "object", "required": [ "generatedAt", "collections", "totalCount", "returned", "hasMore", "limit", "offset" ], "properties": { "generatedAt": { "type": "string", "format": "date-time" }, "collections": { "type": "array", "items": { "$ref": "#/components/schemas/CollectionSummary" } }, "timeSince": { "type": "string", "format": "date-time" }, "totalCount": { "type": "integer", "minimum": 0 }, "returned": { "type": "integer", "minimum": 0 }, "hasMore": { "type": "boolean" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "creditsUsed": { "type": "number", "minimum": 0 }, "operationCredits": { "type": "number", "minimum": 0 }, "creditAccounting": { "type": "object", "additionalProperties": true } } }, "CollectionCandidate": { "type": "object", "description": "Fixed slim person projection plus collection workflow fields.", "properties": { "id": { "type": [ "string", "null" ] }, "candidateId": { "type": "string" }, "personId": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "company": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] }, "headline": { "type": [ "string", "null" ] }, "linkedinUrl": { "type": [ "string", "null" ], "format": "uri" }, "linkedinUrlStable": { "type": [ "string", "null" ], "format": "uri" }, "email": { "type": [ "string", "null" ], "format": "email" }, "stage": { "type": [ "string", "null" ] }, "matchScore": { "type": [ "number", "null" ] }, "addedAt": { "type": [ "string", "null" ], "format": "date-time" }, "url": { "type": [ "string", "null" ], "format": "uri" }, "columnValues": { "type": "object", "additionalProperties": true } }, "additionalProperties": true }, "CollectionDetail": { "type": "object", "required": [ "generatedAt", "collection", "analytics", "candidates", "totalCount", "returned" ], "properties": { "generatedAt": { "type": "string", "format": "date-time" }, "collection": { "$ref": "#/components/schemas/CollectionSummary" }, "analytics": { "type": "object", "additionalProperties": true }, "candidates": { "type": "array", "items": { "$ref": "#/components/schemas/CollectionCandidate" } }, "totalCount": { "type": "integer", "minimum": 0 }, "returned": { "type": "integer", "minimum": 0 }, "cursor": { "type": [ "string", "null" ] }, "nextCursor": { "type": [ "string", "null" ] }, "nextPageToken": { "type": [ "string", "null" ] }, "creditsUsed": { "type": "number", "minimum": 0 }, "operationCredits": { "type": "number", "minimum": 0 }, "creditAccounting": { "type": "object", "additionalProperties": true } } }, "SequenceSummary": { "type": "object", "required": [ "sequenceId", "name" ], "properties": { "sequenceId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "enabled": { "type": "boolean" }, "pausedReason": { "type": [ "string", "null" ] }, "ownerId": { "type": "string" }, "ownedByViewer": { "type": "boolean" }, "organizationId": { "type": [ "string", "null" ] }, "projectId": { "type": [ "string", "null" ] }, "createdAt": { "type": [ "string", "null" ], "format": "date-time" }, "updatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "recipientCount": { "type": "integer", "minimum": 0 }, "activeRecipients": { "type": "integer", "minimum": 0 }, "url": { "type": "string", "format": "uri" } }, "additionalProperties": true }, "SequenceList": { "type": "object", "required": [ "generatedAt", "sequences", "scope", "totalCount", "returned", "hasMore", "limit", "offset" ], "properties": { "generatedAt": { "type": "string", "format": "date-time" }, "sequences": { "type": "array", "items": { "$ref": "#/components/schemas/SequenceSummary" } }, "scope": { "type": "object", "additionalProperties": true }, "timeSince": { "type": "string", "format": "date-time" }, "totalCount": { "type": "integer", "minimum": 0 }, "returned": { "type": "integer", "minimum": 0 }, "hasMore": { "type": "boolean" }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "creditsUsed": { "type": "number", "minimum": 0 }, "operationCredits": { "type": "number", "minimum": 0 }, "creditAccounting": { "type": "object", "additionalProperties": true } } }, "SequenceDetail": { "type": "object", "required": [ "generatedAt", "sequenceId", "scopes" ], "properties": { "generatedAt": { "type": "string", "format": "date-time" }, "sequenceId": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "meta", "copy", "steps", "performance", "recipients", "actions", "events", "replies", "full" ] } }, "cursor": { "type": [ "string", "null" ] }, "sequence": { "type": [ "object", "null" ], "additionalProperties": true }, "candidates": { "type": [ "object", "null" ], "additionalProperties": true }, "copy": { "type": [ "object", "null" ], "additionalProperties": true }, "steps": { "type": [ "object", "array", "null" ], "additionalProperties": true, "items": {} }, "performance": { "type": [ "object", "null" ], "additionalProperties": true }, "deliverability": { "type": [ "object", "null" ], "additionalProperties": true }, "recipients": { "type": [ "object", "null" ], "additionalProperties": true }, "actions": { "type": [ "object", "null" ], "additionalProperties": true }, "events": { "type": [ "object", "null" ], "additionalProperties": true }, "replies": { "type": [ "object", "null" ], "additionalProperties": true }, "creditsUsed": { "type": "number", "minimum": 0 }, "operationCredits": { "type": "number", "minimum": 0 }, "creditAccounting": { "type": "object", "additionalProperties": true } }, "additionalProperties": true } } } }