{"openapi":"3.0.0","info":{"title":"Knock API","description":"Enrich people and companies with Knock data, and read your chats and meetings, from your own systems.\n\nAuthenticate every request with your API key in the `x-api-key` header. Request and response bodies are JSON, and every path carries its API version (`v1`).","version":"1.0.0"},"tags":[{"name":"Authentication","description":"Check that your API key works."},{"name":"Enrichment","description":"Submit people or companies for enrichment, then poll the request for the results: enrichment runs in the background."},{"name":"Chats","description":"Read your chats with contacts and their messages."},{"name":"Meetings","description":"Read the meetings contacts booked with your team."}],"paths":{"/resources/whoami/v1":{"get":{"description":"Checks that an API key works and returns the ID of the Knock account it belongs to. Any active key issued for API access can call it, whichever endpoints it may use. It enriches nothing and uses no credits, so it is a safe first call when you set up an integration. It counts toward your rate limit like every other request.","operationId":"verify-api-key","parameters":[],"responses":{"200":{"description":"The API key is valid.","headers":{"X-RateLimit-Limit":{"description":"Requests your account can make in the current rate-limit window.","schema":{"type":"integer","example":600}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer","example":599}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer","example":60}},"X-Request-Id":{"description":"Unique ID of this request. Include it when you contact Knock about a call. Not sent on `413` responses or on a `400` for a body that is not valid JSON.","schema":{"type":"string","example":"0b4c7f9e-1d2a-4e3b-8c5d-6f7a8b9c0d1e"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyApiKeyResponse"}}}},"401":{"description":"The API key is missing, unknown, expired or revoked (`authentication.invalid`). Knock also answers this way when it cannot verify a key at that moment, so retry with backoff before you treat the key as invalid. A request from a country Knock does not serve gets `authentication.forbidden`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalidKey":{"summary":"Missing, unknown or expired API key","value":{"errors":["Invalid authentication token"],"code":"authentication.invalid","metadata":{}}},"blockedCountry":{"summary":"Request from a country Knock does not serve","value":{"errors":["You do not have access to this resource"],"code":"authentication.forbidden","metadata":{}}}}}},"headers":{"X-Request-Id":{"description":"Unique ID of this request. Include it when you contact Knock about a call. Not sent on `413` responses or on a `400` for a body that is not valid JSON.","schema":{"type":"string","example":"0b4c7f9e-1d2a-4e3b-8c5d-6f7a8b9c0d1e"}}}},"403":{"description":"Your account limits API access to an IP allowlist that does not include the caller's IP address (`ip-restriction.denied`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"ipRestriction":{"summary":"IP address not on your allowlist","value":{"errors":["Your IP address is not allowed to access this resource"],"code":"ip-restriction.denied","metadata":{}}}}}},"headers":{"X-Request-Id":{"description":"Unique ID of this request. Include it when you contact Knock about a call. Not sent on `413` responses or on a `400` for a body that is not valid JSON.","schema":{"type":"string","example":"0b4c7f9e-1d2a-4e3b-8c5d-6f7a8b9c0d1e"}}}},"429":{"description":"Your account exceeded its rate limit (`external-api.rate-limit.exceeded`). Wait the number of seconds in `Retry-After` (also in `metadata.retryAfterSeconds`) before you retry. A separate per-IP limit also applies before the API key is checked; when it is exceeded the response has a `Retry-After` header and a `PlainErrorResponse` body with no `code`.","headers":{"Retry-After":{"description":"Seconds to wait before you retry.","schema":{"type":"integer","example":42}},"X-RateLimit-Limit":{"description":"Requests your account can make in the current rate-limit window.","schema":{"type":"integer","example":600}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer","example":599}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer","example":60}},"X-Request-Id":{"description":"Unique ID of this request. Include it when you contact Knock about a call. Not sent on `413` responses or on a `400` for a body that is not valid JSON.","schema":{"type":"string","example":"0b4c7f9e-1d2a-4e3b-8c5d-6f7a8b9c0d1e"}}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/RateLimitErrorResponse"},{"$ref":"#/components/schemas/PlainErrorResponse"}]},"examples":{"accountLimit":{"summary":"Your account exceeded its rate limit","value":{"errors":["Rate limit exceeded"],"code":"external-api.rate-limit.exceeded","metadata":{"limit":600,"retryAfterSeconds":42}}},"ipLimit":{"summary":"Too many requests from one IP address","value":{"statusCode":429,"message":"ThrottlerException: Too Many Requests"}}}}}},"500":{"description":"An unexpected error (a `PlainErrorResponse`, with no `code`). This call changes nothing, so retry it with exponential backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainErrorResponse"},"example":{"statusCode":500,"message":"Internal server error"}}},"headers":{"X-Request-Id":{"description":"Unique ID of this request. Include it when you contact Knock about a call. Not sent on `413` responses or on a `400` for a body that is not valid JSON.","schema":{"type":"string","example":"0b4c7f9e-1d2a-4e3b-8c5d-6f7a8b9c0d1e"}}}}},"security":[{"ApiKeyAuth":[]}],"summary":"Verify API key","tags":["Authentication"]}},"/v1/chats":{"get":{"description":"Returns your chats, latest activity first. `fromDate` and `toDate` filter on `lastActivityAt`.\n\nChats the Knock dashboard hides, such as spam, are not listed. A chat with new activity moves to the top, so it can be skipped or repeated while you page through: deduplicate by `contactId`, and start the next sync with `fromDate` set to when this one started.","operationId":"list-chats","parameters":[{"name":"limit","required":false,"in":"query","description":"Page size.","schema":{"minimum":1,"maximum":100,"default":50,"type":"integer"}},{"name":"offset","required":false,"in":"query","description":"Number of items to skip.","schema":{"minimum":0,"default":0,"type":"integer"}},{"name":"fromDate","required":false,"in":"query","description":"Start of the time window, inclusive: a date (`YYYY-MM-DD`) for the start of that day in UTC, or a date-time (`YYYY-MM-DDTHH:mm[:ss[.sss]]`, optionally followed by `Z` or `±HH:MM`; UTC without one).","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,9})?)?(Z|[+-]\\d{2}:\\d{2})?)?$","example":"2026-10-01T00:00:00Z","type":"string"}},{"name":"toDate","required":false,"in":"query","description":"End of the time window, inclusive: a date (`YYYY-MM-DD`) for the end of that day in UTC, or a date-time (`YYYY-MM-DDTHH:mm[:ss[.sss]]`, optionally followed by `Z` or `±HH:MM`; UTC without one).","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,9})?)?(Z|[+-]\\d{2}:\\d{2})?)?$","example":"2026-10-31T23:59:59Z","type":"string"}}],"responses":{"200":{"description":"A page of chats.","headers":{"X-RateLimit-Limit":{"description":"Requests your account can make in the current rate-limit window.","schema":{"type":"integer","example":600}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer","example":599}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer","example":60}},"X-Request-Id":{"description":"Unique ID of this request. Include it when you contact Knock about a call. Not sent on `413` responses or on a `400` for a body that is not valid JSON.","schema":{"type":"string","example":"0b4c7f9e-1d2a-4e3b-8c5d-6f7a8b9c0d1e"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatList"}}}},"400":{"description":"A query parameter failed validation (`validation`): `errors` has one message per failed check.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"errors":["limit: limit must not be greater than 100"],"code":"validation","metadata":{}}}},"headers":{"X-Request-Id":{"description":"Unique ID of this request. Include it when you contact Knock about a call. Not sent on `413` responses or on a `400` for a body that is not valid JSON.","schema":{"type":"string","example":"0b4c7f9e-1d2a-4e3b-8c5d-6f7a8b9c0d1e"}}}},"401":{"description":"The API key is missing, unknown, expired or revoked (`authentication.invalid`). Knock also answers this way when it cannot verify a key at that moment, so retry with backoff before you treat the key as invalid. A request from a country Knock does not serve gets `authentication.forbidden`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalidKey":{"summary":"Missing, unknown or expired API key","value":{"errors":["Invalid authentication token"],"code":"authentication.invalid","metadata":{}}},"blockedCountry":{"summary":"Request from a country Knock does not serve","value":{"errors":["You do not have access to this resource"],"code":"authentication.forbidden","metadata":{}}}}}},"headers":{"X-Request-Id":{"description":"Unique ID of this request. Include it when you contact Knock about a call. Not sent on `413` responses or on a `400` for a body that is not valid JSON.","schema":{"type":"string","example":"0b4c7f9e-1d2a-4e3b-8c5d-6f7a8b9c0d1e"}}}},"403":{"description":"The API key's role cannot view chats and meetings, such as the Enrichment API role (`permissions.denied`), or your account limits API access to an IP allowlist that does not include the caller's IP address (`ip-restriction.denied`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"permissionDenied":{"summary":"API key without access to chats and meetings","value":{"errors":["You do not have permission to perform this action"],"code":"permissions.denied","metadata":{}}},"ipRestriction":{"summary":"IP address not on your allowlist","value":{"errors":["Your IP address is not allowed to access this resource"],"code":"ip-restriction.denied","metadata":{}}}}}},"headers":{"X-Request-Id":{"description":"Unique ID of this request. Include it when you contact Knock about a call. Not sent on `413` responses or on a `400` for a body that is not valid JSON.","schema":{"type":"string","example":"0b4c7f9e-1d2a-4e3b-8c5d-6f7a8b9c0d1e"}}}},"429":{"description":"Your account exceeded its rate limit (`external-api.rate-limit.exceeded`). Wait the number of seconds in `Retry-After` (also in `metadata.retryAfterSeconds`) before you retry. A separate per-IP limit also applies before the API key is checked; when it is exceeded the response has a `Retry-After` header and a `PlainErrorResponse` body with no `code`.","headers":{"Retry-After":{"description":"Seconds to wait before you retry.","schema":{"type":"integer","example":42}},"X-RateLimit-Limit":{"description":"Requests your account can make in the current rate-limit window.","schema":{"type":"integer","example":600}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer","example":599}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer","example":60}},"X-Request-Id":{"description":"Unique ID of this request. Include it when you contact Knock about a call. Not sent on `413` responses or on a `400` for a body that is not valid JSON.","schema":{"type":"string","example":"0b4c7f9e-1d2a-4e3b-8c5d-6f7a8b9c0d1e"}}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/RateLimitErrorResponse"},{"$ref":"#/components/schemas/PlainErrorResponse"}]},"examples":{"accountLimit":{"summary":"Your account exceeded its rate limit","value":{"errors":["Rate limit exceeded"],"code":"external-api.rate-limit.exceeded","metadata":{"limit":600,"retryAfterSeconds":42}}},"ipLimit":{"summary":"Too many requests from one IP address","value":{"statusCode":429,"message":"ThrottlerException: Too Many Requests"}}}}}},"500":{"description":"An unexpected error (a `PlainErrorResponse`, with no `code`). This call changes nothing, so retry it with exponential backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainErrorResponse"},"example":{"statusCode":500,"message":"Internal server error"}}},"headers":{"X-Request-Id":{"description":"Unique ID of this request. Include it when you contact Knock about a call. Not sent on `413` responses or on a `400` for a body that is not valid JSON.","schema":{"type":"string","example":"0b4c7f9e-1d2a-4e3b-8c5d-6f7a8b9c0d1e"}}}},"502":{"description":"Knock could not read your history at that moment (`external-api.history.unavailable`). Retry after a short wait, with exponential backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"errors":["History is temporarily unavailable, retry later"],"code":"external-api.history.unavailable","metadata":{"vendorId":"3f2c8a71-5d4e-4b9a-8c1f-2e6d7a9b0c35"}}}},"headers":{"X-Request-Id":{"description":"Unique ID of this request. Include it when you contact Knock about a call. Not sent on `413` responses or on a `400` for a body that is not valid JSON.","schema":{"type":"string","example":"0b4c7f9e-1d2a-4e3b-8c5d-6f7a8b9c0d1e"}}}}},"security":[{"ApiKeyAuth":[]}],"summary":"List chats","tags":["Chats"]}},"/v1/chats/{contactId}/messages":{"get":{"description":"Returns the messages of one chat, oldest first, up to 500.","operationId":"get-chat-messages","parameters":[{"name":"contactId","required":true,"in":"path","description":"The `contactId` of a chat from `GET /v1/chats`.","schema":{"format":"uuid","example":"9b1e4c2a-6f3d-4e8b-a7c5-1d2e3f4a5b6c","type":"string"}}],"responses":{"200":{"description":"The messages of the chat.","headers":{"X-RateLimit-Limit":{"description":"Requests your account can make in the current rate-limit window.","schema":{"type":"integer","example":600}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer","example":599}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer","example":60}},"X-Request-Id":{"description":"Unique ID of this request. Include it when you contact Knock about a call. Not sent on `413` responses or on a `400` for a body that is not valid JSON.","schema":{"type":"string","example":"0b4c7f9e-1d2a-4e3b-8c5d-6f7a8b9c0d1e"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatMessages"}}}},"400":{"description":"The `contactId` is not a valid UUID (`validation`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"errors":["contactId: contactId must be a UUID"],"code":"validation","metadata":{}}}},"headers":{"X-Request-Id":{"description":"Unique ID of this request. Include it when you contact Knock about a call. Not sent on `413` responses or on a `400` for a body that is not valid JSON.","schema":{"type":"string","example":"0b4c7f9e-1d2a-4e3b-8c5d-6f7a8b9c0d1e"}}}},"401":{"description":"The API key is missing, unknown, expired or revoked (`authentication.invalid`). Knock also answers this way when it cannot verify a key at that moment, so retry with backoff before you treat the key as invalid. A request from a country Knock does not serve gets `authentication.forbidden`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalidKey":{"summary":"Missing, unknown or expired API key","value":{"errors":["Invalid authentication token"],"code":"authentication.invalid","metadata":{}}},"blockedCountry":{"summary":"Request from a country Knock does not serve","value":{"errors":["You do not have access to this resource"],"code":"authentication.forbidden","metadata":{}}}}}},"headers":{"X-Request-Id":{"description":"Unique ID of this request. Include it when you contact Knock about a call. Not sent on `413` responses or on a `400` for a body that is not valid JSON.","schema":{"type":"string","example":"0b4c7f9e-1d2a-4e3b-8c5d-6f7a8b9c0d1e"}}}},"403":{"description":"The API key's role cannot view chats and meetings, such as the Enrichment API role (`permissions.denied`), or your account limits API access to an IP allowlist that does not include the caller's IP address (`ip-restriction.denied`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"permissionDenied":{"summary":"API key without access to chats and meetings","value":{"errors":["You do not have permission to perform this action"],"code":"permissions.denied","metadata":{}}},"ipRestriction":{"summary":"IP address not on your allowlist","value":{"errors":["Your IP address is not allowed to access this resource"],"code":"ip-restriction.denied","metadata":{}}}}}},"headers":{"X-Request-Id":{"description":"Unique ID of this request. Include it when you contact Knock about a call. Not sent on `413` responses or on a `400` for a body that is not valid JSON.","schema":{"type":"string","example":"0b4c7f9e-1d2a-4e3b-8c5d-6f7a8b9c0d1e"}}}},"404":{"description":"Your account has no chat with this `contactId`, or the chat is hidden, such as spam (`external-api.chat.not-found`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"errors":["Chat not found"],"code":"external-api.chat.not-found","metadata":{"vendorId":"3f2c8a71-5d4e-4b9a-8c1f-2e6d7a9b0c35","contactId":"9b1e4c2a-6f3d-4e8b-a7c5-1d2e3f4a5b6c"}}}},"headers":{"X-Request-Id":{"description":"Unique ID of this request. Include it when you contact Knock about a call. Not sent on `413` responses or on a `400` for a body that is not valid JSON.","schema":{"type":"string","example":"0b4c7f9e-1d2a-4e3b-8c5d-6f7a8b9c0d1e"}}}},"429":{"description":"Your account exceeded its rate limit (`external-api.rate-limit.exceeded`). Wait the number of seconds in `Retry-After` (also in `metadata.retryAfterSeconds`) before you retry. A separate per-IP limit also applies before the API key is checked; when it is exceeded the response has a `Retry-After` header and a `PlainErrorResponse` body with no `code`.","headers":{"Retry-After":{"description":"Seconds to wait before you retry.","schema":{"type":"integer","example":42}},"X-RateLimit-Limit":{"description":"Requests your account can make in the current rate-limit window.","schema":{"type":"integer","example":600}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer","example":599}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer","example":60}},"X-Request-Id":{"description":"Unique ID of this request. Include it when you contact Knock about a call. Not sent on `413` responses or on a `400` for a body that is not valid JSON.","schema":{"type":"string","example":"0b4c7f9e-1d2a-4e3b-8c5d-6f7a8b9c0d1e"}}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/RateLimitErrorResponse"},{"$ref":"#/components/schemas/PlainErrorResponse"}]},"examples":{"accountLimit":{"summary":"Your account exceeded its rate limit","value":{"errors":["Rate limit exceeded"],"code":"external-api.rate-limit.exceeded","metadata":{"limit":600,"retryAfterSeconds":42}}},"ipLimit":{"summary":"Too many requests from one IP address","value":{"statusCode":429,"message":"ThrottlerException: Too Many Requests"}}}}}},"500":{"description":"An unexpected error (a `PlainErrorResponse`, with no `code`). This call changes nothing, so retry it with exponential backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainErrorResponse"},"example":{"statusCode":500,"message":"Internal server error"}}},"headers":{"X-Request-Id":{"description":"Unique ID of this request. Include it when you contact Knock about a call. Not sent on `413` responses or on a `400` for a body that is not valid JSON.","schema":{"type":"string","example":"0b4c7f9e-1d2a-4e3b-8c5d-6f7a8b9c0d1e"}}}},"502":{"description":"Knock could not read your history at that moment (`external-api.history.unavailable`). Retry after a short wait, with exponential backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"errors":["History is temporarily unavailable, retry later"],"code":"external-api.history.unavailable","metadata":{"vendorId":"3f2c8a71-5d4e-4b9a-8c1f-2e6d7a9b0c35"}}}},"headers":{"X-Request-Id":{"description":"Unique ID of this request. Include it when you contact Knock about a call. Not sent on `413` responses or on a `400` for a body that is not valid JSON.","schema":{"type":"string","example":"0b4c7f9e-1d2a-4e3b-8c5d-6f7a8b9c0d1e"}}}}},"security":[{"ApiKeyAuth":[]}],"summary":"Get chat messages","tags":["Chats"]}},"/v1/enrichment-requests/companies":{"post":{"description":"Submits 1 to 100 companies, identified by domain or website URL, for enrichment. Values that reduce to the same domain are merged into one item. A value that is not a valid domain does not fail the request: its item comes back with status `failed`.\n\nKnock answers `202 Accepted` with an `enrichRequestId` and enriches the items in the background. Poll `GET /v1/enrichment-requests/{enrichRequestId}` with that ID until the request is finished. There are no webhooks.\n\nSend `Content-Type: application/json`. Unknown fields are ignored. If any item is invalid, the whole request is rejected with `400` and nothing is submitted.\n\nEnrichment uses credits from your Knock account. There is no idempotency key: sending the same body again creates a new enrichment request.","operationId":"create-companies-enrichment-request","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCompaniesEnrichmentRequestBody"}}}},"responses":{"202":{"description":"Knock accepted the request and is enriching its items.","headers":{"X-RateLimit-Limit":{"description":"Requests your account can make in the current rate-limit window.","schema":{"type":"integer","example":600}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer","example":599}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer","example":60}},"X-Request-Id":{"description":"Unique ID of this request. Include it when you contact Knock about a call. Not sent on `413` responses or on a `400` for a body that is not valid JSON.","schema":{"type":"string","example":"0b4c7f9e-1d2a-4e3b-8c5d-6f7a8b9c0d1e"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnrichmentRequestAccepted"}}}},"400":{"description":"The body failed validation (`validation`): `errors` has one message per failed check, prefixed with the field's path (such as `companies.0.domain`), and nothing was submitted. Or Knock rejected the request (`external-api.enrichment-request.rejected`). A body that is not valid JSON gets a `PlainErrorResponse` with no `code`.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/PlainErrorResponse"}]},"examples":{"validation":{"summary":"Too many companies","value":{"errors":["companies: companies must contain no more than 100 elements"],"code":"validation","metadata":{}}},"rejected":{"summary":"Knock rejected the request","value":{"errors":["The enrichment request was rejected"],"code":"external-api.enrichment-request.rejected","metadata":{"vendorId":"3f2c8a71-5d4e-4b9a-8c1f-2e6d7a9b0c35"}}},"invalidJson":{"summary":"The body is not valid JSON","value":{"message":"Unexpected end of JSON input","error":"Bad Request","statusCode":400}}}}},"headers":{"X-Request-Id":{"description":"Unique ID of this request. Include it when you contact Knock about a call. Not sent on `413` responses or on a `400` for a body that is not valid JSON.","schema":{"type":"string","example":"0b4c7f9e-1d2a-4e3b-8c5d-6f7a8b9c0d1e"}}}},"401":{"description":"The API key is missing, unknown, expired or revoked (`authentication.invalid`). Knock also answers this way when it cannot verify a key at that moment, so retry with backoff before you treat the key as invalid. A request from a country Knock does not serve gets `authentication.forbidden`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalidKey":{"summary":"Missing, unknown or expired API key","value":{"errors":["Invalid authentication token"],"code":"authentication.invalid","metadata":{}}},"blockedCountry":{"summary":"Request from a country Knock does not serve","value":{"errors":["You do not have access to this resource"],"code":"authentication.forbidden","metadata":{}}}}}},"headers":{"X-Request-Id":{"description":"Unique ID of this request. Include it when you contact Knock about a call. Not sent on `413` responses or on a `400` for a body that is not valid JSON.","schema":{"type":"string","example":"0b4c7f9e-1d2a-4e3b-8c5d-6f7a8b9c0d1e"}}}},"403":{"description":"The API key's role does not include the Enrichment API (`permissions.denied`), or your account limits API access to an IP allowlist that does not include the caller's IP address (`ip-restriction.denied`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"permissionDenied":{"summary":"API key without Enrichment API access","value":{"errors":["You do not have permission to perform this action"],"code":"permissions.denied","metadata":{}}},"ipRestriction":{"summary":"IP address not on your allowlist","value":{"errors":["Your IP address is not allowed to access this resource"],"code":"ip-restriction.denied","metadata":{}}}}}},"headers":{"X-Request-Id":{"description":"Unique ID of this request. Include it when you contact Knock about a call. Not sent on `413` responses or on a `400` for a body that is not valid JSON.","schema":{"type":"string","example":"0b4c7f9e-1d2a-4e3b-8c5d-6f7a8b9c0d1e"}}}},"413":{"description":"The body is larger than 100 KB (102,400 bytes). Split the items across several requests.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainErrorResponse"},"example":{"statusCode":413,"message":"request entity too large"}}}},"429":{"description":"Your account exceeded its rate limit (`external-api.rate-limit.exceeded`). Wait the number of seconds in `Retry-After` (also in `metadata.retryAfterSeconds`) before you retry. A separate per-IP limit also applies before the API key is checked; when it is exceeded the response has a `Retry-After` header and a `PlainErrorResponse` body with no `code`.","headers":{"Retry-After":{"description":"Seconds to wait before you retry.","schema":{"type":"integer","example":42}},"X-RateLimit-Limit":{"description":"Requests your account can make in the current rate-limit window.","schema":{"type":"integer","example":600}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer","example":599}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer","example":60}},"X-Request-Id":{"description":"Unique ID of this request. Include it when you contact Knock about a call. Not sent on `413` responses or on a `400` for a body that is not valid JSON.","schema":{"type":"string","example":"0b4c7f9e-1d2a-4e3b-8c5d-6f7a8b9c0d1e"}}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/RateLimitErrorResponse"},{"$ref":"#/components/schemas/PlainErrorResponse"}]},"examples":{"accountLimit":{"summary":"Your account exceeded its rate limit","value":{"errors":["Rate limit exceeded"],"code":"external-api.rate-limit.exceeded","metadata":{"limit":600,"retryAfterSeconds":42}}},"ipLimit":{"summary":"Too many requests from one IP address","value":{"statusCode":429,"message":"ThrottlerException: Too Many Requests"}}}}}},"500":{"description":"Knock accepted the items but could not record the request, so you have no `enrichRequestId` for it (`external-api.enrichment-request.not-stored`). Do not resubmit automatically: the items may already have been enriched and their credits used. Contact Knock support and include the `X-Request-Id` response header. Any other `500` is an unexpected error (a `PlainErrorResponse`, with no `code`): the request may or may not have been created. Sending it again is safe (Knock reuses the same contacts and joins enrichment already in progress) and returns a new `enrichRequestId`.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/PlainErrorResponse"}]},"examples":{"notStored":{"summary":"The request could not be recorded","value":{"errors":["The enrichment request could not be stored"],"code":"external-api.enrichment-request.not-stored","metadata":{"vendorId":"3f2c8a71-5d4e-4b9a-8c1f-2e6d7a9b0c35"}}},"unexpected":{"summary":"Unexpected error","value":{"statusCode":500,"message":"Internal server error"}}}}},"headers":{"X-Request-Id":{"description":"Unique ID of this request. Include it when you contact Knock about a call. Not sent on `413` responses or on a `400` for a body that is not valid JSON.","schema":{"type":"string","example":"0b4c7f9e-1d2a-4e3b-8c5d-6f7a8b9c0d1e"}}}},"502":{"description":"Enrichment is temporarily unavailable (`external-api.enrichment.unavailable`) and no enrichment request was created. Send the same request again after a short wait, with exponential backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"errors":["Enrichment is temporarily unavailable, retry later"],"code":"external-api.enrichment.unavailable","metadata":{"vendorId":"3f2c8a71-5d4e-4b9a-8c1f-2e6d7a9b0c35"}}}},"headers":{"X-Request-Id":{"description":"Unique ID of this request. Include it when you contact Knock about a call. Not sent on `413` responses or on a `400` for a body that is not valid JSON.","schema":{"type":"string","example":"0b4c7f9e-1d2a-4e3b-8c5d-6f7a8b9c0d1e"}}}}},"security":[{"ApiKeyAuth":[]}],"summary":"Enrich companies","tags":["Enrichment"]}},"/v1/enrichment-requests/people":{"post":{"description":"Submits 1 to 100 people, identified by work email, for enrichment. Repeated emails are merged into one item.\n\nKnock answers `202 Accepted` with an `enrichRequestId` and enriches the items in the background. Poll `GET /v1/enrichment-requests/{enrichRequestId}` with that ID until the request is finished. There are no webhooks.\n\nSend `Content-Type: application/json`. Unknown fields are ignored. If any item is invalid, the whole request is rejected with `400` and nothing is submitted.\n\nEnrichment uses credits from your Knock account. There is no idempotency key: sending the same body again creates a new enrichment request.\n\nEach person you submit is added to the contacts in your Knock workspace.","operationId":"create-people-enrichment-request","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePeopleEnrichmentRequestBody"}}}},"responses":{"202":{"description":"Knock accepted the request and is enriching its items.","headers":{"X-RateLimit-Limit":{"description":"Requests your account can make in the current rate-limit window.","schema":{"type":"integer","example":600}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer","example":599}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer","example":60}},"X-Request-Id":{"description":"Unique ID of this request. Include it when you contact Knock about a call. Not sent on `413` responses or on a `400` for a body that is not valid JSON.","schema":{"type":"string","example":"0b4c7f9e-1d2a-4e3b-8c5d-6f7a8b9c0d1e"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnrichmentRequestAccepted"}}}},"400":{"description":"The body failed validation (`validation`): `errors` has one message per failed check, prefixed with the field's path (such as `people.0.email`), and nothing was submitted. Or Knock rejected the request (`external-api.enrichment-request.rejected`). A body that is not valid JSON gets a `PlainErrorResponse` with no `code`.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/PlainErrorResponse"}]},"examples":{"validation":{"summary":"Invalid email","value":{"errors":["people.0.email: email must be an email"],"code":"validation","metadata":{}}},"rejected":{"summary":"Knock rejected the request","value":{"errors":["The enrichment request was rejected"],"code":"external-api.enrichment-request.rejected","metadata":{"vendorId":"3f2c8a71-5d4e-4b9a-8c1f-2e6d7a9b0c35"}}},"invalidJson":{"summary":"The body is not valid JSON","value":{"message":"Unexpected end of JSON input","error":"Bad Request","statusCode":400}}}}},"headers":{"X-Request-Id":{"description":"Unique ID of this request. Include it when you contact Knock about a call. Not sent on `413` responses or on a `400` for a body that is not valid JSON.","schema":{"type":"string","example":"0b4c7f9e-1d2a-4e3b-8c5d-6f7a8b9c0d1e"}}}},"401":{"description":"The API key is missing, unknown, expired or revoked (`authentication.invalid`). Knock also answers this way when it cannot verify a key at that moment, so retry with backoff before you treat the key as invalid. A request from a country Knock does not serve gets `authentication.forbidden`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalidKey":{"summary":"Missing, unknown or expired API key","value":{"errors":["Invalid authentication token"],"code":"authentication.invalid","metadata":{}}},"blockedCountry":{"summary":"Request from a country Knock does not serve","value":{"errors":["You do not have access to this resource"],"code":"authentication.forbidden","metadata":{}}}}}},"headers":{"X-Request-Id":{"description":"Unique ID of this request. Include it when you contact Knock about a call. Not sent on `413` responses or on a `400` for a body that is not valid JSON.","schema":{"type":"string","example":"0b4c7f9e-1d2a-4e3b-8c5d-6f7a8b9c0d1e"}}}},"403":{"description":"The API key's role does not include the Enrichment API (`permissions.denied`), or your account limits API access to an IP allowlist that does not include the caller's IP address (`ip-restriction.denied`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"permissionDenied":{"summary":"API key without Enrichment API access","value":{"errors":["You do not have permission to perform this action"],"code":"permissions.denied","metadata":{}}},"ipRestriction":{"summary":"IP address not on your allowlist","value":{"errors":["Your IP address is not allowed to access this resource"],"code":"ip-restriction.denied","metadata":{}}}}}},"headers":{"X-Request-Id":{"description":"Unique ID of this request. Include it when you contact Knock about a call. Not sent on `413` responses or on a `400` for a body that is not valid JSON.","schema":{"type":"string","example":"0b4c7f9e-1d2a-4e3b-8c5d-6f7a8b9c0d1e"}}}},"413":{"description":"The body is larger than 100 KB (102,400 bytes). Split the items across several requests.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainErrorResponse"},"example":{"statusCode":413,"message":"request entity too large"}}}},"429":{"description":"Your account exceeded its rate limit (`external-api.rate-limit.exceeded`). Wait the number of seconds in `Retry-After` (also in `metadata.retryAfterSeconds`) before you retry. A separate per-IP limit also applies before the API key is checked; when it is exceeded the response has a `Retry-After` header and a `PlainErrorResponse` body with no `code`.","headers":{"Retry-After":{"description":"Seconds to wait before you retry.","schema":{"type":"integer","example":42}},"X-RateLimit-Limit":{"description":"Requests your account can make in the current rate-limit window.","schema":{"type":"integer","example":600}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer","example":599}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer","example":60}},"X-Request-Id":{"description":"Unique ID of this request. Include it when you contact Knock about a call. Not sent on `413` responses or on a `400` for a body that is not valid JSON.","schema":{"type":"string","example":"0b4c7f9e-1d2a-4e3b-8c5d-6f7a8b9c0d1e"}}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/RateLimitErrorResponse"},{"$ref":"#/components/schemas/PlainErrorResponse"}]},"examples":{"accountLimit":{"summary":"Your account exceeded its rate limit","value":{"errors":["Rate limit exceeded"],"code":"external-api.rate-limit.exceeded","metadata":{"limit":600,"retryAfterSeconds":42}}},"ipLimit":{"summary":"Too many requests from one IP address","value":{"statusCode":429,"message":"ThrottlerException: Too Many Requests"}}}}}},"500":{"description":"Knock accepted the items but could not record the request, so you have no `enrichRequestId` for it (`external-api.enrichment-request.not-stored`). Do not resubmit automatically: the items may already have been enriched and their credits used. Contact Knock support and include the `X-Request-Id` response header. Any other `500` is an unexpected error (a `PlainErrorResponse`, with no `code`): the request may or may not have been created. Sending it again is safe (Knock reuses the same contacts and joins enrichment already in progress) and returns a new `enrichRequestId`.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/PlainErrorResponse"}]},"examples":{"notStored":{"summary":"The request could not be recorded","value":{"errors":["The enrichment request could not be stored"],"code":"external-api.enrichment-request.not-stored","metadata":{"vendorId":"3f2c8a71-5d4e-4b9a-8c1f-2e6d7a9b0c35"}}},"unexpected":{"summary":"Unexpected error","value":{"statusCode":500,"message":"Internal server error"}}}}},"headers":{"X-Request-Id":{"description":"Unique ID of this request. Include it when you contact Knock about a call. Not sent on `413` responses or on a `400` for a body that is not valid JSON.","schema":{"type":"string","example":"0b4c7f9e-1d2a-4e3b-8c5d-6f7a8b9c0d1e"}}}},"502":{"description":"Enrichment is temporarily unavailable (`external-api.enrichment.unavailable`) and no enrichment request was created. Send the same request again after a short wait, with exponential backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"errors":["Enrichment is temporarily unavailable, retry later"],"code":"external-api.enrichment.unavailable","metadata":{"vendorId":"3f2c8a71-5d4e-4b9a-8c1f-2e6d7a9b0c35"}}}},"headers":{"X-Request-Id":{"description":"Unique ID of this request. Include it when you contact Knock about a call. Not sent on `413` responses or on a `400` for a body that is not valid JSON.","schema":{"type":"string","example":"0b4c7f9e-1d2a-4e3b-8c5d-6f7a8b9c0d1e"}}}}},"security":[{"ApiKeyAuth":[]}],"summary":"Enrich people","tags":["Enrichment"]}},"/v1/enrichment-requests/{enrichRequestId}":{"get":{"description":"Returns an enrichment request with the status and result of each item. Poll it until `status` is `completed`, `partially_completed` or `failed`; while it is `pending` or `in_progress`, wait before you poll again. Every call counts toward your rate limit.\n\nItems are listed in the order you submitted them, one per distinct input. A person's result includes their current company.\n\nEnrichment has a 24-hour deadline: an item still `pending` 24 hours after the request was created is settled the next time you read the request, as `completed` if Knock has data for it and `failed` otherwise. If Knock cannot check at that moment, the item stays `pending` until a later read.","operationId":"get-enrichment-request","parameters":[{"name":"enrichRequestId","required":true,"in":"path","description":"The `enrichRequestId` you received when you submitted the request.","schema":{"format":"uuid","example":"7d0f4f1e-2c3b-4a8e-9a51-0e6f3b8c2d14","type":"string"}}],"responses":{"200":{"description":"The enrichment request. Its `type` tells you whether the items are people or companies.","headers":{"X-RateLimit-Limit":{"description":"Requests your account can make in the current rate-limit window.","schema":{"type":"integer","example":600}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer","example":599}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer","example":60}},"X-Request-Id":{"description":"Unique ID of this request. Include it when you contact Knock about a call. Not sent on `413` responses or on a `400` for a body that is not valid JSON.","schema":{"type":"string","example":"0b4c7f9e-1d2a-4e3b-8c5d-6f7a8b9c0d1e"}}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/PeopleEnrichmentRequest"},{"$ref":"#/components/schemas/CompaniesEnrichmentRequest"}],"discriminator":{"propertyName":"type","mapping":{"people":"#/components/schemas/PeopleEnrichmentRequest","companies":"#/components/schemas/CompaniesEnrichmentRequest"}}}}}},"400":{"description":"The `enrichRequestId` is not a valid UUID (`validation`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"errors":["enrichRequestId: enrichRequestId must be a UUID"],"code":"validation","metadata":{}}}},"headers":{"X-Request-Id":{"description":"Unique ID of this request. Include it when you contact Knock about a call. Not sent on `413` responses or on a `400` for a body that is not valid JSON.","schema":{"type":"string","example":"0b4c7f9e-1d2a-4e3b-8c5d-6f7a8b9c0d1e"}}}},"401":{"description":"The API key is missing, unknown, expired or revoked (`authentication.invalid`). Knock also answers this way when it cannot verify a key at that moment, so retry with backoff before you treat the key as invalid. A request from a country Knock does not serve gets `authentication.forbidden`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalidKey":{"summary":"Missing, unknown or expired API key","value":{"errors":["Invalid authentication token"],"code":"authentication.invalid","metadata":{}}},"blockedCountry":{"summary":"Request from a country Knock does not serve","value":{"errors":["You do not have access to this resource"],"code":"authentication.forbidden","metadata":{}}}}}},"headers":{"X-Request-Id":{"description":"Unique ID of this request. Include it when you contact Knock about a call. Not sent on `413` responses or on a `400` for a body that is not valid JSON.","schema":{"type":"string","example":"0b4c7f9e-1d2a-4e3b-8c5d-6f7a8b9c0d1e"}}}},"403":{"description":"The API key's role does not include the Enrichment API (`permissions.denied`), or your account limits API access to an IP allowlist that does not include the caller's IP address (`ip-restriction.denied`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"permissionDenied":{"summary":"API key without Enrichment API access","value":{"errors":["You do not have permission to perform this action"],"code":"permissions.denied","metadata":{}}},"ipRestriction":{"summary":"IP address not on your allowlist","value":{"errors":["Your IP address is not allowed to access this resource"],"code":"ip-restriction.denied","metadata":{}}}}}},"headers":{"X-Request-Id":{"description":"Unique ID of this request. Include it when you contact Knock about a call. Not sent on `413` responses or on a `400` for a body that is not valid JSON.","schema":{"type":"string","example":"0b4c7f9e-1d2a-4e3b-8c5d-6f7a8b9c0d1e"}}}},"404":{"description":"Your account has no enrichment request with this ID (`external-api.enrichment-request.not-found`). An ID that belongs to another account returns `404` too.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"errors":["Enrichment request not found"],"code":"external-api.enrichment-request.not-found","metadata":{"vendorId":"3f2c8a71-5d4e-4b9a-8c1f-2e6d7a9b0c35","enrichRequestId":"7d0f4f1e-2c3b-4a8e-9a51-0e6f3b8c2d14"}}}},"headers":{"X-Request-Id":{"description":"Unique ID of this request. Include it when you contact Knock about a call. Not sent on `413` responses or on a `400` for a body that is not valid JSON.","schema":{"type":"string","example":"0b4c7f9e-1d2a-4e3b-8c5d-6f7a8b9c0d1e"}}}},"429":{"description":"Your account exceeded its rate limit (`external-api.rate-limit.exceeded`). Wait the number of seconds in `Retry-After` (also in `metadata.retryAfterSeconds`) before you retry. A separate per-IP limit also applies before the API key is checked; when it is exceeded the response has a `Retry-After` header and a `PlainErrorResponse` body with no `code`.","headers":{"Retry-After":{"description":"Seconds to wait before you retry.","schema":{"type":"integer","example":42}},"X-RateLimit-Limit":{"description":"Requests your account can make in the current rate-limit window.","schema":{"type":"integer","example":600}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer","example":599}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer","example":60}},"X-Request-Id":{"description":"Unique ID of this request. Include it when you contact Knock about a call. Not sent on `413` responses or on a `400` for a body that is not valid JSON.","schema":{"type":"string","example":"0b4c7f9e-1d2a-4e3b-8c5d-6f7a8b9c0d1e"}}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/RateLimitErrorResponse"},{"$ref":"#/components/schemas/PlainErrorResponse"}]},"examples":{"accountLimit":{"summary":"Your account exceeded its rate limit","value":{"errors":["Rate limit exceeded"],"code":"external-api.rate-limit.exceeded","metadata":{"limit":600,"retryAfterSeconds":42}}},"ipLimit":{"summary":"Too many requests from one IP address","value":{"statusCode":429,"message":"ThrottlerException: Too Many Requests"}}}}}},"500":{"description":"An unexpected error (a `PlainErrorResponse`, with no `code`). This call changes nothing, so retry it with exponential backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainErrorResponse"},"example":{"statusCode":500,"message":"Internal server error"}}},"headers":{"X-Request-Id":{"description":"Unique ID of this request. Include it when you contact Knock about a call. Not sent on `413` responses or on a `400` for a body that is not valid JSON.","schema":{"type":"string","example":"0b4c7f9e-1d2a-4e3b-8c5d-6f7a8b9c0d1e"}}}},"502":{"description":"Knock could not read the results at that moment (`external-api.enrichment.unavailable`). Retry after a short wait, with exponential backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"errors":["Enrichment is temporarily unavailable, retry later"],"code":"external-api.enrichment.unavailable","metadata":{"vendorId":"3f2c8a71-5d4e-4b9a-8c1f-2e6d7a9b0c35"}}}},"headers":{"X-Request-Id":{"description":"Unique ID of this request. Include it when you contact Knock about a call. Not sent on `413` responses or on a `400` for a body that is not valid JSON.","schema":{"type":"string","example":"0b4c7f9e-1d2a-4e3b-8c5d-6f7a8b9c0d1e"}}}}},"security":[{"ApiKeyAuth":[]}],"summary":"Get an enrichment request","tags":["Enrichment"]}},"/v1/meetings":{"get":{"description":"Returns your booked, completed and cancelled meetings, newest booking first. `fromDate` and `toDate` filter on `updatedAt`. Meetings booked by your own team members are not listed.","operationId":"list-meetings","parameters":[{"name":"limit","required":false,"in":"query","description":"Page size.","schema":{"minimum":1,"maximum":100,"default":50,"type":"integer"}},{"name":"offset","required":false,"in":"query","description":"Number of items to skip.","schema":{"minimum":0,"default":0,"type":"integer"}},{"name":"fromDate","required":false,"in":"query","description":"Start of the time window, inclusive: a date (`YYYY-MM-DD`) for the start of that day in UTC, or a date-time (`YYYY-MM-DDTHH:mm[:ss[.sss]]`, optionally followed by `Z` or `±HH:MM`; UTC without one).","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,9})?)?(Z|[+-]\\d{2}:\\d{2})?)?$","example":"2026-10-01T00:00:00Z","type":"string"}},{"name":"toDate","required":false,"in":"query","description":"End of the time window, inclusive: a date (`YYYY-MM-DD`) for the end of that day in UTC, or a date-time (`YYYY-MM-DDTHH:mm[:ss[.sss]]`, optionally followed by `Z` or `±HH:MM`; UTC without one).","schema":{"pattern":"^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d{1,9})?)?(Z|[+-]\\d{2}:\\d{2})?)?$","example":"2026-10-31T23:59:59Z","type":"string"}}],"responses":{"200":{"description":"A page of meetings.","headers":{"X-RateLimit-Limit":{"description":"Requests your account can make in the current rate-limit window.","schema":{"type":"integer","example":600}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer","example":599}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer","example":60}},"X-Request-Id":{"description":"Unique ID of this request. Include it when you contact Knock about a call. Not sent on `413` responses or on a `400` for a body that is not valid JSON.","schema":{"type":"string","example":"0b4c7f9e-1d2a-4e3b-8c5d-6f7a8b9c0d1e"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeetingList"}}}},"400":{"description":"A query parameter failed validation (`validation`): `errors` has one message per failed check.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"errors":["limit: limit must not be greater than 100"],"code":"validation","metadata":{}}}},"headers":{"X-Request-Id":{"description":"Unique ID of this request. Include it when you contact Knock about a call. Not sent on `413` responses or on a `400` for a body that is not valid JSON.","schema":{"type":"string","example":"0b4c7f9e-1d2a-4e3b-8c5d-6f7a8b9c0d1e"}}}},"401":{"description":"The API key is missing, unknown, expired or revoked (`authentication.invalid`). Knock also answers this way when it cannot verify a key at that moment, so retry with backoff before you treat the key as invalid. A request from a country Knock does not serve gets `authentication.forbidden`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalidKey":{"summary":"Missing, unknown or expired API key","value":{"errors":["Invalid authentication token"],"code":"authentication.invalid","metadata":{}}},"blockedCountry":{"summary":"Request from a country Knock does not serve","value":{"errors":["You do not have access to this resource"],"code":"authentication.forbidden","metadata":{}}}}}},"headers":{"X-Request-Id":{"description":"Unique ID of this request. Include it when you contact Knock about a call. Not sent on `413` responses or on a `400` for a body that is not valid JSON.","schema":{"type":"string","example":"0b4c7f9e-1d2a-4e3b-8c5d-6f7a8b9c0d1e"}}}},"403":{"description":"The API key's role cannot view chats and meetings, such as the Enrichment API role (`permissions.denied`), or your account limits API access to an IP allowlist that does not include the caller's IP address (`ip-restriction.denied`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"permissionDenied":{"summary":"API key without access to chats and meetings","value":{"errors":["You do not have permission to perform this action"],"code":"permissions.denied","metadata":{}}},"ipRestriction":{"summary":"IP address not on your allowlist","value":{"errors":["Your IP address is not allowed to access this resource"],"code":"ip-restriction.denied","metadata":{}}}}}},"headers":{"X-Request-Id":{"description":"Unique ID of this request. Include it when you contact Knock about a call. Not sent on `413` responses or on a `400` for a body that is not valid JSON.","schema":{"type":"string","example":"0b4c7f9e-1d2a-4e3b-8c5d-6f7a8b9c0d1e"}}}},"429":{"description":"Your account exceeded its rate limit (`external-api.rate-limit.exceeded`). Wait the number of seconds in `Retry-After` (also in `metadata.retryAfterSeconds`) before you retry. A separate per-IP limit also applies before the API key is checked; when it is exceeded the response has a `Retry-After` header and a `PlainErrorResponse` body with no `code`.","headers":{"Retry-After":{"description":"Seconds to wait before you retry.","schema":{"type":"integer","example":42}},"X-RateLimit-Limit":{"description":"Requests your account can make in the current rate-limit window.","schema":{"type":"integer","example":600}},"X-RateLimit-Remaining":{"description":"Requests left in the current window.","schema":{"type":"integer","example":599}},"X-RateLimit-Reset":{"description":"Seconds until the current window resets.","schema":{"type":"integer","example":60}},"X-Request-Id":{"description":"Unique ID of this request. Include it when you contact Knock about a call. Not sent on `413` responses or on a `400` for a body that is not valid JSON.","schema":{"type":"string","example":"0b4c7f9e-1d2a-4e3b-8c5d-6f7a8b9c0d1e"}}},"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/RateLimitErrorResponse"},{"$ref":"#/components/schemas/PlainErrorResponse"}]},"examples":{"accountLimit":{"summary":"Your account exceeded its rate limit","value":{"errors":["Rate limit exceeded"],"code":"external-api.rate-limit.exceeded","metadata":{"limit":600,"retryAfterSeconds":42}}},"ipLimit":{"summary":"Too many requests from one IP address","value":{"statusCode":429,"message":"ThrottlerException: Too Many Requests"}}}}}},"500":{"description":"An unexpected error (a `PlainErrorResponse`, with no `code`). This call changes nothing, so retry it with exponential backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlainErrorResponse"},"example":{"statusCode":500,"message":"Internal server error"}}},"headers":{"X-Request-Id":{"description":"Unique ID of this request. Include it when you contact Knock about a call. Not sent on `413` responses or on a `400` for a body that is not valid JSON.","schema":{"type":"string","example":"0b4c7f9e-1d2a-4e3b-8c5d-6f7a8b9c0d1e"}}}},"502":{"description":"Knock could not read your history at that moment (`external-api.history.unavailable`). Retry after a short wait, with exponential backoff.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"errors":["History is temporarily unavailable, retry later"],"code":"external-api.history.unavailable","metadata":{"vendorId":"3f2c8a71-5d4e-4b9a-8c1f-2e6d7a9b0c35"}}}},"headers":{"X-Request-Id":{"description":"Unique ID of this request. Include it when you contact Knock about a call. Not sent on `413` responses or on a `400` for a body that is not valid JSON.","schema":{"type":"string","example":"0b4c7f9e-1d2a-4e3b-8c5d-6f7a8b9c0d1e"}}}}},"security":[{"ApiKeyAuth":[]}],"summary":"List meetings","tags":["Meetings"]}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your Knock API key. Ask your Knock account team for one: a key with the Enrichment API role for enrichment, or the Viewer role for chats and meetings."}},"schemas":{"AccountIntel":{"type":"object","properties":{"targetPersona":{"description":"The personas the company sells to.","example":["Sales Director"],"type":"array","items":{"type":"string"}},"segments":{"description":"The customer segments the company serves.","example":["Enterprise","SMBs"],"type":"array","items":{"type":"string"}},"verticals":{"description":"The industries the company sells into.","example":["Software"],"type":"array","items":{"type":"string"}},"spaces":{"description":"The market spaces the company operates in.","example":["Sales"],"type":"array","items":{"type":"string"}},"productTypes":{"description":"The kinds of products the company sells.","example":["Inbound scheduling & routing"],"type":"array","items":{"type":"string"}},"salesMotions":{"description":"How the company sells, for example `Sales-Led`.","example":["Sales-Led"],"type":"array","items":{"type":"string"}}},"description":"How the company goes to market.","required":["targetPersona","segments","verticals","spaces","productTypes","salesMotions"]},"Chat":{"type":"object","properties":{"contactId":{"type":"string","format":"uuid","description":"ID of the contact. Pass it to `GET /v1/chats/{contactId}/messages`.","example":"9b1e4c2a-6f3d-4e8b-a7c5-1d2e3f4a5b6c"},"firstName":{"type":"string","nullable":true,"description":"Contact's first name.","example":"Jane"},"lastName":{"type":"string","nullable":true,"description":"Contact's last name.","example":"Doe"},"role":{"type":"string","nullable":true,"description":"Contact's job title.","example":"VP Sales"},"companyName":{"type":"string","nullable":true,"description":"Contact's company name.","example":"Acme"},"companyDomain":{"type":"string","nullable":true,"description":"Contact's company domain.","example":"acme.com"},"channels":{"type":"array","description":"Messaging apps the chat ran on.","example":["slack"],"items":{"$ref":"#/components/schemas/ChatChannel"}},"status":{"type":"string","description":"Contact's status in Knock, for example `Qualified` or `Rep Reply Needed`.","example":"Qualified"},"intent":{"type":"string","nullable":true,"description":"What the contact wants: `buying`, `support`, `partnership` or `job-seeker`.","example":"buying"},"segment":{"type":"string","nullable":true,"description":"Segment the contact was routed to.","example":"Enterprise"},"ownerId":{"type":"string","format":"uuid","nullable":true,"description":"ID of the team member who owns the chat. Null when the AI agent handles it.","example":"5a7c9e1b-3d5f-4a6b-8c9d-0e1f2a3b4c5d"},"ownerName":{"type":"string","nullable":true,"description":"Owner's name.","example":"Alex Kim"},"lastActivityAt":{"type":"string","format":"date-time","nullable":true,"description":"When the contact was last active.","example":"2026-10-19T10:00:00.000Z"},"createdAt":{"type":"string","format":"date-time","description":"When the contact was added to Knock.","example":"2026-10-01T09:00:00.000Z"}},"description":"A chat with a contact.","required":["contactId","firstName","lastName","role","companyName","companyDomain","channels","status","intent","segment","ownerId","ownerName","lastActivityAt","createdAt"]},"ChatChannel":{"type":"string","enum":["slack","slack_community","google_chat","whatsapp","linkedin","telegram"],"description":"Messaging apps the chat ran on."},"ChatList":{"type":"object","properties":{"total":{"type":"integer","description":"Number of items that match the query, across all pages.","example":1},"limit":{"type":"integer","description":"Page size of this page.","example":50},"offset":{"type":"integer","description":"Number of items skipped before this page.","example":0},"items":{"description":"Chats, latest activity first.","type":"array","items":{"$ref":"#/components/schemas/Chat"}}},"description":"A page of chats.","required":["total","limit","offset","items"]},"ChatMessage":{"type":"object","properties":{"author":{"description":"Who wrote the message: `contact`, `rep` (a team member) or `ai` (the Knock AI agent).","example":"rep","allOf":[{"$ref":"#/components/schemas/ChatMessageAuthor"}]},"memberId":{"type":"string","format":"uuid","nullable":true,"description":"ID of the team member who wrote a `rep` message. Null for other authors and when unknown.","example":"5a7c9e1b-3d5f-4a6b-8c9d-0e1f2a3b4c5d"},"memberName":{"type":"string","nullable":true,"description":"That team member's name.","example":"Alex Kim"},"text":{"type":"string","description":"Message text.","example":"Sure, does Tuesday at 3pm work?"},"sentAt":{"type":"string","format":"date-time","description":"When the message was sent.","example":"2026-10-19T10:00:00.000Z"}},"description":"One message in a chat.","required":["author","memberId","memberName","text","sentAt"]},"ChatMessageAuthor":{"type":"string","enum":["contact","rep","ai"],"description":"Who wrote the message: `contact`, `rep` (a team member) or `ai` (the Knock AI agent)."},"ChatMessages":{"type":"object","properties":{"messages":{"description":"Messages, oldest first. At most 500: a longer chat returns its first 500.","type":"array","items":{"$ref":"#/components/schemas/ChatMessage"}}},"description":"The messages of a chat.","required":["messages"]},"CompaniesEnrichmentRequest":{"type":"object","properties":{"enrichRequestId":{"type":"string","format":"uuid","description":"ID of the enrichment request.","example":"7d0f4f1e-2c3b-4a8e-9a51-0e6f3b8c2d14"},"type":{"type":"string","enum":["companies"],"description":"What the request enriches.","example":"companies"},"status":{"description":"Status of the request.","example":"in_progress","allOf":[{"$ref":"#/components/schemas/EnrichmentRequestStatus"}]},"createdAt":{"type":"string","format":"date-time","description":"When the request was created (ISO 8601, UTC).","example":"2026-10-20T09:30:00.000Z"},"items":{"description":"One item per distinct company, in the order you submitted them.","type":"array","items":{"$ref":"#/components/schemas/CompanyEnrichmentItem"}}},"description":"A companies enrichment request and its items.","required":["enrichRequestId","type","status","createdAt","items"]},"CompanyEnrichmentItem":{"type":"object","properties":{"input":{"type":"string","description":"The domain or URL this item is for, exactly as you sent it (the first one, when several reduced to the same domain). Match results to your records by this value, not by position.","example":"acme.com"},"status":{"description":"Status of this item.","example":"completed","allOf":[{"$ref":"#/components/schemas/EnrichmentItemStatus"}]},"result":{"nullable":true,"description":"The enriched company when `status` is `completed`, otherwise null. A completed item can still be null when Knock holds no data for the company.","type":"object","allOf":[{"$ref":"#/components/schemas/EnrichedCompany"}]}},"description":"One company in a companies enrichment request.","required":["input","status","result"]},"CompanyInput":{"type":"object","properties":{"domain":{"type":"string","minLength":1,"maxLength":320,"description":"The company's domain or website URL, for example `acme.com` or `https://www.acme.com/about`. Knock reduces a URL to its domain. A value that is not a valid domain does not fail the request: its item comes back with status `failed`.","example":"acme.com"}},"description":"A company to enrich.","required":["domain"]},"CreateCompaniesEnrichmentRequestBody":{"type":"object","properties":{"companies":{"minItems":1,"maxItems":100,"description":"The companies to enrich, 1 to 100. Values that reduce to the same domain are merged into one item.","type":"array","items":{"$ref":"#/components/schemas/CompanyInput"}}},"required":["companies"]},"CreatePeopleEnrichmentRequestBody":{"type":"object","properties":{"people":{"minItems":1,"maxItems":100,"description":"The people to enrich, 1 to 100. Repeated emails are merged into one item.","type":"array","items":{"$ref":"#/components/schemas/PersonInput"}}},"required":["people"]},"DecisionMaker":{"type":"object","properties":{"name":{"type":"string","description":"Full name.","example":"Bob Smith"},"title":{"type":"string","description":"Current job title.","example":"CRO"},"linkedinUrl":{"type":"string","description":"LinkedIn profile URL.","example":"https://www.linkedin.com/in/bob-smith"},"matchedRole":{"type":"string","description":"The decision-maker role this person was matched to.","example":"Sales leader"}},"description":"A person at the company who holds one of the decision-maker roles in your Knock account.","required":["name","title","linkedinUrl","matchedRole"]},"DepartmentHeadcount":{"type":"object","properties":{"department":{"type":"string","description":"Department name.","example":"Sales"},"headcount":{"type":"integer","description":"Number of employees in the department.","example":40}},"description":"The headcount of one department.","required":["department","headcount"]},"EnrichedCompany":{"type":"object","properties":{"name":{"type":"string","nullable":true,"description":"Company name.","example":"Acme"},"domain":{"type":"string","nullable":true,"description":"Primary domain.","example":"acme.com"},"logoUrl":{"type":"string","nullable":true,"description":"Logo image URL.","example":"https://logo.example.com/acme.png"},"description":{"type":"string","nullable":true,"description":"Short description of the company.","example":"Acme builds scheduling software for revenue teams."},"industry":{"type":"string","nullable":true,"description":"Industry, as an upper-case code such as `COMPUTER_SOFTWARE` or `FINANCIAL_SERVICES`.","example":"COMPUTER_SOFTWARE"},"size":{"type":"string","nullable":true,"description":"Employee-count range, such as `11-50`, `101-200` or `10000+`.","example":"101-200"},"employees":{"type":"string","nullable":true,"description":"Number of employees.","example":"120"},"foundedDate":{"type":"string","nullable":true,"description":"Year the company was founded.","example":"2015"},"totalFunding":{"type":"string","nullable":true,"description":"Total funding raised.","example":"$22M"},"lastFunding":{"type":"string","nullable":true,"description":"Latest funding stage, for example `seed`, `series_a` or `private_equity`.","example":"series_a"},"annualRevenue":{"type":"string","nullable":true,"description":"Annual revenue range, such as `$1m-$10m`, `$10m-$25m` or `$10b+`.","example":"$10m-$25m"},"ownership":{"type":"string","nullable":true,"description":"Ownership type, for example `Private`, `Public` or `Acquired/Merged`.","example":"Private"},"headquarters":{"type":"string","nullable":true,"description":"Headquarters location.","example":"New York, NY"},"country":{"type":"string","nullable":true,"description":"Country of the headquarters, as a country name or a two-letter ISO 3166-1 code depending on the source.","example":"US"},"region":{"type":"string","nullable":true,"description":"Sales region of the headquarters, such as `North America`, `EMEA` or `APAC`.","example":"North America"},"state":{"type":"string","nullable":true,"description":"State or province of the headquarters.","example":"New York"},"competitors":{"type":"string","nullable":true,"description":"Main competitors.","example":"Globex, Initech"},"techStack":{"description":"Technologies the company uses.","type":"array","items":{"$ref":"#/components/schemas/TechStackItem"}},"teamSize":{"description":"Headcount by department.","type":"array","items":{"$ref":"#/components/schemas/DepartmentHeadcount"}},"fundingRounds":{"description":"Funding rounds the company raised.","type":"array","items":{"$ref":"#/components/schemas/FundingRound"}},"accountIntel":{"nullable":true,"description":"How the company goes to market. Null when Knock has no data.","type":"object","allOf":[{"$ref":"#/components/schemas/AccountIntel"}]},"decisionMakers":{"description":"People at the company who hold one of the decision-maker roles in your Knock account.","type":"array","items":{"$ref":"#/components/schemas/DecisionMaker"}}},"description":"An enriched company. Fields Knock has no data for are null (or empty lists).","required":["name","domain","logoUrl","description","industry","size","employees","foundedDate","totalFunding","lastFunding","annualRevenue","ownership","headquarters","country","region","state","competitors","techStack","teamSize","fundingRounds","accountIntel","decisionMakers"]},"EnrichedPerson":{"type":"object","properties":{"firstName":{"type":"string","nullable":true,"description":"First name.","example":"Jane"},"lastName":{"type":"string","nullable":true,"description":"Last name.","example":"Doe"},"title":{"type":"string","nullable":true,"description":"Current job title.","example":"VP Sales"},"seniority":{"type":"string","nullable":true,"description":"Seniority level.","example":"VP"},"profession":{"type":"string","nullable":true,"description":"Professional area.","example":"Sales"},"linkedinUrl":{"type":"string","description":"LinkedIn profile URL. Always present: Knock returns a person only when it matched their LinkedIn profile.","example":"https://www.linkedin.com/in/jane-doe"},"location":{"type":"string","nullable":true,"description":"Location.","example":"Austin, Texas, United States"},"photoUrl":{"type":"string","nullable":true,"description":"Profile photo URL.","example":"https://media.example.com/jane-doe.jpg"},"currentPositionStartDate":{"type":"string","nullable":true,"description":"When the person started their current position, as precise as the source allows (`YYYY-MM` or `YYYY-MM-DD`).","example":"2024-03"},"company":{"nullable":true,"description":"The person's current company, with the same fields a company enrichment returns. Null while Knock has not resolved the company.","type":"object","allOf":[{"$ref":"#/components/schemas/EnrichedCompany"}]}},"description":"An enriched person. Fields Knock has no data for are null.","required":["firstName","lastName","title","seniority","profession","linkedinUrl","location","photoUrl","currentPositionStartDate","company"]},"EnrichmentItemStatus":{"type":"string","description":"Status of one item: `pending` (still being enriched), `completed` (enriched), `not_found` (Knock found no match), `failed` (the item could not be enriched, for example an invalid domain). Every status except `pending` is final.","enum":["completed","not_found","pending","failed"]},"EnrichmentRequestAccepted":{"type":"object","properties":{"enrichRequestId":{"type":"string","format":"uuid","description":"ID of the new enrichment request. Store it: you need it to read the results, and there is no endpoint that lists your requests.","example":"7d0f4f1e-2c3b-4a8e-9a51-0e6f3b8c2d14"},"status":{"description":"Status right after submission. Usually `pending`, but items Knock has already enriched, or recently failed to match, are final at once.","example":"pending","allOf":[{"$ref":"#/components/schemas/EnrichmentRequestStatus"}]}},"description":"An enrichment request Knock accepted.","required":["enrichRequestId","status"]},"EnrichmentRequestStatus":{"type":"string","description":"Status of an enrichment request, derived from its items: `pending` (no item has finished), `in_progress` (some items have finished, others are pending), `completed` (every item finished and none failed; `not_found` counts as finished), `partially_completed` (every item finished and some failed), `failed` (every item failed).","enum":["pending","in_progress","completed","partially_completed","failed"]},"ErrorResponse":{"type":"object","properties":{"errors":{"description":"Human-readable error messages.","example":["Invalid authentication token"],"type":"array","items":{"type":"string"}},"code":{"type":"string","description":"Stable, machine-readable error code. Branch on this value, not on the messages.","example":"authentication.invalid"},"metadata":{"type":"object","additionalProperties":true,"description":"Extra context about the error, such as the ID that was not found. Often empty.","example":{}}},"description":"The body of an error response.","required":["errors","code","metadata"]},"FundingRound":{"type":"object","properties":{"type":{"type":"string","description":"Round type, for example `seed`, `series_a` or `debt_financing`.","example":"series_a"},"amountMillions":{"type":"number","nullable":true,"description":"Amount raised, in millions. Null when it was not disclosed.","example":22},"currency":{"type":"string","description":"Currency of the amount, as an ISO 4217 code.","example":"USD"},"date":{"type":"string","nullable":true,"description":"Date of the round (`YYYY-MM-DD`). Null when unknown.","example":"2024-03-01"},"investors":{"description":"Investors in the round.","example":["Example Ventures"],"type":"array","items":{"type":"string"}}},"description":"A funding round the company raised.","required":["type","amountMillions","currency","date","investors"]},"Meeting":{"type":"object","properties":{"meetingId":{"type":"string","format":"uuid","description":"ID of the meeting.","example":"2e4f6a8c-0b1d-4c3e-9f5a-7b8c9d0e1f2a"},"contactId":{"type":"string","format":"uuid","nullable":true,"description":"ID of the contact who booked the meeting.","example":"9b1e4c2a-6f3d-4e8b-a7c5-1d2e3f4a5b6c"},"status":{"description":"Status of the meeting: `booked`, `completed` or `cancelled`.","example":"booked","allOf":[{"$ref":"#/components/schemas/MeetingStatus"}]},"bookingSource":{"type":"string","nullable":true,"description":"How the contact booked: `meeting_link` (a Knock link), `personal_link` (a team member's personal link) or `messaging_app` (from a chat).","example":"meeting_link"},"bookedAt":{"type":"string","format":"date-time","nullable":true,"description":"When the meeting was booked.","example":"2026-10-18T12:00:00.000Z"},"startAt":{"type":"string","format":"date-time","nullable":true,"description":"When the meeting starts: `endAt` minus your configured meeting length.","example":"2026-10-25T15:00:00.000Z"},"endAt":{"type":"string","format":"date-time","nullable":true,"description":"When the meeting ends.","example":"2026-10-25T15:30:00.000Z"},"updatedAt":{"type":"string","format":"date-time","description":"When Knock last updated the meeting, for example its status.","example":"2026-10-18T12:00:00.000Z"},"firstName":{"type":"string","nullable":true,"description":"Contact's first name.","example":"Jane"},"lastName":{"type":"string","nullable":true,"description":"Contact's last name.","example":"Doe"},"companyName":{"type":"string","nullable":true,"description":"Contact's company name.","example":"Acme"},"companyDomain":{"type":"string","nullable":true,"description":"Contact's company domain.","example":"acme.com"},"segment":{"type":"string","nullable":true,"description":"Segment the meeting was routed to.","example":"Enterprise"},"ownerId":{"type":"string","format":"uuid","nullable":true,"description":"ID of the team member who hosts the meeting, or the contact's owner when Knock has no host for it.","example":"5a7c9e1b-3d5f-4a6b-8c9d-0e1f2a3b4c5d"},"ownerName":{"type":"string","nullable":true,"description":"That team member's name.","example":"Alex Kim"}},"description":"A meeting a contact booked with your team.","required":["meetingId","contactId","status","bookingSource","bookedAt","startAt","endAt","updatedAt","firstName","lastName","companyName","companyDomain","segment","ownerId","ownerName"]},"MeetingList":{"type":"object","properties":{"total":{"type":"integer","description":"Number of items that match the query, across all pages.","example":1},"limit":{"type":"integer","description":"Page size of this page.","example":50},"offset":{"type":"integer","description":"Number of items skipped before this page.","example":0},"items":{"description":"Meetings, newest booking first.","type":"array","items":{"$ref":"#/components/schemas/Meeting"}}},"description":"A page of meetings.","required":["total","limit","offset","items"]},"MeetingStatus":{"type":"string","enum":["booked","completed","cancelled"],"description":"Status of the meeting: `booked`, `completed` or `cancelled`."},"PeopleEnrichmentRequest":{"type":"object","properties":{"enrichRequestId":{"type":"string","format":"uuid","description":"ID of the enrichment request.","example":"7d0f4f1e-2c3b-4a8e-9a51-0e6f3b8c2d14"},"type":{"type":"string","enum":["people"],"description":"What the request enriches.","example":"people"},"status":{"description":"Status of the request.","example":"in_progress","allOf":[{"$ref":"#/components/schemas/EnrichmentRequestStatus"}]},"createdAt":{"type":"string","format":"date-time","description":"When the request was created (ISO 8601, UTC).","example":"2026-10-20T09:30:00.000Z"},"items":{"description":"One item per distinct email, in the order you submitted them.","type":"array","items":{"$ref":"#/components/schemas/PersonEnrichmentItem"}}},"description":"A people enrichment request and its items.","required":["enrichRequestId","type","status","createdAt","items"]},"PersonEnrichmentItem":{"type":"object","properties":{"input":{"type":"string","description":"The email this item is for, lowercased. Match results to your records by this value, not by position: repeated emails are merged into one item.","example":"jane@acme.com"},"status":{"description":"Status of this item.","example":"completed","allOf":[{"$ref":"#/components/schemas/EnrichmentItemStatus"}]},"result":{"nullable":true,"description":"The enriched person when `status` is `completed`, otherwise null. A completed item can still be null when Knock holds no data for the person.","type":"object","allOf":[{"$ref":"#/components/schemas/EnrichedPerson"}]}},"description":"One person in a people enrichment request.","required":["input","status","result"]},"PersonInput":{"type":"object","properties":{"email":{"type":"string","format":"email","maxLength":254,"description":"The person's work email, matched case-insensitively. At most 254 characters: a longer value is rejected as an invalid email.","example":"jane@acme.com"},"firstName":{"type":"string","maxLength":320,"description":"First name. Used when Knock adds the person to your contacts.","example":"Jane"},"lastName":{"type":"string","maxLength":320,"description":"Last name. Used when Knock adds the person to your contacts.","example":"Doe"}},"description":"A person to enrich.","required":["email"]},"PlainErrorResponse":{"type":"object","properties":{"statusCode":{"type":"integer","description":"The HTTP status code.","example":500},"message":{"type":"string","description":"What went wrong. Do not parse it: the wording can change.","example":"Internal server error"},"error":{"type":"string","description":"The HTTP status text. Only some responses include it.","example":"Bad Request"}},"description":"The body of an error raised before the request reaches the Knock API itself: a body that is not valid JSON (`400`) or is too large (`413`), the per-IP rate limit (`429`) or an unexpected error (`500`). It has no `code`: branch on the HTTP status.","required":["statusCode","message"]},"RateLimitErrorMetadata":{"type":"object","properties":{"limit":{"type":"integer","description":"Requests your account can make per rate-limit window.","example":600},"retryAfterSeconds":{"type":"integer","description":"Seconds to wait before you retry. Same value as the `Retry-After` header.","example":42}},"description":"Details of the rate limit you exceeded.","required":["limit","retryAfterSeconds"]},"RateLimitErrorResponse":{"type":"object","properties":{"errors":{"description":"Human-readable error messages.","example":["Rate limit exceeded"],"type":"array","items":{"type":"string"}},"code":{"type":"string","description":"Stable, machine-readable error code. Branch on this value, not on the messages.","example":"external-api.rate-limit.exceeded"},"metadata":{"$ref":"#/components/schemas/RateLimitErrorMetadata"}},"description":"The body of a `429` response when your account exceeds its rate limit.","required":["errors","code","metadata"]},"TechStackItem":{"type":"object","properties":{"name":{"type":"string","description":"Technology name.","example":"Salesforce"},"category":{"type":"string","description":"Technology category.","example":"CRM"}},"description":"A technology the company uses.","required":["name","category"]},"VerifyApiKeyResponse":{"type":"object","properties":{"vendorId":{"type":"string","format":"uuid","description":"ID of the Knock account that owns the API key.","example":"3f2c8a71-5d4e-4b9a-8c1f-2e6d7a9b0c35"}},"description":"The account an API key belongs to.","required":["vendorId"]}}},"servers":[{"url":"https://app.knock-ai.com","description":"Production"}]}