{"openapi":"3.1.0","info":{"title":"Instalent Integrator API","version":"1.0.0","description":"Search, enrich and analyse talent from your own platform. Every response is a strict allowlist: no vendor names, no raw payloads, no internal ids.\n\n## Authentication\n\nTwo keys. The integrator key identifies your platform and goes in the Authorization header on every call: `Authorization: Bearer ik_live_...`. The customer key identifies the end customer acting and goes in the `X-Customer-Key` header on data-plane calls (searches, enrichments, analyses, profiles). Control-plane calls (customers, plans, usage, webhook) take the integrator key only. Keys are shown once when minted; only a hash is stored.\n\n## Customers\n\nEach end customer has an individual Instalent account that you create with POST /customers.\n\nThe response to that call carries `customerKey`, and it is the only time the key exists in readable form: we store a hash and a twelve character prefix, and no endpoint can ever show it again. We keep it out of our own logs and our request ledger. Your side has to do the same. Do not log that response body, do not put it in an error report, and do not send it to a third party logging service. Store the key against your user record and use the rotate endpoint if you ever suspect it leaked.\n\n The account starts on a card-free trial with credits, receives no emails from us apart from Stripe receipts, and pays through a Stripe Checkout link you request with POST /customers/{id}/checkout-sessions. While a pending session for the same price exists, that call returns it again (200) instead of creating a second one, so retries are safe. Plan changes and cancellations go through the Billing Portal link. Credit top-ups use POST /customers/{id}/credit-checkout.\n\nReturn addresses (where we send the customer's browser afterwards) must be https on a domain Instalent has allowed for you, with one exception for development: a loopback address always works, with or without TLS. `http://localhost:3000/billing/done`, `http://127.0.0.1:5173/done` and the IPv6 form are all accepted, on any port, even before any domain has been allowed for you. That means you can build and test the whole payment flow against your own machine without a tunnel. It is safe because a loopback address only ever resolves on the browser's own computer. Webhooks are different and have no such exception: we have to reach those from our servers, so they must be a public https URL.\n\n## Jobs\n\nSearch, enrichment and analysis are durable jobs. A create call returns 202 with a job id and links. Consume the outcome any way you like: poll the job, open the SSE event stream, receive the signed webhook, or page the results once the job is done. Send an `Idempotency-Key` header on creates: a retried request returns the original job with 200 (even if your caps or balance would now reject a new job), and a key reused for a different job family is refused with 409 idempotency_key_reused.\n\nSearch accepts structured criteria only (titles, locations, optional industries, skills, companies, keywords and a minimum experience). Enrichment takes profile ids from your own searches plus the contact fields wanted (email, phone, linkedin); a contact field appears on a profile only once it has been unlocked.\n\nFor people who never came from our search, POST /enrichments/by-identifier takes IDENTIFIERS instead of profile ids. An identifier is something that points at a real person well enough for us to find them. There are three kinds:\n\n- `{\"type\": \"linkedin\", \"value\": \"https://www.linkedin.com/in/jane-doe\"}`\n- `{\"type\": \"email\", \"value\": \"jane@acme.com\"}`\n- `{\"type\": \"name\", \"value\": \"Jane Doe\", \"company\": \"Acme\"}`\n\nSend each person as `{\"ref\": \"your-own-key\", \"identifiers\": [ ... ]}`, up to a hundred people at a time, and ask for the same three fields the other route takes. A person may carry all three kinds at once; send every kind you hold and we decide the order to try them in. Sending two of the same kind for one person is refused, so we never have to guess which you meant.\n\nLinkedIn is the strongest identifier and email the next: either one pins the person to a single record, so asking for that person again reuses what we already paid a vendor for and costs you nothing the second time. A name with a company pins nobody, so that person is looked up, and paid for, on every call. The create response tells you which is which per person with `repeatLookupIsFree`.\n\nA phone number is not an identifier. No vendor can find a person from a phone number, so we refuse it rather than quietly ignoring it. You can still ASK for a phone as a field; you just cannot identify someone by one.\n\nEvery event and every result row carries your `ref` back. Omit it and we number them p1, p2 and so on. Asking for a field you already sent as an identifier costs nothing: we answer it from your own value, the result reads `provided`, and no vendor is called. It creates an ordinary enrichment job, so everything after the create is the route you already use. Analysis takes profile ids plus up to twenty criteria strings and returns a score, a per-criterion breakdown and a summary.\n\n## Credits and limits\n\nEach job checks the customer's plan and credit balance before it is accepted. A 402 carries the exact shortfall; a 403 plan_required means the customer needs a plan; a 429 with plan_limit_reached or too_many_running_jobs tells you which cap was hit. Request rate limits are per integrator and per customer; the X-RateLimit headers on every response show the remaining budget.\n\nOne budget covers everything a customer does: creating jobs, polling their status and paging their results all draw on the same 120 requests per minute. Polling every two seconds costs 30 of those per job per minute, so four jobs in flight will exhaust the budget on status checks alone. Poll no faster than once every five seconds, back off as a job runs longer, and prefer the event stream or the webhook when you want to know the moment a job finishes. Read `X-RateLimit-Remaining` and slow down before it reaches zero rather than waiting for the 429.\n\n## Webhooks\n\nSet an https URL with PUT /webhook. Every event is POSTed as JSON with an `X-Instalent-Event-Id` header, which is stable across retries so you can use it to deduplicate, and an `X-Instalent-Delivery-Attempt` header counting from 1.\n\n**Your signing secret.** We issue one when your account is created and send it to you at onboarding; POST /webhook/rotate-secret returns a fresh one, shown once, and takes effect immediately. Events carry an `X-Instalent-Signature` header of the form `t=<unix seconds>,v1=<hex hmac>`. Verify by computing HMAC-SHA256 over `<t>.<raw body>` with your signing secret and comparing it to v1 in constant time; reject timestamps older than five minutes.\n\nVerifying is your choice, not a condition of delivery: the secret exists so you can confirm a call really came from us. If your account has no secret, events are delivered without the signature header rather than held back. We strongly recommend verifying in production, since your endpoint is a public URL and anyone who learns it could otherwise post to it.\n\nDeliveries retry on a fixed schedule - 1 minute, 5 minutes, 30 minutes, 2 hours, 8 hours, then 24 hours, so seven attempts over about 35 hours. Any response outside 2xx counts as a failure, including a redirect, which we never follow; each attempt times out after 10 seconds. After the last attempt the delivery is marked dead and can be redelivered by support. Twenty consecutive failures mark your endpoint failing, which shows on GET /me and GET /webhook; any success clears it. Webhooks are never the only route to a result: every job can be polled or streamed instead.\n\n## Webhook events\n\nThere is **no subscription model**: every event below is sent to your endpoint. Switch on `type` and ignore the ones you do not handle - new event types are added over time and must not break your handler.\n\nEvery event shares one envelope. `customerId` is null on account-level events such as `webhook.test`:\n\n```json\n{\n  \"id\": \"evt_1a2b3c4d5e6f7g8h\",\n  \"type\": \"customer.created\",\n  \"createdAt\": \"2026-09-24T21:12:20.193Z\",\n  \"integratorId\": \"int_WqkgLlggVEtqFKAsEY7K3PSBW0DCmWhp\",\n  \"customerId\": \"cus_uaWT1cG1DbcEJM6FgXKmWoQ3GTNNhmqJ\",\n  \"data\": {\n    \"…\": \"per-event, see below\"\n  }\n}\n```\n\nThe `data` object differs per event. The payloads below are illustrative, not a contract: `customer.updated` echoes whatever you sent, and a job `summary` differs per job kind. Read the fields you need and tolerate the rest.\n\n### Webhook events\n\n**`webhook.test`** - You press Send test event, or call POST /webhook/test. Carries no customer.\n\n```json\n{\n  \"message\": \"Hello from Instalent\"\n}\n```\n\n### Customer events\n\n**`customer.created`** - A customer is provisioned through POST /customers.\n\n```json\n{\n  \"customerId\": \"cus_uaWT1cG1DbcEJM6FgXKmWoQ3GTNNhmqJ\",\n  \"externalRef\": \"your-own-id-001\",\n  \"email\": \"person@company.com\",\n  \"trialGranted\": true\n}\n```\n\n**`customer.updated`** - PATCH /customers/{id} succeeds. Echoes the fields you sent, nothing more.\n\n```json\n{\n  \"name\": \"New Name\",\n  \"externalRef\": \"your-own-id-002\"\n}\n```\n\n**`customer.suspended`** - The customer's API access is turned off, by you, or by us. `by` is present only when we did it.\n\n```json\n{\n  \"by\": \"admin\"\n}\n```\n\n**`customer.unsuspended`** - The customer's API access is restored.\n\n```json\n{\n  \"by\": \"admin\"\n}\n```\n\n### Trial events\n\n**`trial.started`** - A new customer's free trial begins.\n\n```json\n{\n  \"variant\": \"standard\",\n  \"days\": 14,\n  \"credits\": 1000,\n  \"endsAt\": \"2026-10-08T21:12:20.955Z\"\n}\n```\n\n**`trial.ending`** - The trial is close to its end, your cue to prompt the customer to convert.\n\n```json\n{\n  \"trialEndsAt\": \"2026-10-08T21:12:20.955Z\"\n}\n```\n\n**`trial.ended`** - The trial ran out without converting. The customer keeps their account and loses plan access.\n\n```json\n{\n  \"previousPlan\": \"basic\"\n}\n```\n\n### Billing events\n\n**`checkout.completed`** - A customer finished Stripe checkout for a plan.\n\n```json\n{\n  \"plan\": \"basic\",\n  \"durationMonths\": 1,\n  \"stripeSessionId\": \"cs_test_a1b2c3\"\n}\n```\n\n**`subscription.activated`** - A paid subscription starts.\n\n```json\n{\n  \"subscriptionId\": \"sub_1a2b3c\"\n}\n```\n\n**`subscription.updated`** - The plan or its billing status changes, including renewals.\n\n```json\n{\n  \"plan\": \"pro\",\n  \"status\": \"active\",\n  \"invoiceId\": \"in_1a2b3c\"\n}\n```\n\n**`subscription.cancelled`** - The subscription is cancelled. The customer drops to the free plan.\n\n```json\n{\n  \"subscriptionId\": \"sub_1a2b3c\",\n  \"previousPlan\": \"pro\"\n}\n```\n\n**`subscription.expired`** - A paid plan lapsed without renewing.\n\n```json\n{\n  \"previousPlan\": \"pro\"\n}\n```\n\n**`payment.failed`** - Stripe could not collect a payment. Access continues while Stripe retries.\n\n```json\n{\n  \"invoiceId\": \"in_1a2b3c\"\n}\n```\n\n**`credits.allocated`** - A billing cycle granted the plan's monthly credits.\n\n```json\n{\n  \"plan\": \"basic\",\n  \"invoiceId\": \"in_1a2b3c\"\n}\n```\n\n**`credits.topped_up`** - A customer bought extra credits outside their plan.\n\n```json\n{\n  \"credits\": 5000\n}\n```\n\n### Search job events\n\n**`search.completed`** - A search job finished. Page GET /searches/{id}/results for the profiles.\n\n```json\n{\n  \"jobId\": \"job_1a2b3c4d\",\n  \"summary\": {\n    \"totalResults\": 120,\n    \"stoppedEarly\": false,\n    \"creditsCharged\": 12\n  }\n}\n```\n\n**`search.failed`** - The job stopped on an error. `summary.partial` marks work already charged for.\n\n```json\n{\n  \"jobId\": \"job_1a2b3c4d\",\n  \"error\": \"vendor_unavailable\",\n  \"summary\": {\n    \"partial\": true\n  }\n}\n```\n\n**`search.cancelled`** - You cancelled the job. `cancelledBeforeStart` means it never ran.\n\n```json\n{\n  \"jobId\": \"job_1a2b3c4d\",\n  \"summary\": {\n    \"cancelledBeforeStart\": true\n  }\n}\n```\n\n### Enrichment job events\n\n**`enrichment.completed`** - An enrichment job finished, from either /enrichments route.\n\n```json\n{\n  \"jobId\": \"job_2b3c4d5e\",\n  \"summary\": {\n    \"requested\": 50,\n    \"found\": 41,\n    \"notFound\": 8,\n    \"errors\": 1,\n    \"byField\": {\n      \"email\": {\n        \"found\": 41,\n        \"notFound\": 8,\n        \"errors\": 1\n      }\n    },\n    \"stoppedEarly\": false,\n    \"creditsCharged\": 123\n  }\n}\n```\n\n**`enrichment.failed`** - The job stopped on an error.\n\n```json\n{\n  \"jobId\": \"job_2b3c4d5e\",\n  \"error\": \"insufficient_credits\",\n  \"summary\": {\n    \"partial\": true\n  }\n}\n```\n\n**`enrichment.cancelled`** - You cancelled the job.\n\n```json\n{\n  \"jobId\": \"job_2b3c4d5e\",\n  \"summary\": {\n    \"cancelledBeforeStart\": false\n  }\n}\n```\n\n### Analysis job events\n\n**`analysis.completed`** - An analysis job finished. Page GET /analyses/{id}/results for the scores.\n\n```json\n{\n  \"jobId\": \"job_3c4d5e6f\",\n  \"summary\": {\n    \"analyzed\": 40,\n    \"avgScore\": 72.5,\n    \"errors\": 0,\n    \"erroredProfileIds\": [],\n    \"chargedProfileIds\": [\n      \"prof_1\",\n      \"prof_2\"\n    ],\n    \"stoppedEarly\": false,\n    \"creditsCharged\": 20\n  }\n}\n```\n\n**`analysis.failed`** - The job stopped on an error.\n\n```json\n{\n  \"jobId\": \"job_3c4d5e6f\",\n  \"error\": \"model_unavailable\",\n  \"summary\": {\n    \"partial\": true\n  }\n}\n```\n\n**`analysis.cancelled`** - You cancelled the job, or it ran out of credits mid-run.\n\n```json\n{\n  \"jobId\": \"job_3c4d5e6f\",\n  \"summary\": {\n    \"stoppedEarly\": true,\n    \"stoppedReason\": \"insufficient_credits\"\n  }\n}\n```\n\n\n## Attribution\n\nYour agreement asks you to show that search is powered by Instalent, wherever your users search. We host the badge, so one paste does it and the artwork stays current without you redeploying. Take whichever matches your background.\n\nOn a light background:\n\n```html\n<a href=\"https://instalent.io\" target=\"_blank\" rel=\"noopener\">\n  <img src=\"https://instalent.io/badge/powered-by-instalent-on-light.png\" alt=\"Powered by Instalent\" height=\"36\" />\n</a>\n```\n\nOn a dark background:\n\n```html\n<a href=\"https://instalent.io\" target=\"_blank\" rel=\"noopener\">\n  <img src=\"https://instalent.io/badge/powered-by-instalent-on-dark.png\" alt=\"Powered by Instalent\" height=\"36\" />\n</a>\n```\n\nBoth are PNG at twice the displayed size, so they stay sharp on high density screens. Your dashboard carries the same two snippets with a JSX variant and a live preview.\n\n## Errors\n\nEvery error has the same shape: an object with code, message, field, hint, details and requestId. Quote the requestId when you contact support."},"servers":[{"url":"/api/v1"}],"components":{"securitySchemes":{"integratorKey":{"type":"http","scheme":"bearer","description":"Your integrator key (ik_live_...) in the Authorization header"},"customerKey":{"type":"apiKey","in":"header","name":"X-Customer-Key","description":"The acting customer's key (ck_live_...)"}}},"paths":{"/me":{"get":{"summary":"Your integrator profile","security":[{"integratorKey":[]}],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"status":{"type":"string"},"billingMode":{"type":"string"},"trialDays":{"type":"number"},"webhook":{"type":"object","properties":{"url":{"type":["string","null"]},"status":{"type":"string"}}},"allowedReturnDomains":{"type":"array","items":{"type":"string"}},"rateLimits":{"type":["object","null"]}}}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":["string","null"]},"hint":{"type":["string","null"]},"details":{"type":["object","null"]},"requestId":{"type":"string"}},"required":["code","message","requestId"]}}}}}}}}},"/plans":{"get":{"summary":"Plans and prices","security":[{"integratorKey":[]}],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","enum":["basic","explorer","pro"]},"name":{"type":"string"},"prices":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"interval":{"type":"string","enum":["month","year"]},"amountCents":{"type":"number"},"currency":{"type":"string"}}}},"monthlyCredits":{"type":"number"},"limits":{"type":"object","properties":{"searchesMonthly":{"type":"number"},"searchesDaily":{"type":"number"}}}}}},"trialDays":{"type":"number"}}}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":["string","null"]},"hint":{"type":["string","null"]},"details":{"type":["object","null"]},"requestId":{"type":"string"}},"required":["code","message","requestId"]}}}}}}}}},"/credit-packages":{"get":{"summary":"Credit top-up packages","security":[{"integratorKey":[]}],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"credits":{"type":"number"},"discountPercent":{"type":"number"},"priceUsd":{"type":"number"}}}}}}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":["string","null"]},"hint":{"type":["string","null"]},"details":{"type":["object","null"]},"requestId":{"type":"string"}},"required":["code","message","requestId"]}}}}}}}}},"/customers":{"post":{"summary":"Create a customer","description":"Creates the customer's Instalent account and returns the customer with its key (customerKey) once. No email is sent to the customer.","security":[{"integratorKey":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","maxLength":254,"format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"name":{"type":"string"},"externalRef":{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]+$"},"acceptedTerms":{"type":"boolean","const":true}},"required":["email","name","acceptedTerms"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"customer":{"type":"object","properties":{"id":{"type":"string"},"externalRef":{"anyOf":[{"type":"string"},{"type":"null"}]},"email":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"createdAt":{"type":"string"},"plan":{"type":"object","properties":{"name":{"type":"string"},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"type":"string"},"trialEndsAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"expiresAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"billingHealth":{"type":"string"},"hasStripeSubscription":{"type":"boolean"}},"required":["name","status","source","trialEndsAt","expiresAt","billingHealth","hasStripeSubscription"],"additionalProperties":false},"credits":{"type":"object","properties":{"total":{"type":"number"},"monthly":{"type":"number"},"rollover":{"type":"number"},"topUp":{"type":"number"},"periodEnd":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["total","monthly","rollover","topUp","periodEnd"],"additionalProperties":false},"limits":{"type":"object","properties":{"searchesMonthly":{"type":"object","properties":{"used":{"type":"number"},"limit":{"type":"number"}},"required":["used","limit"],"additionalProperties":false},"searchesDaily":{"type":"object","properties":{"used":{"type":"number"},"limit":{"type":"number"}},"required":["used","limit"],"additionalProperties":false}},"required":["searchesMonthly","searchesDaily"],"additionalProperties":false},"keys":{"type":"object","properties":{"current":{"anyOf":[{"type":"object","properties":{"prefix":{"type":"string"},"createdAt":{"type":"string"}},"required":["prefix","createdAt"],"additionalProperties":false},{"type":"null"}]},"previous":{"anyOf":[{"type":"object","properties":{"prefix":{"type":"string"},"expiresAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["prefix","expiresAt"],"additionalProperties":false},{"type":"null"}]}},"required":["current","previous"],"additionalProperties":false}},"required":["id","externalRef","email","name","status","createdAt","plan","credits","limits","keys"],"additionalProperties":false},"customerKey":{"type":"string"},"trial":{"type":["object","null"],"properties":{"status":{"type":"string"},"endsAt":{"type":["string","null"]},"credits":{"type":["number","null"]}}},"trialReason":{"type":["string","null"]}}}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":["string","null"]},"hint":{"type":["string","null"]},"details":{"type":["object","null"]},"requestId":{"type":"string"}},"required":["code","message","requestId"]}}}}}}}},"get":{"summary":"List customers","security":[{"integratorKey":[]}],"parameters":[{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque cursor from a previous response"},{"name":"limit","in":"query","required":false,"schema":{"type":"string"},"description":"1 to 200, default 50"},{"name":"externalRef","in":"query","required":false,"schema":{"type":"string"},"description":"Filter by your own reference"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"externalRef":{"anyOf":[{"type":"string"},{"type":"null"}]},"email":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"createdAt":{"type":"string"},"plan":{"type":"object","properties":{"name":{"type":"string"},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"type":"string"},"trialEndsAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"expiresAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"billingHealth":{"type":"string"},"hasStripeSubscription":{"type":"boolean"}},"required":["name","status","source","trialEndsAt","expiresAt","billingHealth","hasStripeSubscription"],"additionalProperties":false},"credits":{"type":"object","properties":{"total":{"type":"number"},"monthly":{"type":"number"},"rollover":{"type":"number"},"topUp":{"type":"number"},"periodEnd":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["total","monthly","rollover","topUp","periodEnd"],"additionalProperties":false},"limits":{"type":"object","properties":{"searchesMonthly":{"type":"object","properties":{"used":{"type":"number"},"limit":{"type":"number"}},"required":["used","limit"],"additionalProperties":false},"searchesDaily":{"type":"object","properties":{"used":{"type":"number"},"limit":{"type":"number"}},"required":["used","limit"],"additionalProperties":false}},"required":["searchesMonthly","searchesDaily"],"additionalProperties":false},"keys":{"type":"object","properties":{"current":{"anyOf":[{"type":"object","properties":{"prefix":{"type":"string"},"createdAt":{"type":"string"}},"required":["prefix","createdAt"],"additionalProperties":false},{"type":"null"}]},"previous":{"anyOf":[{"type":"object","properties":{"prefix":{"type":"string"},"expiresAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["prefix","expiresAt"],"additionalProperties":false},{"type":"null"}]}},"required":["current","previous"],"additionalProperties":false}},"required":["id","externalRef","email","name","status","createdAt","plan","credits","limits","keys"],"additionalProperties":false}},"nextCursor":{"type":["string","null"]}}}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":["string","null"]},"hint":{"type":["string","null"]},"details":{"type":["object","null"]},"requestId":{"type":"string"}},"required":["code","message","requestId"]}}}}}}}}},"/customers/{id}":{"get":{"summary":"Get a customer","security":[{"integratorKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"externalRef":{"anyOf":[{"type":"string"},{"type":"null"}]},"email":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"createdAt":{"type":"string"},"plan":{"type":"object","properties":{"name":{"type":"string"},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"type":"string"},"trialEndsAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"expiresAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"billingHealth":{"type":"string"},"hasStripeSubscription":{"type":"boolean"}},"required":["name","status","source","trialEndsAt","expiresAt","billingHealth","hasStripeSubscription"],"additionalProperties":false},"credits":{"type":"object","properties":{"total":{"type":"number"},"monthly":{"type":"number"},"rollover":{"type":"number"},"topUp":{"type":"number"},"periodEnd":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["total","monthly","rollover","topUp","periodEnd"],"additionalProperties":false},"limits":{"type":"object","properties":{"searchesMonthly":{"type":"object","properties":{"used":{"type":"number"},"limit":{"type":"number"}},"required":["used","limit"],"additionalProperties":false},"searchesDaily":{"type":"object","properties":{"used":{"type":"number"},"limit":{"type":"number"}},"required":["used","limit"],"additionalProperties":false}},"required":["searchesMonthly","searchesDaily"],"additionalProperties":false},"keys":{"type":"object","properties":{"current":{"anyOf":[{"type":"object","properties":{"prefix":{"type":"string"},"createdAt":{"type":"string"}},"required":["prefix","createdAt"],"additionalProperties":false},{"type":"null"}]},"previous":{"anyOf":[{"type":"object","properties":{"prefix":{"type":"string"},"expiresAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["prefix","expiresAt"],"additionalProperties":false},{"type":"null"}]}},"required":["current","previous"],"additionalProperties":false}},"required":["id","externalRef","email","name","status","createdAt","plan","credits","limits","keys"],"additionalProperties":false}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":["string","null"]},"hint":{"type":["string","null"]},"details":{"type":["object","null"]},"requestId":{"type":"string"}},"required":["code","message","requestId"]}}}}}}}},"patch":{"summary":"Update a customer","security":[{"integratorKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"externalRef":{"anyOf":[{"type":"string","minLength":1,"maxLength":128,"pattern":"^[A-Za-z0-9._:-]+$"},{"type":"null"}]}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"externalRef":{"anyOf":[{"type":"string"},{"type":"null"}]},"email":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"createdAt":{"type":"string"},"plan":{"type":"object","properties":{"name":{"type":"string"},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"type":"string"},"trialEndsAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"expiresAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"billingHealth":{"type":"string"},"hasStripeSubscription":{"type":"boolean"}},"required":["name","status","source","trialEndsAt","expiresAt","billingHealth","hasStripeSubscription"],"additionalProperties":false},"credits":{"type":"object","properties":{"total":{"type":"number"},"monthly":{"type":"number"},"rollover":{"type":"number"},"topUp":{"type":"number"},"periodEnd":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["total","monthly","rollover","topUp","periodEnd"],"additionalProperties":false},"limits":{"type":"object","properties":{"searchesMonthly":{"type":"object","properties":{"used":{"type":"number"},"limit":{"type":"number"}},"required":["used","limit"],"additionalProperties":false},"searchesDaily":{"type":"object","properties":{"used":{"type":"number"},"limit":{"type":"number"}},"required":["used","limit"],"additionalProperties":false}},"required":["searchesMonthly","searchesDaily"],"additionalProperties":false},"keys":{"type":"object","properties":{"current":{"anyOf":[{"type":"object","properties":{"prefix":{"type":"string"},"createdAt":{"type":"string"}},"required":["prefix","createdAt"],"additionalProperties":false},{"type":"null"}]},"previous":{"anyOf":[{"type":"object","properties":{"prefix":{"type":"string"},"expiresAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["prefix","expiresAt"],"additionalProperties":false},{"type":"null"}]}},"required":["current","previous"],"additionalProperties":false}},"required":["id","externalRef","email","name","status","createdAt","plan","credits","limits","keys"],"additionalProperties":false}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":["string","null"]},"hint":{"type":["string","null"]},"details":{"type":["object","null"]},"requestId":{"type":"string"}},"required":["code","message","requestId"]}}}}}}}}},"/customers/{id}/suspend":{"post":{"summary":"Suspend API access","security":[{"integratorKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"externalRef":{"anyOf":[{"type":"string"},{"type":"null"}]},"email":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"createdAt":{"type":"string"},"plan":{"type":"object","properties":{"name":{"type":"string"},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"type":"string"},"trialEndsAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"expiresAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"billingHealth":{"type":"string"},"hasStripeSubscription":{"type":"boolean"}},"required":["name","status","source","trialEndsAt","expiresAt","billingHealth","hasStripeSubscription"],"additionalProperties":false},"credits":{"type":"object","properties":{"total":{"type":"number"},"monthly":{"type":"number"},"rollover":{"type":"number"},"topUp":{"type":"number"},"periodEnd":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["total","monthly","rollover","topUp","periodEnd"],"additionalProperties":false},"limits":{"type":"object","properties":{"searchesMonthly":{"type":"object","properties":{"used":{"type":"number"},"limit":{"type":"number"}},"required":["used","limit"],"additionalProperties":false},"searchesDaily":{"type":"object","properties":{"used":{"type":"number"},"limit":{"type":"number"}},"required":["used","limit"],"additionalProperties":false}},"required":["searchesMonthly","searchesDaily"],"additionalProperties":false},"keys":{"type":"object","properties":{"current":{"anyOf":[{"type":"object","properties":{"prefix":{"type":"string"},"createdAt":{"type":"string"}},"required":["prefix","createdAt"],"additionalProperties":false},{"type":"null"}]},"previous":{"anyOf":[{"type":"object","properties":{"prefix":{"type":"string"},"expiresAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["prefix","expiresAt"],"additionalProperties":false},{"type":"null"}]}},"required":["current","previous"],"additionalProperties":false}},"required":["id","externalRef","email","name","status","createdAt","plan","credits","limits","keys"],"additionalProperties":false}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":["string","null"]},"hint":{"type":["string","null"]},"details":{"type":["object","null"]},"requestId":{"type":"string"}},"required":["code","message","requestId"]}}}}}}}}},"/customers/{id}/unsuspend":{"post":{"summary":"Restore API access","security":[{"integratorKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"externalRef":{"anyOf":[{"type":"string"},{"type":"null"}]},"email":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"createdAt":{"type":"string"},"plan":{"type":"object","properties":{"name":{"type":"string"},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"type":"string"},"trialEndsAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"expiresAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"billingHealth":{"type":"string"},"hasStripeSubscription":{"type":"boolean"}},"required":["name","status","source","trialEndsAt","expiresAt","billingHealth","hasStripeSubscription"],"additionalProperties":false},"credits":{"type":"object","properties":{"total":{"type":"number"},"monthly":{"type":"number"},"rollover":{"type":"number"},"topUp":{"type":"number"},"periodEnd":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["total","monthly","rollover","topUp","periodEnd"],"additionalProperties":false},"limits":{"type":"object","properties":{"searchesMonthly":{"type":"object","properties":{"used":{"type":"number"},"limit":{"type":"number"}},"required":["used","limit"],"additionalProperties":false},"searchesDaily":{"type":"object","properties":{"used":{"type":"number"},"limit":{"type":"number"}},"required":["used","limit"],"additionalProperties":false}},"required":["searchesMonthly","searchesDaily"],"additionalProperties":false},"keys":{"type":"object","properties":{"current":{"anyOf":[{"type":"object","properties":{"prefix":{"type":"string"},"createdAt":{"type":"string"}},"required":["prefix","createdAt"],"additionalProperties":false},{"type":"null"}]},"previous":{"anyOf":[{"type":"object","properties":{"prefix":{"type":"string"},"expiresAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["prefix","expiresAt"],"additionalProperties":false},{"type":"null"}]}},"required":["current","previous"],"additionalProperties":false}},"required":["id","externalRef","email","name","status","createdAt","plan","credits","limits","keys"],"additionalProperties":false}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":["string","null"]},"hint":{"type":["string","null"]},"details":{"type":["object","null"]},"requestId":{"type":"string"}},"required":["code","message","requestId"]}}}}}}}}},"/customers/{id}/keys/rotate":{"post":{"summary":"Rotate the customer key","description":"Returns the new key once. The previous key keeps working for the grace period you pass (up to 72 hours).","security":[{"integratorKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"graceHours":{"type":"integer","minimum":0,"maximum":72}},"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"customerKey":{"type":"string"},"previousKeyValidUntil":{"type":["string","null"]}}}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":["string","null"]},"hint":{"type":["string","null"]},"details":{"type":["object","null"]},"requestId":{"type":"string"}},"required":["code","message","requestId"]}}}}}}}}},"/customers/{id}/keys/current":{"delete":{"summary":"Revoke the customer key","security":[{"integratorKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"revoked":{"type":"integer"}}}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":["string","null"]},"hint":{"type":["string","null"]},"details":{"type":["object","null"]},"requestId":{"type":"string"}},"required":["code","message","requestId"]}}}}}}}}},"/customers/{id}/usage":{"get":{"summary":"Customer usage by day","security":[{"integratorKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"from","in":"query","required":false,"schema":{"type":"string"},"description":"ISO date"},{"name":"to","in":"query","required":false,"schema":{"type":"string"},"description":"ISO date"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"},"data":{"type":"array","items":{"type":"object","properties":{"day":{"type":"string"},"requests":{"type":"number"},"searches":{"type":"number"},"enrichments":{"type":"number"},"analyses":{"type":"number"},"errors":{"type":"number"},"creditsCharged":{"type":"number"}}}}}}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":["string","null"]},"hint":{"type":["string","null"]},"details":{"type":["object","null"]},"requestId":{"type":"string"}},"required":["code","message","requestId"]}}}}}}}}},"/customers/{id}/credits":{"get":{"summary":"Customer credit transactions","security":[{"integratorKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque cursor from a previous response"},{"name":"limit","in":"query","required":false,"schema":{"type":"string"},"description":"1 to 200, default 50"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"amount":{"type":"number"},"pool":{"type":"string"},"description":{"type":["string","null"]},"createdAt":{"type":"string"}}}},"nextCursor":{"type":["string","null"]}}}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":["string","null"]},"hint":{"type":["string","null"]},"details":{"type":["object","null"]},"requestId":{"type":"string"}},"required":["code","message","requestId"]}}}}}}}}},"/customers/{id}/checkout-sessions":{"post":{"summary":"Create a Stripe Checkout link","description":"Returns a Checkout URL on our Stripe account for the plan chosen. Redirect the customer there; the return URLs must be on a domain allowed for your integration.","security":[{"integratorKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"priceId":{"type":"string","maxLength":40},"successUrl":{"type":"string","maxLength":2048,"format":"uri"},"cancelUrl":{"type":"string","maxLength":2048,"format":"uri"}},"required":["priceId"],"additionalProperties":false}}}},"responses":{"200":{"description":"Replayed: a pending session for this plan already exists and is returned unchanged.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":["string","null"]},"expiresAt":{"type":"string"},"replayed":{"type":"boolean"}}}}}},"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":["string","null"]},"expiresAt":{"type":"string"},"replayed":{"type":"boolean"}}}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":["string","null"]},"hint":{"type":["string","null"]},"details":{"type":["object","null"]},"requestId":{"type":"string"}},"required":["code","message","requestId"]}}}}}}}}},"/customers/{id}/checkout-sessions/{sid}":{"get":{"summary":"Checkout session status","security":[{"integratorKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"sid","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"paidAt":{"type":["string","null"]},"url":{"type":["string","null"]},"plan":{"type":"string"},"expiresAt":{"type":"string"}}}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":["string","null"]},"hint":{"type":["string","null"]},"details":{"type":["object","null"]},"requestId":{"type":"string"}},"required":["code","message","requestId"]}}}}}}}}},"/customers/{id}/billing-portal":{"post":{"summary":"Stripe Billing Portal link","security":[{"integratorKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"returnUrl":{"type":"string","maxLength":2048,"format":"uri"}},"required":["returnUrl"],"additionalProperties":false}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"}}}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":["string","null"]},"hint":{"type":["string","null"]},"details":{"type":["object","null"]},"requestId":{"type":"string"}},"required":["code","message","requestId"]}}}}}}}}},"/customers/{id}/credit-checkout":{"post":{"summary":"Credit top-up Checkout link","security":[{"integratorKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"packageId":{"type":"string","maxLength":40},"successUrl":{"type":"string","maxLength":2048,"format":"uri"},"cancelUrl":{"type":"string","maxLength":2048,"format":"uri"}},"required":["packageId","successUrl","cancelUrl"],"additionalProperties":false}}}},"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"sessionId":{"type":"string"}}}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":["string","null"]},"hint":{"type":["string","null"]},"details":{"type":["object","null"]},"requestId":{"type":"string"}},"required":["code","message","requestId"]}}}}}}}}},"/usage":{"get":{"summary":"Usage by day (all customers)","security":[{"integratorKey":[]}],"parameters":[{"name":"from","in":"query","required":false,"schema":{"type":"string"},"description":"ISO date"},{"name":"to","in":"query","required":false,"schema":{"type":"string"},"description":"ISO date"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"},"data":{"type":"array","items":{"type":"object","properties":{"day":{"type":"string"},"requests":{"type":"number"},"searches":{"type":"number"},"enrichments":{"type":"number"},"analyses":{"type":"number"},"errors":{"type":"number"},"creditsCharged":{"type":"number"}}}}}}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":["string","null"]},"hint":{"type":["string","null"]},"details":{"type":["object","null"]},"requestId":{"type":"string"}},"required":["code","message","requestId"]}}}}}}}}},"/webhook":{"get":{"summary":"Webhook configuration","security":[{"integratorKey":[]}],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":["string","null"]},"status":{"type":"string"},"consecutiveFailures":{"type":"integer"}}}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":["string","null"]},"hint":{"type":["string","null"]},"details":{"type":["object","null"]},"requestId":{"type":"string"}},"required":["code","message","requestId"]}}}}}}}},"put":{"summary":"Set the webhook URL","security":[{"integratorKey":[]}],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"}},"required":["url"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string"},"status":{"type":"string"}}}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":["string","null"]},"hint":{"type":["string","null"]},"details":{"type":["object","null"]},"requestId":{"type":"string"}},"required":["code","message","requestId"]}}}}}}}}},"/webhook/test":{"post":{"summary":"Send a test event","security":[{"integratorKey":[]}],"parameters":[],"responses":{"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"eventId":{"type":"string"},"status":{"type":"string"}}}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":["string","null"]},"hint":{"type":["string","null"]},"details":{"type":["object","null"]},"requestId":{"type":"string"}},"required":["code","message","requestId"]}}}}}}}}},"/webhook/rotate-secret":{"post":{"summary":"Rotate the signing secret","description":"Returns the new secret once. Takes effect immediately.","security":[{"integratorKey":[]}],"parameters":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"secret":{"type":"string"}}}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":["string","null"]},"hint":{"type":["string","null"]},"details":{"type":["object","null"]},"requestId":{"type":"string"}},"required":["code","message","requestId"]}}}}}}}}},"/searches":{"post":{"summary":"Create a search job","description":"Queues the job and returns 202. Poll GET /searches/{id}, stream GET /searches/{id}/events, or wait for the search.completed webhook, then page GET /searches/{id}/results.","security":[{"integratorKey":[],"customerKey":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"8 to 128 characters. A retry with the same key returns the original job."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"default":"candidate","type":"string","enum":["candidate","client"]},"criteria":{"type":"object","properties":{"titles":{"description":"Every title is searched exactly as given; none is added or rephrased.","maxItems":5,"type":"array","items":{"type":"string"}},"locations":{"maxItems":5,"type":"array","items":{"type":"string"}},"industries":{"maxItems":5,"type":"array","items":{"type":"string"}},"skills":{"maxItems":15,"type":"array","items":{"type":"string"}},"companies":{"maxItems":10,"type":"array","items":{"type":"string"}},"keywords":{"type":"string"},"experience":{"type":"object","properties":{"min":{"type":"integer","minimum":0,"maximum":60}},"required":["min"],"additionalProperties":false}},"required":["titles","locations"],"additionalProperties":false},"openToWork":{"description":"Has no effect since 2026-10-06 (still accepted): open to work is not a search option. Every result carries `openToWork` instead, read from the person's profile: true when they say they are looking, or hold no job and the last one ended within two years; null otherwise. Never false: nobody can tell that a person is not looking.","type":"boolean"},"maxResults":{"description":"An upper bound, not a target. Candidate searches return only people who closely match the criteria, typically about 85 to 115 for a specific role and city, so a higher value rarely returns more.","type":"integer","minimum":1,"maximum":1000}},"required":["criteria"],"additionalProperties":false}}}},"responses":{"200":{"description":"Replayed: this Idempotency-Key already created a job, so the original is returned.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["search","enrichment","analysis"]},"status":{"type":"string","enum":["queued","running","succeeded","failed","cancelled"]},"input":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"progress":{"anyOf":[{"type":"object","properties":{"phase":{"type":"string"},"current":{"type":"number"},"total":{"type":"number"}}},{"type":"null"}]},"summary":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message"]},{"type":"null"}]},"createdAt":{"type":"string"},"startedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"links":{"type":"object","properties":{"self":{"type":"string"},"results":{"type":"string"},"events":{"type":"string"},"cancel":{"type":"string"}}}},"required":["id","kind","status","input","progress","summary","error","createdAt","startedAt","finishedAt"],"additionalProperties":false}}}},"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["search","enrichment","analysis"]},"status":{"type":"string","enum":["queued","running","succeeded","failed","cancelled"]},"input":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"progress":{"anyOf":[{"type":"object","properties":{"phase":{"type":"string"},"current":{"type":"number"},"total":{"type":"number"}}},{"type":"null"}]},"summary":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message"]},{"type":"null"}]},"createdAt":{"type":"string"},"startedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"links":{"type":"object","properties":{"self":{"type":"string"},"results":{"type":"string"},"events":{"type":"string"},"cancel":{"type":"string"}}}},"required":["id","kind","status","input","progress","summary","error","createdAt","startedAt","finishedAt"],"additionalProperties":false}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":["string","null"]},"hint":{"type":["string","null"]},"details":{"type":["object","null"]},"requestId":{"type":"string"}},"required":["code","message","requestId"]}}}}}}}},"get":{"summary":"List search jobs","security":[{"integratorKey":[],"customerKey":[]}],"parameters":[{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque cursor from a previous response"},{"name":"limit","in":"query","required":false,"schema":{"type":"string"},"description":"1 to 200, default 50"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["search","enrichment","analysis"]},"status":{"type":"string","enum":["queued","running","succeeded","failed","cancelled"]},"input":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"progress":{"anyOf":[{"type":"object","properties":{"phase":{"type":"string"},"current":{"type":"number"},"total":{"type":"number"}}},{"type":"null"}]},"summary":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message"]},{"type":"null"}]},"createdAt":{"type":"string"},"startedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"links":{"type":"object","properties":{"self":{"type":"string"},"results":{"type":"string"},"events":{"type":"string"},"cancel":{"type":"string"}}}},"required":["id","kind","status","input","progress","summary","error","createdAt","startedAt","finishedAt"],"additionalProperties":false}},"nextCursor":{"type":["string","null"]}}}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":["string","null"]},"hint":{"type":["string","null"]},"details":{"type":["object","null"]},"requestId":{"type":"string"}},"required":["code","message","requestId"]}}}}}}}}},"/searches/{id}":{"get":{"summary":"Get a search job","security":[{"integratorKey":[],"customerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["search","enrichment","analysis"]},"status":{"type":"string","enum":["queued","running","succeeded","failed","cancelled"]},"input":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"progress":{"anyOf":[{"type":"object","properties":{"phase":{"type":"string"},"current":{"type":"number"},"total":{"type":"number"}}},{"type":"null"}]},"summary":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message"]},{"type":"null"}]},"createdAt":{"type":"string"},"startedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"links":{"type":"object","properties":{"self":{"type":"string"},"results":{"type":"string"},"events":{"type":"string"},"cancel":{"type":"string"}}}},"required":["id","kind","status","input","progress","summary","error","createdAt","startedAt","finishedAt"],"additionalProperties":false}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":["string","null"]},"hint":{"type":["string","null"]},"details":{"type":["object","null"]},"requestId":{"type":"string"}},"required":["code","message","requestId"]}}}}}}}}},"/searches/{id}/results":{"get":{"summary":"Page search results","security":[{"integratorKey":[],"customerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque cursor from a previous response"},{"name":"limit","in":"query","required":false,"schema":{"type":"string"},"description":"1 to 200, default 50"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"searchId":{"anyOf":[{"type":"string"},{"type":"null"}]},"fullName":{"type":"string"},"firstName":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastName":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"company":{"anyOf":[{"type":"string"},{"type":"null"}]},"location":{"anyOf":[{"type":"string"},{"type":"null"}]},"industry":{"anyOf":[{"type":"string"},{"type":"null"}]},"skills":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"yearsOfExperience":{"anyOf":[{"type":"number"},{"type":"null"}]},"openToWork":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"createdAt":{"type":"string"},"contact":{"type":"object","properties":{"email":{"type":"array","items":{"type":"string"}},"phone":{"type":"array","items":{"type":"string"}},"linkedin":{"type":"array","items":{"type":"string"}}},"additionalProperties":false},"analysis":{"anyOf":[{"type":"object","properties":{"score":{"anyOf":[{"type":"number"},{"type":"null"}]},"breakdown":{"type":"array","items":{"type":"object","properties":{"criterion":{"type":"string"},"met":{"type":"boolean"},"evidence":{"type":"string"},"reasoning":{"type":"string"}},"required":["criterion","met","evidence","reasoning"],"additionalProperties":false}},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"analyzedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["score","breakdown","description","analyzedAt"],"additionalProperties":false},{"type":"null"}]}},"required":["id","searchId","fullName","firstName","lastName","title","company","location","industry","skills","yearsOfExperience","openToWork","createdAt","contact","analysis"],"additionalProperties":false}},"nextCursor":{"type":["string","null"]}}}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":["string","null"]},"hint":{"type":["string","null"]},"details":{"type":["object","null"]},"requestId":{"type":"string"}},"required":["code","message","requestId"]}}}}}}}}},"/searches/{id}/events":{"get":{"summary":"Stream search events (SSE)","description":"Server-sent events. Each frame carries id (sequence), event (type) and data (JSON). Heartbeats every 15 seconds. Closes after the terminal event (job.completed, job.failed, job.cancelled) or after 30 minutes with a reattach frame. Returns 410 once the events have expired (30 days after completion).","security":[{"integratorKey":[],"customerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Last-Event-ID","in":"header","required":false,"schema":{"type":"string"},"description":"Resume from this event sequence number."}],"responses":{"200":{"description":"OK","content":{"text/event-stream":{"schema":{"type":"string"}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":["string","null"]},"hint":{"type":["string","null"]},"details":{"type":["object","null"]},"requestId":{"type":"string"}},"required":["code","message","requestId"]}}}}}}}}},"/searches/{id}/cancel":{"post":{"summary":"Cancel a search job","security":[{"integratorKey":[],"customerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["cancelled","cancel_requested"]}}}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":["string","null"]},"hint":{"type":["string","null"]},"details":{"type":["object","null"]},"requestId":{"type":"string"}},"required":["code","message","requestId"]}}}}}}}}},"/enrichments":{"post":{"summary":"Create an enrichment job","description":"Queues the job and returns 202. Poll GET /enrichments/{id}, stream GET /enrichments/{id}/events, or wait for the enrichment.completed webhook, then page GET /enrichments/{id}/results.","security":[{"integratorKey":[],"customerKey":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"8 to 128 characters. A retry with the same key returns the original job."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"profileIds":{"minItems":1,"maxItems":1000,"type":"array","items":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,64}$"}},"fields":{"minItems":1,"maxItems":3,"type":"array","items":{"type":"string","enum":["email","phone","linkedin"]}}},"required":["profileIds","fields"],"additionalProperties":false}}}},"responses":{"200":{"description":"Replayed: this Idempotency-Key already created a job, so the original is returned.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["search","enrichment","analysis"]},"status":{"type":"string","enum":["queued","running","succeeded","failed","cancelled"]},"input":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"progress":{"anyOf":[{"type":"object","properties":{"phase":{"type":"string"},"current":{"type":"number"},"total":{"type":"number"}}},{"type":"null"}]},"summary":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message"]},{"type":"null"}]},"createdAt":{"type":"string"},"startedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"links":{"type":"object","properties":{"self":{"type":"string"},"results":{"type":"string"},"events":{"type":"string"},"cancel":{"type":"string"}}}},"required":["id","kind","status","input","progress","summary","error","createdAt","startedAt","finishedAt"],"additionalProperties":false}}}},"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["search","enrichment","analysis"]},"status":{"type":"string","enum":["queued","running","succeeded","failed","cancelled"]},"input":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"progress":{"anyOf":[{"type":"object","properties":{"phase":{"type":"string"},"current":{"type":"number"},"total":{"type":"number"}}},{"type":"null"}]},"summary":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message"]},{"type":"null"}]},"createdAt":{"type":"string"},"startedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"links":{"type":"object","properties":{"self":{"type":"string"},"results":{"type":"string"},"events":{"type":"string"},"cancel":{"type":"string"}}}},"required":["id","kind","status","input","progress","summary","error","createdAt","startedAt","finishedAt"],"additionalProperties":false}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":["string","null"]},"hint":{"type":["string","null"]},"details":{"type":["object","null"]},"requestId":{"type":"string"}},"required":["code","message","requestId"]}}}}}}}},"get":{"summary":"List enrichment jobs","security":[{"integratorKey":[],"customerKey":[]}],"parameters":[{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque cursor from a previous response"},{"name":"limit","in":"query","required":false,"schema":{"type":"string"},"description":"1 to 200, default 50"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["search","enrichment","analysis"]},"status":{"type":"string","enum":["queued","running","succeeded","failed","cancelled"]},"input":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"progress":{"anyOf":[{"type":"object","properties":{"phase":{"type":"string"},"current":{"type":"number"},"total":{"type":"number"}}},{"type":"null"}]},"summary":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message"]},{"type":"null"}]},"createdAt":{"type":"string"},"startedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"links":{"type":"object","properties":{"self":{"type":"string"},"results":{"type":"string"},"events":{"type":"string"},"cancel":{"type":"string"}}}},"required":["id","kind","status","input","progress","summary","error","createdAt","startedAt","finishedAt"],"additionalProperties":false}},"nextCursor":{"type":["string","null"]}}}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":["string","null"]},"hint":{"type":["string","null"]},"details":{"type":["object","null"]},"requestId":{"type":"string"}},"required":["code","message","requestId"]}}}}}}}}},"/enrichments/{id}":{"get":{"summary":"Get an enrichment job","security":[{"integratorKey":[],"customerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["search","enrichment","analysis"]},"status":{"type":"string","enum":["queued","running","succeeded","failed","cancelled"]},"input":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"progress":{"anyOf":[{"type":"object","properties":{"phase":{"type":"string"},"current":{"type":"number"},"total":{"type":"number"}}},{"type":"null"}]},"summary":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message"]},{"type":"null"}]},"createdAt":{"type":"string"},"startedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"links":{"type":"object","properties":{"self":{"type":"string"},"results":{"type":"string"},"events":{"type":"string"},"cancel":{"type":"string"}}}},"required":["id","kind","status","input","progress","summary","error","createdAt","startedAt","finishedAt"],"additionalProperties":false}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":["string","null"]},"hint":{"type":["string","null"]},"details":{"type":["object","null"]},"requestId":{"type":"string"}},"required":["code","message","requestId"]}}}}}}}}},"/enrichments/{id}/results":{"get":{"summary":"Page enrichment results","security":[{"integratorKey":[],"customerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque cursor from a previous response"},{"name":"limit","in":"query","required":false,"schema":{"type":"string"},"description":"1 to 200, default 50"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"profileId":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"object","properties":{"status":{"type":"string","enum":["found","not_found","pending"]},"values":{"type":"array","items":{"type":"string"}}}}}}}},"nextCursor":{"type":["string","null"]}}}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":["string","null"]},"hint":{"type":["string","null"]},"details":{"type":["object","null"]},"requestId":{"type":"string"}},"required":["code","message","requestId"]}}}}}}}}},"/enrichments/{id}/events":{"get":{"summary":"Stream enrichment events (SSE)","description":"Server-sent events. Each frame carries id (sequence), event (type) and data (JSON). Heartbeats every 15 seconds. Closes after the terminal event (job.completed, job.failed, job.cancelled) or after 30 minutes with a reattach frame. Returns 410 once the events have expired (30 days after completion).","security":[{"integratorKey":[],"customerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Last-Event-ID","in":"header","required":false,"schema":{"type":"string"},"description":"Resume from this event sequence number."}],"responses":{"200":{"description":"OK","content":{"text/event-stream":{"schema":{"type":"string"}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":["string","null"]},"hint":{"type":["string","null"]},"details":{"type":["object","null"]},"requestId":{"type":"string"}},"required":["code","message","requestId"]}}}}}}}}},"/enrichments/{id}/cancel":{"post":{"summary":"Cancel an enrichment job","security":[{"integratorKey":[],"customerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["cancelled","cancel_requested"]}}}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":["string","null"]},"hint":{"type":["string","null"]},"details":{"type":["object","null"]},"requestId":{"type":"string"}},"required":["code","message","requestId"]}}}}}}}}},"/analyses":{"post":{"summary":"Create an analysis job","description":"Queues the job and returns 202. Poll GET /analyses/{id}, stream GET /analyses/{id}/events, or wait for the analysis.completed webhook, then page GET /analyses/{id}/results.","security":[{"integratorKey":[],"customerKey":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"8 to 128 characters. A retry with the same key returns the original job."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"profileIds":{"minItems":1,"maxItems":500,"type":"array","items":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,64}$"}},"criteria":{"maxItems":20,"type":"array","items":{"type":"string"}}},"required":["profileIds","criteria"],"additionalProperties":false}}}},"responses":{"200":{"description":"Replayed: this Idempotency-Key already created a job, so the original is returned.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["search","enrichment","analysis"]},"status":{"type":"string","enum":["queued","running","succeeded","failed","cancelled"]},"input":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"progress":{"anyOf":[{"type":"object","properties":{"phase":{"type":"string"},"current":{"type":"number"},"total":{"type":"number"}}},{"type":"null"}]},"summary":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message"]},{"type":"null"}]},"createdAt":{"type":"string"},"startedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"links":{"type":"object","properties":{"self":{"type":"string"},"results":{"type":"string"},"events":{"type":"string"},"cancel":{"type":"string"}}}},"required":["id","kind","status","input","progress","summary","error","createdAt","startedAt","finishedAt"],"additionalProperties":false}}}},"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["search","enrichment","analysis"]},"status":{"type":"string","enum":["queued","running","succeeded","failed","cancelled"]},"input":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"progress":{"anyOf":[{"type":"object","properties":{"phase":{"type":"string"},"current":{"type":"number"},"total":{"type":"number"}}},{"type":"null"}]},"summary":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message"]},{"type":"null"}]},"createdAt":{"type":"string"},"startedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"links":{"type":"object","properties":{"self":{"type":"string"},"results":{"type":"string"},"events":{"type":"string"},"cancel":{"type":"string"}}}},"required":["id","kind","status","input","progress","summary","error","createdAt","startedAt","finishedAt"],"additionalProperties":false}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":["string","null"]},"hint":{"type":["string","null"]},"details":{"type":["object","null"]},"requestId":{"type":"string"}},"required":["code","message","requestId"]}}}}}}}},"get":{"summary":"List analysis jobs","security":[{"integratorKey":[],"customerKey":[]}],"parameters":[{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque cursor from a previous response"},{"name":"limit","in":"query","required":false,"schema":{"type":"string"},"description":"1 to 200, default 50"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["search","enrichment","analysis"]},"status":{"type":"string","enum":["queued","running","succeeded","failed","cancelled"]},"input":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"progress":{"anyOf":[{"type":"object","properties":{"phase":{"type":"string"},"current":{"type":"number"},"total":{"type":"number"}}},{"type":"null"}]},"summary":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message"]},{"type":"null"}]},"createdAt":{"type":"string"},"startedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"links":{"type":"object","properties":{"self":{"type":"string"},"results":{"type":"string"},"events":{"type":"string"},"cancel":{"type":"string"}}}},"required":["id","kind","status","input","progress","summary","error","createdAt","startedAt","finishedAt"],"additionalProperties":false}},"nextCursor":{"type":["string","null"]}}}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":["string","null"]},"hint":{"type":["string","null"]},"details":{"type":["object","null"]},"requestId":{"type":"string"}},"required":["code","message","requestId"]}}}}}}}}},"/analyses/{id}":{"get":{"summary":"Get an analysis job","security":[{"integratorKey":[],"customerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["search","enrichment","analysis"]},"status":{"type":"string","enum":["queued","running","succeeded","failed","cancelled"]},"input":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"progress":{"anyOf":[{"type":"object","properties":{"phase":{"type":"string"},"current":{"type":"number"},"total":{"type":"number"}}},{"type":"null"}]},"summary":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message"]},{"type":"null"}]},"createdAt":{"type":"string"},"startedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"links":{"type":"object","properties":{"self":{"type":"string"},"results":{"type":"string"},"events":{"type":"string"},"cancel":{"type":"string"}}}},"required":["id","kind","status","input","progress","summary","error","createdAt","startedAt","finishedAt"],"additionalProperties":false}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":["string","null"]},"hint":{"type":["string","null"]},"details":{"type":["object","null"]},"requestId":{"type":"string"}},"required":["code","message","requestId"]}}}}}}}}},"/analyses/{id}/results":{"get":{"summary":"Page analysis results","security":[{"integratorKey":[],"customerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque cursor from a previous response"},{"name":"limit","in":"query","required":false,"schema":{"type":"string"},"description":"1 to 200, default 50"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"profileId":{"type":"string"},"status":{"type":"string","enum":["completed","pending","error"]},"score":{"type":["number","null"]},"breakdown":{"type":"array"},"description":{"type":["string","null"]},"analyzedAt":{"type":["string","null"]}}}},"nextCursor":{"type":["string","null"]}}}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":["string","null"]},"hint":{"type":["string","null"]},"details":{"type":["object","null"]},"requestId":{"type":"string"}},"required":["code","message","requestId"]}}}}}}}}},"/analyses/{id}/events":{"get":{"summary":"Stream analysis events (SSE)","description":"Server-sent events. Each frame carries id (sequence), event (type) and data (JSON). Heartbeats every 15 seconds. Closes after the terminal event (job.completed, job.failed, job.cancelled) or after 30 minutes with a reattach frame. Returns 410 once the events have expired (30 days after completion).","security":[{"integratorKey":[],"customerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Last-Event-ID","in":"header","required":false,"schema":{"type":"string"},"description":"Resume from this event sequence number."}],"responses":{"200":{"description":"OK","content":{"text/event-stream":{"schema":{"type":"string"}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":["string","null"]},"hint":{"type":["string","null"]},"details":{"type":["object","null"]},"requestId":{"type":"string"}},"required":["code","message","requestId"]}}}}}}}}},"/analyses/{id}/cancel":{"post":{"summary":"Cancel an analysis job","security":[{"integratorKey":[],"customerKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["cancelled","cancel_requested"]}}}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":["string","null"]},"hint":{"type":["string","null"]},"details":{"type":["object","null"]},"requestId":{"type":"string"}},"required":["code","message","requestId"]}}}}}}}}},"/enrichments/by-identifier":{"post":{"summary":"Find contacts from identifiers","description":"Contacts for people who did not come from our search. Send each person with one or more identifiers: a LinkedIn profile URL, an email address, or a name together with a company. A phone number is not an identifier and is refused. This creates an ordinary enrichment job, so poll GET /enrichments/{id}, stream its events, or wait for the enrichment.completed webhook exactly as you would for the other route; GET /enrichments/{id}/results keys each answer by your own ref instead of a profile id.","security":[{"integratorKey":[],"customerKey":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string"},"description":"8 to 128 characters. A retry with the same key returns the original job."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"people":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"object","properties":{"ref":{"type":"string","minLength":1,"maxLength":64,"pattern":"^[A-Za-z0-9._:-]+$"},"identifiers":{"minItems":1,"maxItems":3,"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"linkedin"},"value":{"type":"string","maxLength":400}},"required":["type","value"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"email"},"value":{"type":"string","maxLength":254,"format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}},"required":["type","value"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","const":"name"},"value":{"type":"string"},"company":{"type":"string"}},"required":["type","value","company"],"additionalProperties":false}]}}},"required":["identifiers"],"additionalProperties":false}},"fields":{"minItems":1,"maxItems":3,"type":"array","items":{"type":"string","enum":["email","phone","linkedin"]}}},"required":["people","fields"],"additionalProperties":false}}}},"responses":{"200":{"description":"Replayed: this Idempotency-Key already created a job, so the original is returned.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["search","enrichment","analysis"]},"status":{"type":"string","enum":["queued","running","succeeded","failed","cancelled"]},"input":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"progress":{"anyOf":[{"type":"object","properties":{"phase":{"type":"string"},"current":{"type":"number"},"total":{"type":"number"}}},{"type":"null"}]},"summary":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message"]},{"type":"null"}]},"createdAt":{"type":"string"},"startedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"links":{"type":"object","properties":{"self":{"type":"string"},"results":{"type":"string"},"events":{"type":"string"},"cancel":{"type":"string"}}}},"required":["id","kind","status","input","progress","summary","error","createdAt","startedAt","finishedAt"],"additionalProperties":false}}}},"202":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["search","enrichment","analysis"]},"status":{"type":"string","enum":["queued","running","succeeded","failed","cancelled"]},"input":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"progress":{"anyOf":[{"type":"object","properties":{"phase":{"type":"string"},"current":{"type":"number"},"total":{"type":"number"}}},{"type":"null"}]},"summary":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message"]},{"type":"null"}]},"createdAt":{"type":"string"},"startedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"finishedAt":{"anyOf":[{"type":"string"},{"type":"null"}]},"links":{"type":"object","properties":{"self":{"type":"string"},"results":{"type":"string"},"events":{"type":"string"},"cancel":{"type":"string"}}}},"required":["id","kind","status","input","progress","summary","error","createdAt","startedAt","finishedAt"],"additionalProperties":false}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":["string","null"]},"hint":{"type":["string","null"]},"details":{"type":["object","null"]},"requestId":{"type":"string"}},"required":["code","message","requestId"]}}}}}}}}},"/profiles/{profileId}":{"get":{"summary":"Get a profile","security":[{"integratorKey":[],"customerKey":[]}],"parameters":[{"name":"profileId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"searchId":{"anyOf":[{"type":"string"},{"type":"null"}]},"fullName":{"type":"string"},"firstName":{"anyOf":[{"type":"string"},{"type":"null"}]},"lastName":{"anyOf":[{"type":"string"},{"type":"null"}]},"title":{"anyOf":[{"type":"string"},{"type":"null"}]},"company":{"anyOf":[{"type":"string"},{"type":"null"}]},"location":{"anyOf":[{"type":"string"},{"type":"null"}]},"industry":{"anyOf":[{"type":"string"},{"type":"null"}]},"skills":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"yearsOfExperience":{"anyOf":[{"type":"number"},{"type":"null"}]},"openToWork":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"createdAt":{"type":"string"},"contact":{"type":"object","properties":{"email":{"type":"array","items":{"type":"string"}},"phone":{"type":"array","items":{"type":"string"}},"linkedin":{"type":"array","items":{"type":"string"}}},"additionalProperties":false},"analysis":{"anyOf":[{"type":"object","properties":{"score":{"anyOf":[{"type":"number"},{"type":"null"}]},"breakdown":{"type":"array","items":{"type":"object","properties":{"criterion":{"type":"string"},"met":{"type":"boolean"},"evidence":{"type":"string"},"reasoning":{"type":"string"}},"required":["criterion","met","evidence","reasoning"],"additionalProperties":false}},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"analyzedAt":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["score","breakdown","description","analyzedAt"],"additionalProperties":false},{"type":"null"}]}},"required":["id","searchId","fullName","firstName","lastName","title","company","location","industry","skills","yearsOfExperience","openToWork","createdAt","contact","analysis"],"additionalProperties":false}}}},"4XX":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"field":{"type":["string","null"]},"hint":{"type":["string","null"]},"details":{"type":["object","null"]},"requestId":{"type":"string"}},"required":["code","message","requestId"]}}}}}}}}}}}