{"openapi":"3.0.0","info":{"title":"Dex Public API","version":"1.0.0","description":"The Dex API lets you programmatically manage your contacts, notes, and reminders. Authenticate using an API key generated from Settings > API in the Dex app.\n\n## Rate Limits\nEvery response carries rate-limit state in two header families, so you can use whichever your HTTP client understands:\n\n- **IETF standard** (`draft-ietf-httpapi-ratelimit-headers`): `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`, plus the structured-field `RateLimit` and `RateLimit-Policy` headers.\n- **Legacy** (still emitted, and not going away): `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`.\n\nBoth families report the same numbers. `*-Reset` is **seconds remaining in the current window**, not a Unix timestamp. On `429 Too Many Requests`, respect the `Retry-After` header (seconds) before retrying.\n\n## Error Format\nAll non-2xx responses return JSON with the shape `{ error: { code, message, hint?, details? } }`. Pattern-match on `error.code` rather than `error.message`. Every documented 4xx/5xx response in this spec references the shared `Error` schema.\n\n## Versioning & Deprecation Policy\nDex uses **URL-path major versioning**: every endpoint is namespaced under a major version (`/v1`, `/v2`). The version is part of the path, never a header or query parameter, so a URL always pins the contract it was written against.\n\n**What can change inside a major version (no notice, treat as routine):**\n\n- New endpoints and new optional request fields.\n- New fields added to existing response objects.\n- New values in non-exhaustive enums, and new `error.code` values.\n\nWrite clients that **tolerate unknown response fields** and that pattern-match on `error.code` with a default branch. Additive changes will not be treated as breaking.\n\n**What never changes inside a major version:** removing or renaming a field or endpoint, changing a field type, tightening validation, or changing the meaning of an existing `error.code`. Changes like these ship as a **new major version path** (for example `/v2`) while the previous version keeps working.\n\n**Current status:** `/v1` is the stable, supported public API surface. It is **not deprecated and has no sunset date**. `/v2` is the newer canonical surface and is additive — adopting it is optional.\n\n**How a deprecation would be announced.** If Dex ever deprecates a version or an individual endpoint, all of the following happen before anything is removed:\n\n1. **At least 12 months of notice** before the endpoint stops responding, announced by email to every API-key owner and published in the API changelog.\n2. The affected operations are marked `deprecated: true` in this OpenAPI document, with the replacement named in the operation description.\n3. Affected responses carry the `Deprecation` and `Sunset` response headers ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594.html)) for the entire notice window, so automated clients can detect the change without reading release notes.\n4. A migration guide is published alongside the announcement.\n\nThe absence of `deprecated: true` on an operation and of `Deprecation`/`Sunset` headers on its responses means that endpoint is fully supported. No Dex API endpoint carries them today.","contact":{"name":"Dex Support","email":"contact@getdex.com","url":"https://getdex.com"},"license":{"name":"Dex Terms of Service","url":"https://getdex.com/termsofservice"},"termsOfService":"https://getdex.com/termsofservice"},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Use your Dex API key (e.g. dex_abc123...) as the Bearer token."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable slug. Pattern-match on this, not `message`.","example":"rate_limited"},"message":{"type":"string","description":"Human-readable description of the error."},"hint":{"type":"string","description":"Optional resolution guidance (e.g. \"Respect the Retry-After header before retrying.\")."},"details":{"type":"object","additionalProperties":true,"description":"Optional structured context. For validation errors, typically `{ fields: { : } }`."}}}}}},"headers":{"RateLimit-Limit":{"description":"Max requests in the current window. IETF-standard spelling of `X-RateLimit-Limit`.","schema":{"type":"integer","minimum":0},"example":600},"RateLimit-Remaining":{"description":"Requests remaining in the current window. IETF-standard spelling of `X-RateLimit-Remaining`.","schema":{"type":"integer","minimum":0},"example":599},"RateLimit-Reset":{"description":"Seconds until the current window resets (not a Unix epoch). IETF-standard spelling of `X-RateLimit-Reset`.","schema":{"type":"integer","minimum":0},"example":58},"RateLimit":{"description":"Structured-field form of the current quota state: `\"default\";r=;t=`.","schema":{"type":"string"},"example":"\"default\";r=599;t=58"},"RateLimit-Policy":{"description":"Structured-field description of the quota policy in force: `\"default\";q=;w=60`.","schema":{"type":"string"},"example":"\"default\";q=600;w=60"},"X-RateLimit-Limit":{"description":"Max requests in the current window.","schema":{"type":"integer","minimum":0},"example":600},"X-RateLimit-Remaining":{"description":"Requests remaining in the current window.","schema":{"type":"integer","minimum":0},"example":599},"X-RateLimit-Reset":{"description":"Seconds until the current rate-limit window resets (not a Unix epoch). Matches @fastify/rate-limit's default semantics.","schema":{"type":"integer","minimum":0},"example":58},"Retry-After":{"description":"Seconds to wait before retrying. Sent on 429; may be sent on 503.","schema":{"type":"integer","minimum":0},"example":30}}},"paths":{"/v1":{"get":{"responses":{"200":{"description":"The API is reachable. Returns a plain-text greeting; use it as an unauthenticated liveness probe for the v1 surface.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"text/plain":{"schema":{"type":"string","example":"Welcome to Dex Lightning API!"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getApiRootV1","summary":"API root (v1)","description":"Unauthenticated liveness check for the v1 surface. Takes no parameters and returns a plain-text greeting with a 200 status. Use it to confirm connectivity and DNS before authenticating; it does not validate your API key.","security":[]}},"/v1/contacts/{contactId}":{"get":{"tags":["contacts"],"parameters":[{"schema":{"type":"object","properties":{"linkedin_data":{"type":"boolean"},"groups_count":{"type":"boolean"},"coordinates":{"type":"boolean"}},"additionalProperties":{"type":"boolean"}},"in":"query","name":"include","required":false},{"schema":{"type":"object","properties":{"linkedin_data":{"type":"boolean"},"groups_count":{"type":"boolean"},"coordinates":{"type":"boolean"}},"additionalProperties":{"type":"boolean"}},"in":"query","name":"select","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"contactId","required":true}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"data":{"nullable":true,"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"first_name":{"nullable":true,"type":"string"},"last_name":{"nullable":true,"type":"string"},"full_name":{"nullable":true,"type":"string"},"description":{"nullable":true,"type":"string"},"job_title":{"nullable":true,"type":"string"},"company":{"nullable":true,"type":"string"},"education":{"nullable":true,"type":"string"},"legacy_location":{"nullable":true,"type":"string"},"image_url":{"nullable":true,"type":"string"},"business_card_url":{"nullable":true,"type":"string"},"website":{"nullable":true,"type":"string"},"image_source":{"nullable":true,"type":"string"},"birthday":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"birthday_year":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"linkedin":{"nullable":true,"type":"string"},"twitter":{"nullable":true,"type":"string"},"facebook":{"nullable":true,"type":"string"},"instagram":{"nullable":true,"type":"string"},"telegram":{"nullable":true,"type":"string"},"tiktok":{"nullable":true,"type":"string"},"youtube":{"nullable":true,"type":"string"},"starred":{"type":"boolean"},"is_archived":{"type":"boolean"},"ignore_merge":{"type":"boolean"},"never_keep_in_touch":{"type":"boolean"},"source":{"type":"string"},"priority_tier":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"frequency":{"nullable":true,"type":"string"},"frequency_text":{"nullable":true,"type":"string"},"last_seen_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"last_reminder_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"next_reminder_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"first_met_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"first_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_companies":{"nullable":true,"type":"string"},"linkedin_education":{"nullable":true,"type":"string"},"linkedin_enhance_date":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_last_message_snippet":{"nullable":true,"type":"string"},"linkedin_message_link":{"nullable":true,"type":"string"},"whatsapp_message_link":{"nullable":true,"type":"string"},"whatsapp_message_snippet":{"nullable":true,"type":"string"},"whatsapp_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"imessage_message_link":{"nullable":true,"type":"string"},"imessage_message_snippet":{"nullable":true,"type":"string"},"imessage_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"instagram_message_link":{"nullable":true,"type":"string"},"instagram_message_snippet":{"nullable":true,"type":"string"},"instagram_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"gmail_last_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"gmail_last_interaction_provider":{"nullable":true,"type":"string","enum":["GOOGLE","OFFICE365"]},"gmail_last_interaction_provider_id":{"nullable":true,"type":"string"},"gmail_last_interaction_subject":{"nullable":true,"type":"string"},"gcal_last_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"gcal_last_interaction_provider":{"nullable":true,"type":"string","enum":["GOOGLE","OFFICE365"]},"gcal_last_interaction_provider_id":{"nullable":true,"type":"string"},"gcal_last_interaction_title":{"nullable":true,"type":"string"},"phone_call_interaction_snippet":{"nullable":true,"type":"string"},"phone_call_last_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"web_search_summary":{"nullable":true},"created_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"updated_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"geocode_attempts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"geocode_failed_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"_count":{"type":"object","properties":{"groups_contacts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["groups_contacts"],"additionalProperties":false},"frequency_interval":{},"linkedin_data":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"latitude":{"nullable":true,"type":"number"},"longitude":{"nullable":true,"type":"number"},"contact_emails":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_phone_numbers":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_birthdays":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"contact_locations":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contacts_custom_fields":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"legacy_contact_addresses":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"groups_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"tags_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"timeline_items_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"reminders_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_relations_contact_relations_sourceTocontacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_relations_contact_relations_destinationTocontacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"feed_items":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"keep_in_touch_reminders":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}}},"required":["id"],"additionalProperties":false}},"required":["error","data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getContactV1","summary":"Get a contact","description":"Retrieve a single contact by its unique ID. Returns the full contact record including name, company, job title, emails, phone numbers, and all associated metadata.","x-mint":{"content":"## Use cases\n\n- Display a contact detail page in your application\n- Fetch the latest data for a specific contact before updating it\n- Verify a contact exists before performing operations on it\n\nThe contact must belong to the authenticated user. Requesting a contact that does not exist or belongs to another user returns a 404 error."}},"put":{"tags":["contacts"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"full_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"first_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"job_title":{"anyOf":[{"type":"string"},{"type":"null"}]},"legacy_location":{"anyOf":[{"type":"string"},{"type":"null"}]},"company":{"anyOf":[{"type":"string"},{"type":"null"}]},"education":{"anyOf":[{"type":"string"},{"type":"null"}]},"starred":{"type":"boolean"},"source":{"type":"string","enum":["linkedin_sync","facebook_import","cal_ingest","email_ingest","web_import","csv_import","whatsapp_sync","imessage_sync","phone_calls_sync","mobile","mobile_import","instagram_sync","oauth_interaction"]},"coordinates":{"type":"object","properties":{"operation":{"type":"string","enum":["set","delete"]},"data":{"type":"object","properties":{"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180}},"additionalProperties":false}},"required":["operation"],"additionalProperties":false},"priority_tier":{"anyOf":[{"type":"integer","minimum":1,"maximum":32767},{"type":"null"}]},"image_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"image_source":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"business_card_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"website":{"anyOf":[{},{"type":"null"}]},"birthday":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"birthday_year":{"anyOf":[{"type":"number","minimum":1900,"maximum":2100},{"type":"null"}]},"frequency":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_seen_at":{"anyOf":[{},{"type":"null"}]},"first_met_at":{"anyOf":[{},{"type":"null"}]},"never_keep_in_touch":{"type":"boolean"},"next_reminder_at":{},"linkedin":{"anyOf":[{"type":"string"},{"type":"null"}]},"twitter":{"anyOf":[{"type":"string"},{"type":"null"}]},"facebook":{"anyOf":[{"type":"string"},{"type":"null"}]},"instagram":{"anyOf":[{"type":"string"},{"type":"null"}]},"telegram":{"anyOf":[{"type":"string"},{"type":"null"}]},"tiktok":{"anyOf":[{"type":"string"},{"type":"null"}]},"youtube":{"anyOf":[{"type":"string"},{"type":"null"}]},"whatsapp_message_link":{"type":"string"},"whatsapp_message_snippet":{"anyOf":[{"type":"string"},{"type":"null"}]},"whatsapp_last_message_at":{"anyOf":[{},{"type":"null"}]},"imessage_message_link":{"type":"string"},"imessage_message_snippet":{"anyOf":[{"type":"string"},{"type":"null"}]},"imessage_last_message_at":{"anyOf":[{},{"type":"null"}]},"linkedin_message_link":{"type":"string","maxLength":600},"linkedin_last_message_snippet":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"linkedin_last_message_at":{"anyOf":[{},{"type":"null"}]},"linkedin_data":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"instagram_message_link":{"type":"string"},"instagram_message_snippet":{"anyOf":[{"type":"string"},{"type":"null"}]},"instagram_last_message_at":{"anyOf":[{},{"type":"null"}]},"gmail_last_interaction_at":{"anyOf":[{},{"type":"null"}]},"gmail_last_interaction_provider_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"gmail_last_interaction_subject":{"anyOf":[{"type":"string"},{"type":"null"}]},"gmail_last_interaction_provider":{"anyOf":[{"type":"string","enum":["GOOGLE","OFFICE365"]},{"type":"null"}]},"gcal_last_interaction_at":{"anyOf":[{},{"type":"null"}]},"gcal_last_interaction_provider_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"gcal_last_interaction_title":{"anyOf":[{"type":"string"},{"type":"null"}]},"gcal_last_interaction_provider":{"anyOf":[{"type":"string","enum":["GOOGLE","OFFICE365"]},{"type":"null"}]},"phone_call_last_interaction_at":{"anyOf":[{},{"type":"null"}]},"phone_call_interaction_snippet":{"anyOf":[{"type":"string"},{"type":"null"}]},"web_search_summary":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"legacy_contact_addresses":{"type":"array","items":{"type":"object","properties":{"formatted":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false}},"contact_emails":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string","maxLength":320},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"ranking":{"type":"number"}},"required":["email"],"additionalProperties":false}},"contact_phone_numbers":{"type":"array","items":{"type":"object","properties":{"phone_number":{"type":"string","maxLength":50},"country_code":{"anyOf":[{"type":"string","maxLength":4},{"type":"null"}]},"phone_number_sanitized":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"ranking":{"type":"number"}},"required":["phone_number"],"additionalProperties":false}},"groups_contacts":{"type":"array","items":{"type":"object","properties":{"group_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["group_id"],"additionalProperties":false}},"tags_contacts":{"anyOf":[{"type":"object","properties":{"append":{"type":"array","items":{"type":"object","properties":{"tag_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["tag_id"],"additionalProperties":false}},"remove":{"type":"array","items":{"type":"object","properties":{"tag_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"contact_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["tag_id","contact_id"],"additionalProperties":false}},"replace":{}},"additionalProperties":false},{"type":"object","properties":{"append":{},"remove":{},"replace":{"type":"array","items":{"type":"object","properties":{"tag_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["tag_id"],"additionalProperties":false}}},"additionalProperties":false}]},"custom_fields":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"type":{"type":"string","enum":["input"]},"text_value":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}]},"custom_field":{}},"required":["id","type","text_value"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"type":{"type":"string","enum":["autocomplete"]},"text_value":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}]},"custom_field":{}},"required":["id","type","text_value"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"type":{"type":"string","enum":["datepicker"]},"text_value":{"anyOf":[{"type":"string"},{"type":"null"}]},"date_value":{"anyOf":[{},{"type":"null"}]},"custom_field":{}},"required":["id","type"],"additionalProperties":false}]}},"contact_birthdays":{"type":"object","properties":{"contact_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"last_dismissal_year":{"type":"number","minimum":1900,"maximum":2100}},"additionalProperties":false},"is_archived":{"type":"boolean"},"ignore_merge":{"type":"boolean"},"related_contacts":{"anyOf":[{"type":"object","properties":{"append":{"type":"array","items":{"type":"object","properties":{"destination":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"source_contact":{},"destination_contact":{}},"required":["destination"],"additionalProperties":false}},"remove":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"source":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"destination":{}},"required":["source","destination"],"additionalProperties":false},{"type":"object","properties":{"source":{},"destination":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["source","destination"],"additionalProperties":false}]}},"replace":{}},"additionalProperties":false},{"type":"object","properties":{"append":{},"remove":{},"replace":{"type":"array","items":{"type":"object","properties":{"destination":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"source_contact":{},"destination_contact":{}},"required":["destination"],"additionalProperties":false}}},"additionalProperties":false}]}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"contactId","required":true}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"data":{"type":"object","properties":{"contact":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"first_name":{"nullable":true,"type":"string"},"last_name":{"nullable":true,"type":"string"},"full_name":{"nullable":true,"type":"string"},"description":{"nullable":true,"type":"string"},"job_title":{"nullable":true,"type":"string"},"company":{"nullable":true,"type":"string"},"education":{"nullable":true,"type":"string"},"legacy_location":{"nullable":true,"type":"string"},"image_url":{"nullable":true,"type":"string"},"business_card_url":{"nullable":true,"type":"string"},"website":{"nullable":true,"type":"string"},"image_source":{"nullable":true,"type":"string"},"birthday":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"birthday_year":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"linkedin":{"nullable":true,"type":"string"},"twitter":{"nullable":true,"type":"string"},"facebook":{"nullable":true,"type":"string"},"instagram":{"nullable":true,"type":"string"},"telegram":{"nullable":true,"type":"string"},"tiktok":{"nullable":true,"type":"string"},"youtube":{"nullable":true,"type":"string"},"starred":{"type":"boolean"},"is_archived":{"type":"boolean"},"ignore_merge":{"type":"boolean"},"never_keep_in_touch":{"type":"boolean"},"source":{"type":"string"},"priority_tier":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"frequency":{"nullable":true,"type":"string"},"frequency_text":{"nullable":true,"type":"string"},"last_seen_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"last_reminder_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"next_reminder_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"first_met_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"first_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_companies":{"nullable":true,"type":"string"},"linkedin_education":{"nullable":true,"type":"string"},"linkedin_enhance_date":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_last_message_snippet":{"nullable":true,"type":"string"},"linkedin_message_link":{"nullable":true,"type":"string"},"whatsapp_message_link":{"nullable":true,"type":"string"},"whatsapp_message_snippet":{"nullable":true,"type":"string"},"whatsapp_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"imessage_message_link":{"nullable":true,"type":"string"},"imessage_message_snippet":{"nullable":true,"type":"string"},"imessage_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"instagram_message_link":{"nullable":true,"type":"string"},"instagram_message_snippet":{"nullable":true,"type":"string"},"instagram_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"gmail_last_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"gmail_last_interaction_provider":{"nullable":true,"type":"string","enum":["GOOGLE","OFFICE365"]},"gmail_last_interaction_provider_id":{"nullable":true,"type":"string"},"gmail_last_interaction_subject":{"nullable":true,"type":"string"},"gcal_last_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"gcal_last_interaction_provider":{"nullable":true,"type":"string","enum":["GOOGLE","OFFICE365"]},"gcal_last_interaction_provider_id":{"nullable":true,"type":"string"},"gcal_last_interaction_title":{"nullable":true,"type":"string"},"phone_call_interaction_snippet":{"nullable":true,"type":"string"},"phone_call_last_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"web_search_summary":{"nullable":true},"created_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"updated_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"geocode_attempts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"geocode_failed_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"_count":{"type":"object","properties":{"groups_contacts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["groups_contacts"],"additionalProperties":false},"frequency_interval":{},"linkedin_data":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"latitude":{"nullable":true,"type":"number"},"longitude":{"nullable":true,"type":"number"},"contact_emails":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_phone_numbers":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_birthdays":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"contact_locations":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contacts_custom_fields":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"legacy_contact_addresses":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"groups_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"tags_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"timeline_items_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"reminders_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_relations_contact_relations_sourceTocontacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_relations_contact_relations_destinationTocontacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"feed_items":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"keep_in_touch_reminders":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}}},"required":["id"],"additionalProperties":false}},"required":["contact"],"additionalProperties":false}},"required":["error","data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"updateContactV1","summary":"Update a contact","description":"Update a single contact by its ID. Only the fields included in the request body are modified; omitted fields remain unchanged.","x-mint":{"content":"## Use cases\n\n- Update a contact's job title or company after a career change\n- Star or archive a contact\n- Add or change a contact's email address or phone number\n\nThis performs a partial update. Only send the fields you want to change — any field you omit will keep its current value."}},"delete":{"tags":["contacts"],"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"contactId","required":true}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"message":{"type":"string"}},"required":["error","message"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"deleteContactV1","summary":"Delete a contact","description":"Permanently delete a single contact by its ID. This removes the contact and all associated data including notes, reminders, and tag associations.","x-mint":{"content":"## Use cases\n\n- Remove a contact that was created by mistake\n- Delete a contact after they have been merged with another\n- Clean up a single outdated contact record\n\nThis action is permanent and cannot be undone. Consider archiving the contact instead if you may need the data later."}}},"/v1/contacts/":{"get":{"tags":["contacts"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":9007199254740991},"in":"query","name":"take","required":false},{"schema":{"type":"integer","minimum":0,"maximum":9007199254740991},"in":"query","name":"skip","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"cursor","required":false},{"schema":{"type":"object","properties":{"in":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"description":"Match contacts whose id is in this set (single id or array)."},"not_in":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"description":"Exclude contacts whose id is in this set (single id or array)."},"ignore_merge":{"type":"boolean","description":"Filter by the `ignore_merge` flag (excluded from merge suggestions)."},"is_starred":{"type":"boolean","description":"Match starred (true) or non-starred (false) contacts."},"is_archived":{"type":"boolean","description":"Match archived (true) or active (false) contacts. Defaults to false when omitted."},"has_priority_tier":{"anyOf":[{"type":"integer","minimum":1,"maximum":9007199254740991},{"type":"array","items":{"type":"integer","minimum":1,"maximum":9007199254740991}},{"type":"boolean"}],"description":"Relationship priority tier: a tier number, an array of tiers (OR), or a boolean (true = any tier set, false = none)."},"has_linkedin":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"LinkedIn slug: an exact slug string, or a boolean for presence/absence of a LinkedIn handle."},"has_instagram":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"Instagram slug: an exact slug string, or a boolean for presence/absence of an Instagram handle."},"has_twitter":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"Twitter/X slug: an exact slug string, or a boolean for presence/absence of a Twitter handle."},"has_source":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Contact source: a single source string or an array of sources (OR)."},"has_name":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Full name: a bare string (fuzzy contains), an array of exact names, or `{ contains }` / `{ eq }` for explicit fuzzy vs exact match."},"has_groups":{"anyOf":[{"type":"object","properties":{"not":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},"required":["not"],"additionalProperties":false},{"type":"boolean"},{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"array","items":{"type":"string"}}],"description":"Group membership: a group id, an array of group ids (OR), a boolean for any/no group, or `{ not }` to exclude group id(s)."},"has_user_created_groups":{"type":"boolean","description":"Non-system group membership: true for at least one user-created group; false for no user-created groups, including contacts with zero memberships or only Dex system-group memberships."},"has_grouping_signal":{"type":"boolean","description":"Internal organize prefilter: title, company, location, or LinkedIn summary is non-null and non-empty. Whitespace-only values are removed by the organize serializer.","enum":[true]},"has_groups_all":{"description":"Array of group-id rows: AND across rows, OR within each row (contact must be in at least one group from every row).","type":"array","items":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"has_frequency":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"Keep-in-touch cadence: a frequency string, or a boolean for presence/absence of a cadence."},"has_location":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"Location: a string (fuzzy, accent-insensitive match), or a boolean for presence/absence of a location."},"has_location_exact":{"type":"string","description":"Location: exact string match (not fuzzy)."},"has_job_title":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Job title: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }` for explicit fuzzy vs exact match."},"has_never_keep_in_touch":{"type":"boolean","description":"Filter by the `never_keep_in_touch` flag."},"has_created_at":{"description":"Creation-date range: `{ gte?, lte? }` ISO 8601 datetimes (at least one bound required).","type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false},"has_updated_at":{"description":"Last-updated-date range: `{ gte?, lte? }` ISO 8601 datetimes (at least one bound required).","type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false},"has_birthday":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{},{"type":"boolean"}],"description":"Birthday: a specific date (matches on day + month), or true for any birthday set."},"has_tag":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Match contacts carrying this single tag id."},"has_tags":{"anyOf":[{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"type":"object","properties":{"not":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}]}},"required":["not"],"additionalProperties":false}],"description":"Tags: an array of tag ids (OR), or `{ not }` to exclude tag id(s)."},"has_tags_all":{"description":"Array of tag-id rows: AND across rows, OR within each row (contact must carry at least one tag from every row).","type":"array","items":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"has_company":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Company: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }` for explicit fuzzy vs exact match."},"has_education":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Education: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }`."},"has_description":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Description/notes: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }`."},"has_linkedin_companies":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"LinkedIn companies text: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }`."},"has_linkedin_education":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"LinkedIn education text: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }`."},"has_email":{"type":"boolean","description":"Match contacts that have (true) or lack (false) at least one email."},"has_phone_number":{"type":"boolean","description":"Match contacts that have (true) or lack (false) at least one phone number."},"not_has_name":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose full name fuzzily matches this string / any of these strings."},"not_has_company":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose company fuzzily matches this string / any of these strings."},"not_has_job_title":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose job title fuzzily matches this string / any of these strings."},"not_has_education":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose education fuzzily matches this string / any of these strings."},"not_has_description":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose description fuzzily matches this string / any of these strings."},"not_has_linkedin_companies":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose LinkedIn companies text fuzzily matches this string / any of these strings."},"not_has_linkedin_education":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose LinkedIn education text fuzzily matches this string / any of these strings."},"has_linkedin_last_message_at":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false}],"description":"LinkedIn last-message time: a boolean for presence/absence, or a `{ gte?, lte? }` ISO 8601 range."},"has_last_seen_at":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false}],"description":"Last-seen (last interaction) time — alias for has_interaction: a boolean for presence/absence, or a `{ gte?, lte? }` ISO 8601 range."},"has_distance":{"type":"object","properties":{"lat":{"type":"number"},"lon":{"type":"number"},"meters":{"type":"number"},"label":{"type":"string"}},"required":["lat","lon","meters"],"additionalProperties":false,"description":"Geo radius filter: contacts within `meters` of `{ lat, lon }` (PostGIS ST_DWithin on geocoded coordinates). `label` is an optional display name for the point."},"has_interaction":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false}],"description":"Interaction (last-seen) time: a boolean for presence/absence, or a `{ gte?, lte? }` ISO 8601 range."},"has_next_reminder":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false}],"description":"Next-reminder time: a boolean for presence/absence, or a `{ gte?, lte? }` ISO 8601 range."},"custom_fields":{"minItems":1,"type":"array","items":{"type":"object","properties":{"field_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"operator":{"type":"string","enum":["contains","eq","in","not_in","present","absent","gte","lte"]},"value":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},"required":["field_id","operator"],"additionalProperties":false},"description":"User-defined custom-field filters. Each clause is `{ field_id, operator, value? }`; multiple clauses AND together. Operators: contains, eq, in, not_in, present, absent, gte, lte."},"_or":{"description":"Compound-OR escape hatch: an array of filter branches combined with OR, each ANDed with the top-level keys. One level deep — branches cannot themselves contain `_or`.","minItems":1,"type":"array","items":{"type":"object","properties":{"in":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"description":"Match contacts whose id is in this set (single id or array)."},"not_in":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"description":"Exclude contacts whose id is in this set (single id or array)."},"ignore_merge":{"type":"boolean","description":"Filter by the `ignore_merge` flag (excluded from merge suggestions)."},"is_starred":{"type":"boolean","description":"Match starred (true) or non-starred (false) contacts."},"is_archived":{"type":"boolean","description":"Match archived (true) or active (false) contacts. Defaults to false when omitted."},"has_priority_tier":{"anyOf":[{"type":"integer","minimum":1,"maximum":9007199254740991},{"type":"array","items":{"type":"integer","minimum":1,"maximum":9007199254740991}},{"type":"boolean"}],"description":"Relationship priority tier: a tier number, an array of tiers (OR), or a boolean (true = any tier set, false = none)."},"has_linkedin":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"LinkedIn slug: an exact slug string, or a boolean for presence/absence of a LinkedIn handle."},"has_instagram":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"Instagram slug: an exact slug string, or a boolean for presence/absence of an Instagram handle."},"has_twitter":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"Twitter/X slug: an exact slug string, or a boolean for presence/absence of a Twitter handle."},"has_source":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Contact source: a single source string or an array of sources (OR)."},"has_name":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Full name: a bare string (fuzzy contains), an array of exact names, or `{ contains }` / `{ eq }` for explicit fuzzy vs exact match."},"has_groups":{"anyOf":[{"type":"object","properties":{"not":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},"required":["not"],"additionalProperties":false},{"type":"boolean"},{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"array","items":{"type":"string"}}],"description":"Group membership: a group id, an array of group ids (OR), a boolean for any/no group, or `{ not }` to exclude group id(s)."},"has_user_created_groups":{"type":"boolean","description":"Non-system group membership: true for at least one user-created group; false for no user-created groups, including contacts with zero memberships or only Dex system-group memberships."},"has_grouping_signal":{"type":"boolean","description":"Internal organize prefilter: title, company, location, or LinkedIn summary is non-null and non-empty. Whitespace-only values are removed by the organize serializer.","enum":[true]},"has_groups_all":{"description":"Array of group-id rows: AND across rows, OR within each row (contact must be in at least one group from every row).","type":"array","items":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"has_frequency":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"Keep-in-touch cadence: a frequency string, or a boolean for presence/absence of a cadence."},"has_location":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"Location: a string (fuzzy, accent-insensitive match), or a boolean for presence/absence of a location."},"has_location_exact":{"type":"string","description":"Location: exact string match (not fuzzy)."},"has_job_title":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Job title: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }` for explicit fuzzy vs exact match."},"has_never_keep_in_touch":{"type":"boolean","description":"Filter by the `never_keep_in_touch` flag."},"has_created_at":{"description":"Creation-date range: `{ gte?, lte? }` ISO 8601 datetimes (at least one bound required).","type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false},"has_updated_at":{"description":"Last-updated-date range: `{ gte?, lte? }` ISO 8601 datetimes (at least one bound required).","type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false},"has_birthday":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{},{"type":"boolean"}],"description":"Birthday: a specific date (matches on day + month), or true for any birthday set."},"has_tag":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Match contacts carrying this single tag id."},"has_tags":{"anyOf":[{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"type":"object","properties":{"not":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}]}},"required":["not"],"additionalProperties":false}],"description":"Tags: an array of tag ids (OR), or `{ not }` to exclude tag id(s)."},"has_tags_all":{"description":"Array of tag-id rows: AND across rows, OR within each row (contact must carry at least one tag from every row).","type":"array","items":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"has_company":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Company: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }` for explicit fuzzy vs exact match."},"has_education":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Education: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }`."},"has_description":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Description/notes: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }`."},"has_linkedin_companies":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"LinkedIn companies text: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }`."},"has_linkedin_education":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"LinkedIn education text: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }`."},"has_email":{"type":"boolean","description":"Match contacts that have (true) or lack (false) at least one email."},"has_phone_number":{"type":"boolean","description":"Match contacts that have (true) or lack (false) at least one phone number."},"not_has_name":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose full name fuzzily matches this string / any of these strings."},"not_has_company":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose company fuzzily matches this string / any of these strings."},"not_has_job_title":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose job title fuzzily matches this string / any of these strings."},"not_has_education":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose education fuzzily matches this string / any of these strings."},"not_has_description":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose description fuzzily matches this string / any of these strings."},"not_has_linkedin_companies":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose LinkedIn companies text fuzzily matches this string / any of these strings."},"not_has_linkedin_education":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose LinkedIn education text fuzzily matches this string / any of these strings."},"has_linkedin_last_message_at":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false}],"description":"LinkedIn last-message time: a boolean for presence/absence, or a `{ gte?, lte? }` ISO 8601 range."},"has_last_seen_at":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false}],"description":"Last-seen (last interaction) time — alias for has_interaction: a boolean for presence/absence, or a `{ gte?, lte? }` ISO 8601 range."},"has_distance":{"type":"object","properties":{"lat":{"type":"number"},"lon":{"type":"number"},"meters":{"type":"number"},"label":{"type":"string"}},"required":["lat","lon","meters"],"additionalProperties":false,"description":"Geo radius filter: contacts within `meters` of `{ lat, lon }` (PostGIS ST_DWithin on geocoded coordinates). `label` is an optional display name for the point."},"has_interaction":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false}],"description":"Interaction (last-seen) time: a boolean for presence/absence, or a `{ gte?, lte? }` ISO 8601 range."},"has_next_reminder":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false}],"description":"Next-reminder time: a boolean for presence/absence, or a `{ gte?, lte? }` ISO 8601 range."},"custom_fields":{"minItems":1,"type":"array","items":{"type":"object","properties":{"field_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"operator":{"type":"string","enum":["contains","eq","in","not_in","present","absent","gte","lte"]},"value":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},"required":["field_id","operator"],"additionalProperties":false},"description":"User-defined custom-field filters. Each clause is `{ field_id, operator, value? }`; multiple clauses AND together. Operators: contains, eq, in, not_in, present, absent, gte, lte."}},"additionalProperties":false}}},"additionalProperties":false},"in":"query","name":"where","required":false},{"schema":{},"in":"query","name":"orderBy","required":false},{"schema":{"type":"object","properties":{"linkedin_data":{"type":"boolean"},"groups_count":{"type":"boolean"},"coordinates":{"type":"boolean"}},"additionalProperties":{"type":"boolean"}},"in":"query","name":"include","required":false},{"schema":{"type":"object","properties":{"linkedin_data":{"type":"boolean"},"groups_count":{"type":"boolean"},"coordinates":{"type":"boolean"}},"additionalProperties":{"type":"boolean"}},"in":"query","name":"select","required":false}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"first_name":{"nullable":true,"type":"string"},"last_name":{"nullable":true,"type":"string"},"full_name":{"nullable":true,"type":"string"},"description":{"nullable":true,"type":"string"},"job_title":{"nullable":true,"type":"string"},"company":{"nullable":true,"type":"string"},"education":{"nullable":true,"type":"string"},"legacy_location":{"nullable":true,"type":"string"},"image_url":{"nullable":true,"type":"string"},"business_card_url":{"nullable":true,"type":"string"},"website":{"nullable":true,"type":"string"},"image_source":{"nullable":true,"type":"string"},"birthday":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"birthday_year":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"linkedin":{"nullable":true,"type":"string"},"twitter":{"nullable":true,"type":"string"},"facebook":{"nullable":true,"type":"string"},"instagram":{"nullable":true,"type":"string"},"telegram":{"nullable":true,"type":"string"},"tiktok":{"nullable":true,"type":"string"},"youtube":{"nullable":true,"type":"string"},"starred":{"type":"boolean"},"is_archived":{"type":"boolean"},"ignore_merge":{"type":"boolean"},"never_keep_in_touch":{"type":"boolean"},"source":{"type":"string"},"priority_tier":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"frequency":{"nullable":true,"type":"string"},"frequency_text":{"nullable":true,"type":"string"},"last_seen_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"last_reminder_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"next_reminder_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"first_met_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"first_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_companies":{"nullable":true,"type":"string"},"linkedin_education":{"nullable":true,"type":"string"},"linkedin_enhance_date":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_last_message_snippet":{"nullable":true,"type":"string"},"linkedin_message_link":{"nullable":true,"type":"string"},"whatsapp_message_link":{"nullable":true,"type":"string"},"whatsapp_message_snippet":{"nullable":true,"type":"string"},"whatsapp_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"imessage_message_link":{"nullable":true,"type":"string"},"imessage_message_snippet":{"nullable":true,"type":"string"},"imessage_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"instagram_message_link":{"nullable":true,"type":"string"},"instagram_message_snippet":{"nullable":true,"type":"string"},"instagram_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"gmail_last_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"gmail_last_interaction_provider":{"nullable":true,"type":"string","enum":["GOOGLE","OFFICE365"]},"gmail_last_interaction_provider_id":{"nullable":true,"type":"string"},"gmail_last_interaction_subject":{"nullable":true,"type":"string"},"gcal_last_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"gcal_last_interaction_provider":{"nullable":true,"type":"string","enum":["GOOGLE","OFFICE365"]},"gcal_last_interaction_provider_id":{"nullable":true,"type":"string"},"gcal_last_interaction_title":{"nullable":true,"type":"string"},"phone_call_interaction_snippet":{"nullable":true,"type":"string"},"phone_call_last_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"web_search_summary":{"nullable":true},"created_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"updated_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"geocode_attempts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"geocode_failed_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"_count":{"type":"object","properties":{"groups_contacts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["groups_contacts"],"additionalProperties":false},"frequency_interval":{},"linkedin_data":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"latitude":{"nullable":true,"type":"number"},"longitude":{"nullable":true,"type":"number"},"contact_emails":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_phone_numbers":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_birthdays":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"contact_locations":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contacts_custom_fields":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"legacy_contact_addresses":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"groups_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"tags_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"timeline_items_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"reminders_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_relations_contact_relations_sourceTocontacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_relations_contact_relations_destinationTocontacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"feed_items":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"keep_in_touch_reminders":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}}},"required":["id"],"additionalProperties":false}},"nextCursor":{"nullable":true,"type":"string"},"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["items","count"],"additionalProperties":{}}},"required":["error","data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"listContactsV1","summary":"List contacts","description":"Retrieve a paginated list of contacts for the authenticated user. Supports cursor-based pagination, sorting, and filtering by archived status.","x-mint":{"content":"## Use cases\n\n- Sync your Dex contacts to an external system\n- Build a contact list view with infinite scroll\n- Export all contacts for backup or migration\n\nResults are paginated. Use the `nextCursor` value from the response to fetch the next page. When `nextCursor` is null, you have reached the end of the list."}},"post":{"tags":["contacts"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contacts":{"maxItems":500,"type":"array","items":{"type":"object","properties":{"full_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"first_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"job_title":{"anyOf":[{"type":"string"},{"type":"null"}]},"legacy_location":{"anyOf":[{"type":"string"},{"type":"null"}]},"company":{"anyOf":[{"type":"string"},{"type":"null"}]},"education":{"anyOf":[{"type":"string"},{"type":"null"}]},"starred":{"type":"boolean"},"source":{"type":"string","enum":["linkedin_sync","facebook_import","cal_ingest","email_ingest","web_import","csv_import","whatsapp_sync","imessage_sync","phone_calls_sync","mobile","mobile_import","instagram_sync","oauth_interaction"]},"coordinates":{"type":"object","properties":{"operation":{"type":"string","enum":["set","delete"]},"data":{"type":"object","properties":{"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180}},"additionalProperties":false}},"required":["operation"],"additionalProperties":false},"priority_tier":{"anyOf":[{"type":"integer","minimum":1,"maximum":32767},{"type":"null"}]},"image_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"image_source":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"business_card_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"website":{"anyOf":[{},{"type":"null"}]},"birthday":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"birthday_year":{"anyOf":[{"type":"number","minimum":1900,"maximum":2100},{"type":"null"}]},"frequency":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_seen_at":{"anyOf":[{},{"type":"null"}]},"first_met_at":{"anyOf":[{},{"type":"null"}]},"never_keep_in_touch":{"type":"boolean"},"next_reminder_at":{},"linkedin":{"anyOf":[{"type":"string"},{"type":"null"}]},"twitter":{"anyOf":[{"type":"string"},{"type":"null"}]},"facebook":{"anyOf":[{"type":"string"},{"type":"null"}]},"instagram":{"anyOf":[{"type":"string"},{"type":"null"}]},"telegram":{"anyOf":[{"type":"string"},{"type":"null"}]},"tiktok":{"anyOf":[{"type":"string"},{"type":"null"}]},"youtube":{"anyOf":[{"type":"string"},{"type":"null"}]},"whatsapp_message_link":{"type":"string"},"whatsapp_message_snippet":{"anyOf":[{"type":"string"},{"type":"null"}]},"whatsapp_last_message_at":{"anyOf":[{},{"type":"null"}]},"imessage_message_link":{"type":"string"},"imessage_message_snippet":{"anyOf":[{"type":"string"},{"type":"null"}]},"imessage_last_message_at":{"anyOf":[{},{"type":"null"}]},"linkedin_message_link":{"type":"string","maxLength":600},"linkedin_last_message_snippet":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"linkedin_last_message_at":{"anyOf":[{},{"type":"null"}]},"linkedin_data":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"instagram_message_link":{"type":"string"},"instagram_message_snippet":{"anyOf":[{"type":"string"},{"type":"null"}]},"instagram_last_message_at":{"anyOf":[{},{"type":"null"}]},"gmail_last_interaction_at":{"anyOf":[{},{"type":"null"}]},"gmail_last_interaction_provider_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"gmail_last_interaction_subject":{"anyOf":[{"type":"string"},{"type":"null"}]},"gmail_last_interaction_provider":{"anyOf":[{"type":"string","enum":["GOOGLE","OFFICE365"]},{"type":"null"}]},"gcal_last_interaction_at":{"anyOf":[{},{"type":"null"}]},"gcal_last_interaction_provider_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"gcal_last_interaction_title":{"anyOf":[{"type":"string"},{"type":"null"}]},"gcal_last_interaction_provider":{"anyOf":[{"type":"string","enum":["GOOGLE","OFFICE365"]},{"type":"null"}]},"phone_call_last_interaction_at":{"anyOf":[{},{"type":"null"}]},"phone_call_interaction_snippet":{"anyOf":[{"type":"string"},{"type":"null"}]},"web_search_summary":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"legacy_contact_addresses":{"type":"array","items":{"type":"object","properties":{"formatted":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false}},"contact_emails":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string","maxLength":320},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"ranking":{"type":"number"}},"required":["email"],"additionalProperties":false}},"contact_phone_numbers":{"type":"array","items":{"type":"object","properties":{"phone_number":{"type":"string","maxLength":50},"country_code":{"anyOf":[{"type":"string","maxLength":4},{"type":"null"}]},"phone_number_sanitized":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"ranking":{"type":"number"}},"required":["phone_number"],"additionalProperties":false}},"groups_contacts":{"type":"array","items":{"type":"object","properties":{"group_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["group_id"],"additionalProperties":false}},"tags_contacts":{"type":"array","items":{"type":"object","properties":{"tag_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["tag_id"],"additionalProperties":false}},"custom_fields":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"type":{"type":"string","enum":["input"]},"text_value":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}]},"custom_field":{}},"required":["id","type","text_value"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"type":{"type":"string","enum":["autocomplete"]},"text_value":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}]},"custom_field":{}},"required":["id","type","text_value"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"type":{"type":"string","enum":["datepicker"]},"text_value":{"anyOf":[{"type":"string"},{"type":"null"}]},"date_value":{"anyOf":[{},{"type":"null"}]},"custom_field":{}},"required":["id","type"],"additionalProperties":false}]}},"contact_birthdays":{"type":"object","properties":{"contact_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"last_dismissal_year":{"type":"number","minimum":1900,"maximum":2100}},"additionalProperties":false},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"related_contacts":{"type":"array","items":{"type":"object","properties":{"destination":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"source_contact":{},"destination_contact":{}},"required":["destination"],"additionalProperties":false}}},"additionalProperties":false}},"continueOnError":{"type":"boolean"},"socialLookup":{"type":"boolean"}},"required":["contacts"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"data":{"type":"object","properties":{"contacts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"first_name":{"nullable":true,"type":"string"},"last_name":{"nullable":true,"type":"string"},"full_name":{"nullable":true,"type":"string"},"description":{"nullable":true,"type":"string"},"job_title":{"nullable":true,"type":"string"},"company":{"nullable":true,"type":"string"},"education":{"nullable":true,"type":"string"},"legacy_location":{"nullable":true,"type":"string"},"image_url":{"nullable":true,"type":"string"},"business_card_url":{"nullable":true,"type":"string"},"website":{"nullable":true,"type":"string"},"image_source":{"nullable":true,"type":"string"},"birthday":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"birthday_year":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"linkedin":{"nullable":true,"type":"string"},"twitter":{"nullable":true,"type":"string"},"facebook":{"nullable":true,"type":"string"},"instagram":{"nullable":true,"type":"string"},"telegram":{"nullable":true,"type":"string"},"tiktok":{"nullable":true,"type":"string"},"youtube":{"nullable":true,"type":"string"},"starred":{"type":"boolean"},"is_archived":{"type":"boolean"},"ignore_merge":{"type":"boolean"},"never_keep_in_touch":{"type":"boolean"},"source":{"type":"string"},"priority_tier":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"frequency":{"nullable":true,"type":"string"},"frequency_text":{"nullable":true,"type":"string"},"last_seen_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"last_reminder_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"next_reminder_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"first_met_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"first_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_companies":{"nullable":true,"type":"string"},"linkedin_education":{"nullable":true,"type":"string"},"linkedin_enhance_date":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_last_message_snippet":{"nullable":true,"type":"string"},"linkedin_message_link":{"nullable":true,"type":"string"},"whatsapp_message_link":{"nullable":true,"type":"string"},"whatsapp_message_snippet":{"nullable":true,"type":"string"},"whatsapp_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"imessage_message_link":{"nullable":true,"type":"string"},"imessage_message_snippet":{"nullable":true,"type":"string"},"imessage_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"instagram_message_link":{"nullable":true,"type":"string"},"instagram_message_snippet":{"nullable":true,"type":"string"},"instagram_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"gmail_last_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"gmail_last_interaction_provider":{"nullable":true,"type":"string","enum":["GOOGLE","OFFICE365"]},"gmail_last_interaction_provider_id":{"nullable":true,"type":"string"},"gmail_last_interaction_subject":{"nullable":true,"type":"string"},"gcal_last_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"gcal_last_interaction_provider":{"nullable":true,"type":"string","enum":["GOOGLE","OFFICE365"]},"gcal_last_interaction_provider_id":{"nullable":true,"type":"string"},"gcal_last_interaction_title":{"nullable":true,"type":"string"},"phone_call_interaction_snippet":{"nullable":true,"type":"string"},"phone_call_last_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"web_search_summary":{"nullable":true},"created_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"updated_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"geocode_attempts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"geocode_failed_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"_count":{"type":"object","properties":{"groups_contacts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["groups_contacts"],"additionalProperties":false},"frequency_interval":{},"linkedin_data":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"latitude":{"nullable":true,"type":"number"},"longitude":{"nullable":true,"type":"number"},"contact_emails":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_phone_numbers":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_birthdays":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"contact_locations":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contacts_custom_fields":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"legacy_contact_addresses":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"groups_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"tags_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"timeline_items_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"reminders_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_relations_contact_relations_sourceTocontacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_relations_contact_relations_destinationTocontacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"feed_items":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"keep_in_touch_reminders":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}}},"required":["id"],"additionalProperties":false}}},"required":["contacts"],"additionalProperties":false}},"required":["error","data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"createContactsV1","summary":"Create contacts","description":"Create one or more new contacts for the authenticated user. Accepts an array of contact objects with fields like name, email, phone, company, and job title.","x-mint":{"content":"## Use cases\n\n- Import contacts from a CSV file or external CRM\n- Create a new contact when someone fills out a form\n- Sync contacts from another system into Dex\n\nYou can create multiple contacts in a single request by passing an array. Each contact must have at least a first name or last name."}},"put":{"tags":["contacts"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"contactId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"data":{"type":"object","properties":{"full_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"first_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"job_title":{"anyOf":[{"type":"string"},{"type":"null"}]},"legacy_location":{"anyOf":[{"type":"string"},{"type":"null"}]},"company":{"anyOf":[{"type":"string"},{"type":"null"}]},"education":{"anyOf":[{"type":"string"},{"type":"null"}]},"starred":{"type":"boolean"},"source":{"type":"string","enum":["linkedin_sync","facebook_import","cal_ingest","email_ingest","web_import","csv_import","whatsapp_sync","imessage_sync","phone_calls_sync","mobile","mobile_import","instagram_sync","oauth_interaction"]},"coordinates":{"type":"object","properties":{"operation":{"type":"string","enum":["set","delete"]},"data":{"type":"object","properties":{"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180}},"additionalProperties":false}},"required":["operation"],"additionalProperties":false},"priority_tier":{"anyOf":[{"type":"integer","minimum":1,"maximum":32767},{"type":"null"}]},"image_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"image_source":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"business_card_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"website":{"anyOf":[{},{"type":"null"}]},"birthday":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"birthday_year":{"anyOf":[{"type":"number","minimum":1900,"maximum":2100},{"type":"null"}]},"frequency":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_seen_at":{"anyOf":[{},{"type":"null"}]},"first_met_at":{"anyOf":[{},{"type":"null"}]},"never_keep_in_touch":{"type":"boolean"},"next_reminder_at":{},"linkedin":{"anyOf":[{"type":"string"},{"type":"null"}]},"twitter":{"anyOf":[{"type":"string"},{"type":"null"}]},"facebook":{"anyOf":[{"type":"string"},{"type":"null"}]},"instagram":{"anyOf":[{"type":"string"},{"type":"null"}]},"telegram":{"anyOf":[{"type":"string"},{"type":"null"}]},"tiktok":{"anyOf":[{"type":"string"},{"type":"null"}]},"youtube":{"anyOf":[{"type":"string"},{"type":"null"}]},"whatsapp_message_link":{"type":"string"},"whatsapp_message_snippet":{"anyOf":[{"type":"string"},{"type":"null"}]},"whatsapp_last_message_at":{"anyOf":[{},{"type":"null"}]},"imessage_message_link":{"type":"string"},"imessage_message_snippet":{"anyOf":[{"type":"string"},{"type":"null"}]},"imessage_last_message_at":{"anyOf":[{},{"type":"null"}]},"linkedin_message_link":{"type":"string","maxLength":600},"linkedin_last_message_snippet":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"linkedin_last_message_at":{"anyOf":[{},{"type":"null"}]},"linkedin_data":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"instagram_message_link":{"type":"string"},"instagram_message_snippet":{"anyOf":[{"type":"string"},{"type":"null"}]},"instagram_last_message_at":{"anyOf":[{},{"type":"null"}]},"gmail_last_interaction_at":{"anyOf":[{},{"type":"null"}]},"gmail_last_interaction_provider_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"gmail_last_interaction_subject":{"anyOf":[{"type":"string"},{"type":"null"}]},"gmail_last_interaction_provider":{"anyOf":[{"type":"string","enum":["GOOGLE","OFFICE365"]},{"type":"null"}]},"gcal_last_interaction_at":{"anyOf":[{},{"type":"null"}]},"gcal_last_interaction_provider_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"gcal_last_interaction_title":{"anyOf":[{"type":"string"},{"type":"null"}]},"gcal_last_interaction_provider":{"anyOf":[{"type":"string","enum":["GOOGLE","OFFICE365"]},{"type":"null"}]},"phone_call_last_interaction_at":{"anyOf":[{},{"type":"null"}]},"phone_call_interaction_snippet":{"anyOf":[{"type":"string"},{"type":"null"}]},"web_search_summary":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"legacy_contact_addresses":{"type":"array","items":{"type":"object","properties":{"formatted":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false}},"contact_emails":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string","maxLength":320},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"ranking":{"type":"number"}},"required":["email"],"additionalProperties":false}},"contact_phone_numbers":{"type":"array","items":{"type":"object","properties":{"phone_number":{"type":"string","maxLength":50},"country_code":{"anyOf":[{"type":"string","maxLength":4},{"type":"null"}]},"phone_number_sanitized":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"ranking":{"type":"number"}},"required":["phone_number"],"additionalProperties":false}},"groups_contacts":{"type":"array","items":{"type":"object","properties":{"group_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["group_id"],"additionalProperties":false}},"tags_contacts":{"anyOf":[{"type":"object","properties":{"append":{"type":"array","items":{"type":"object","properties":{"tag_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["tag_id"],"additionalProperties":false}},"remove":{"type":"array","items":{"type":"object","properties":{"tag_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"contact_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["tag_id","contact_id"],"additionalProperties":false}},"replace":{}},"additionalProperties":false},{"type":"object","properties":{"append":{},"remove":{},"replace":{"type":"array","items":{"type":"object","properties":{"tag_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["tag_id"],"additionalProperties":false}}},"additionalProperties":false}]},"custom_fields":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"type":{"type":"string","enum":["input"]},"text_value":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}]},"custom_field":{}},"required":["id","type","text_value"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"type":{"type":"string","enum":["autocomplete"]},"text_value":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}]},"custom_field":{}},"required":["id","type","text_value"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"type":{"type":"string","enum":["datepicker"]},"text_value":{"anyOf":[{"type":"string"},{"type":"null"}]},"date_value":{"anyOf":[{},{"type":"null"}]},"custom_field":{}},"required":["id","type"],"additionalProperties":false}]}},"contact_birthdays":{"type":"object","properties":{"contact_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"last_dismissal_year":{"type":"number","minimum":1900,"maximum":2100}},"additionalProperties":false},"is_archived":{"type":"boolean"},"ignore_merge":{"type":"boolean"},"related_contacts":{"anyOf":[{"type":"object","properties":{"append":{"type":"array","items":{"type":"object","properties":{"destination":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"source_contact":{},"destination_contact":{}},"required":["destination"],"additionalProperties":false}},"remove":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"source":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"destination":{}},"required":["source","destination"],"additionalProperties":false},{"type":"object","properties":{"source":{},"destination":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["source","destination"],"additionalProperties":false}]}},"replace":{}},"additionalProperties":false},{"type":"object","properties":{"append":{},"remove":{},"replace":{"type":"array","items":{"type":"object","properties":{"destination":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"source_contact":{},"destination_contact":{}},"required":["destination"],"additionalProperties":false}}},"additionalProperties":false}]}},"additionalProperties":false}},"required":["contactId","data"],"additionalProperties":false}}}}},"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"data":{"type":"object","properties":{"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["count"],"additionalProperties":false}},"required":["error","data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"updateContactsV1","summary":"Update multiple contacts","description":"Update multiple contacts in a single request. Each contact in the request body must include its ID along with the fields to update.","x-mint":{"content":"## Use cases\n\n- Bulk-update a field across many contacts (e.g., set company name after a merger)\n- Archive or star multiple contacts at once\n- Sync batch changes from an external system\n\nOnly the fields you include in each contact object will be updated. Omitted fields remain unchanged."}},"delete":{"tags":["contacts"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contactIds":{"minItems":1,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"required":["contactIds"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"data":{"type":"object","properties":{"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"contact_ids":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"required":["count","contact_ids"],"additionalProperties":false}},"required":["error","data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"deleteContactsV1","summary":"Delete multiple contacts","description":"Delete multiple contacts in a single request by providing an array of contact IDs. This permanently removes the contacts and their associated data.","x-mint":{"content":"## Use cases\n\n- Clean up duplicate or outdated contacts in bulk\n- Remove imported contacts that are no longer needed\n- Perform bulk housekeeping on your contact database\n\nThis action is permanent and cannot be undone. All notes, reminders, and tag associations for the deleted contacts will also be removed."}}},"/v1/contacts/by-emails":{"post":{"tags":["contacts"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"emails":{"type":"array","items":{"type":"string"}},"createFromOAuthInteractions":{"type":"boolean"}},"required":["emails"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"object","properties":{"linkedin_data":{"type":"boolean"},"groups_count":{"type":"boolean"},"coordinates":{"type":"boolean"}},"additionalProperties":{"type":"boolean"}},"in":"query","name":"include","required":false}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"first_name":{"nullable":true,"type":"string"},"last_name":{"nullable":true,"type":"string"},"full_name":{"nullable":true,"type":"string"},"description":{"nullable":true,"type":"string"},"job_title":{"nullable":true,"type":"string"},"company":{"nullable":true,"type":"string"},"education":{"nullable":true,"type":"string"},"legacy_location":{"nullable":true,"type":"string"},"image_url":{"nullable":true,"type":"string"},"business_card_url":{"nullable":true,"type":"string"},"website":{"nullable":true,"type":"string"},"image_source":{"nullable":true,"type":"string"},"birthday":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"birthday_year":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"linkedin":{"nullable":true,"type":"string"},"twitter":{"nullable":true,"type":"string"},"facebook":{"nullable":true,"type":"string"},"instagram":{"nullable":true,"type":"string"},"telegram":{"nullable":true,"type":"string"},"tiktok":{"nullable":true,"type":"string"},"youtube":{"nullable":true,"type":"string"},"starred":{"type":"boolean"},"is_archived":{"type":"boolean"},"ignore_merge":{"type":"boolean"},"never_keep_in_touch":{"type":"boolean"},"source":{"type":"string"},"priority_tier":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"frequency":{"nullable":true,"type":"string"},"frequency_text":{"nullable":true,"type":"string"},"last_seen_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"last_reminder_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"next_reminder_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"first_met_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"first_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_companies":{"nullable":true,"type":"string"},"linkedin_education":{"nullable":true,"type":"string"},"linkedin_enhance_date":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_last_message_snippet":{"nullable":true,"type":"string"},"linkedin_message_link":{"nullable":true,"type":"string"},"whatsapp_message_link":{"nullable":true,"type":"string"},"whatsapp_message_snippet":{"nullable":true,"type":"string"},"whatsapp_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"imessage_message_link":{"nullable":true,"type":"string"},"imessage_message_snippet":{"nullable":true,"type":"string"},"imessage_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"instagram_message_link":{"nullable":true,"type":"string"},"instagram_message_snippet":{"nullable":true,"type":"string"},"instagram_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"gmail_last_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"gmail_last_interaction_provider":{"nullable":true,"type":"string","enum":["GOOGLE","OFFICE365"]},"gmail_last_interaction_provider_id":{"nullable":true,"type":"string"},"gmail_last_interaction_subject":{"nullable":true,"type":"string"},"gcal_last_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"gcal_last_interaction_provider":{"nullable":true,"type":"string","enum":["GOOGLE","OFFICE365"]},"gcal_last_interaction_provider_id":{"nullable":true,"type":"string"},"gcal_last_interaction_title":{"nullable":true,"type":"string"},"phone_call_interaction_snippet":{"nullable":true,"type":"string"},"phone_call_last_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"web_search_summary":{"nullable":true},"created_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"updated_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"geocode_attempts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"geocode_failed_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"_count":{"type":"object","properties":{"groups_contacts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["groups_contacts"],"additionalProperties":false},"frequency_interval":{},"linkedin_data":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"latitude":{"nullable":true,"type":"number"},"longitude":{"nullable":true,"type":"number"},"contact_emails":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_phone_numbers":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_birthdays":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"contact_locations":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contacts_custom_fields":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"legacy_contact_addresses":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"groups_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"tags_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"timeline_items_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"reminders_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_relations_contact_relations_sourceTocontacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_relations_contact_relations_destinationTocontacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"feed_items":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"keep_in_touch_reminders":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}}},"required":["id"],"additionalProperties":false}}},"required":["error","data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getContactsByEmailsV1","summary":"Find contacts by email","description":"Look up contacts by one or more email addresses. Returns matching contacts for each email provided, useful for resolving email addresses to contact records.","x-mint":{"content":"## Use cases\n\n- Resolve email senders to existing Dex contacts\n- Check if contacts already exist before importing\n- Enrich email threads with contact information from Dex\n\nPass an array of email addresses in the request body. The response maps each email to its matching contact, if one exists."}}},"/v1/contacts/count":{"get":{"tags":["contacts"],"parameters":[{"schema":{"type":"object","properties":{"in":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"description":"Match contacts whose id is in this set (single id or array)."},"not_in":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"description":"Exclude contacts whose id is in this set (single id or array)."},"ignore_merge":{"type":"boolean","description":"Filter by the `ignore_merge` flag (excluded from merge suggestions)."},"is_starred":{"type":"boolean","description":"Match starred (true) or non-starred (false) contacts."},"is_archived":{"type":"boolean","description":"Match archived (true) or active (false) contacts. Defaults to false when omitted."},"has_priority_tier":{"anyOf":[{"type":"integer","minimum":1,"maximum":9007199254740991},{"type":"array","items":{"type":"integer","minimum":1,"maximum":9007199254740991}},{"type":"boolean"}],"description":"Relationship priority tier: a tier number, an array of tiers (OR), or a boolean (true = any tier set, false = none)."},"has_linkedin":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"LinkedIn slug: an exact slug string, or a boolean for presence/absence of a LinkedIn handle."},"has_instagram":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"Instagram slug: an exact slug string, or a boolean for presence/absence of an Instagram handle."},"has_twitter":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"Twitter/X slug: an exact slug string, or a boolean for presence/absence of a Twitter handle."},"has_source":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Contact source: a single source string or an array of sources (OR)."},"has_name":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Full name: a bare string (fuzzy contains), an array of exact names, or `{ contains }` / `{ eq }` for explicit fuzzy vs exact match."},"has_groups":{"anyOf":[{"type":"object","properties":{"not":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},"required":["not"],"additionalProperties":false},{"type":"boolean"},{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"array","items":{"type":"string"}}],"description":"Group membership: a group id, an array of group ids (OR), a boolean for any/no group, or `{ not }` to exclude group id(s)."},"has_user_created_groups":{"type":"boolean","description":"Non-system group membership: true for at least one user-created group; false for no user-created groups, including contacts with zero memberships or only Dex system-group memberships."},"has_grouping_signal":{"type":"boolean","description":"Internal organize prefilter: title, company, location, or LinkedIn summary is non-null and non-empty. Whitespace-only values are removed by the organize serializer.","enum":[true]},"has_groups_all":{"description":"Array of group-id rows: AND across rows, OR within each row (contact must be in at least one group from every row).","type":"array","items":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"has_frequency":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"Keep-in-touch cadence: a frequency string, or a boolean for presence/absence of a cadence."},"has_location":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"Location: a string (fuzzy, accent-insensitive match), or a boolean for presence/absence of a location."},"has_location_exact":{"type":"string","description":"Location: exact string match (not fuzzy)."},"has_job_title":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Job title: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }` for explicit fuzzy vs exact match."},"has_never_keep_in_touch":{"type":"boolean","description":"Filter by the `never_keep_in_touch` flag."},"has_created_at":{"description":"Creation-date range: `{ gte?, lte? }` ISO 8601 datetimes (at least one bound required).","type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false},"has_updated_at":{"description":"Last-updated-date range: `{ gte?, lte? }` ISO 8601 datetimes (at least one bound required).","type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false},"has_birthday":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{},{"type":"boolean"}],"description":"Birthday: a specific date (matches on day + month), or true for any birthday set."},"has_tag":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Match contacts carrying this single tag id."},"has_tags":{"anyOf":[{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"type":"object","properties":{"not":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}]}},"required":["not"],"additionalProperties":false}],"description":"Tags: an array of tag ids (OR), or `{ not }` to exclude tag id(s)."},"has_tags_all":{"description":"Array of tag-id rows: AND across rows, OR within each row (contact must carry at least one tag from every row).","type":"array","items":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"has_company":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Company: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }` for explicit fuzzy vs exact match."},"has_education":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Education: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }`."},"has_description":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Description/notes: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }`."},"has_linkedin_companies":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"LinkedIn companies text: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }`."},"has_linkedin_education":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"LinkedIn education text: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }`."},"has_email":{"type":"boolean","description":"Match contacts that have (true) or lack (false) at least one email."},"has_phone_number":{"type":"boolean","description":"Match contacts that have (true) or lack (false) at least one phone number."},"not_has_name":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose full name fuzzily matches this string / any of these strings."},"not_has_company":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose company fuzzily matches this string / any of these strings."},"not_has_job_title":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose job title fuzzily matches this string / any of these strings."},"not_has_education":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose education fuzzily matches this string / any of these strings."},"not_has_description":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose description fuzzily matches this string / any of these strings."},"not_has_linkedin_companies":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose LinkedIn companies text fuzzily matches this string / any of these strings."},"not_has_linkedin_education":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose LinkedIn education text fuzzily matches this string / any of these strings."},"has_linkedin_last_message_at":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false}],"description":"LinkedIn last-message time: a boolean for presence/absence, or a `{ gte?, lte? }` ISO 8601 range."},"has_last_seen_at":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false}],"description":"Last-seen (last interaction) time — alias for has_interaction: a boolean for presence/absence, or a `{ gte?, lte? }` ISO 8601 range."},"has_distance":{"type":"object","properties":{"lat":{"type":"number"},"lon":{"type":"number"},"meters":{"type":"number"},"label":{"type":"string"}},"required":["lat","lon","meters"],"additionalProperties":false,"description":"Geo radius filter: contacts within `meters` of `{ lat, lon }` (PostGIS ST_DWithin on geocoded coordinates). `label` is an optional display name for the point."},"has_interaction":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false}],"description":"Interaction (last-seen) time: a boolean for presence/absence, or a `{ gte?, lte? }` ISO 8601 range."},"has_next_reminder":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false}],"description":"Next-reminder time: a boolean for presence/absence, or a `{ gte?, lte? }` ISO 8601 range."},"custom_fields":{"minItems":1,"type":"array","items":{"type":"object","properties":{"field_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"operator":{"type":"string","enum":["contains","eq","in","not_in","present","absent","gte","lte"]},"value":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},"required":["field_id","operator"],"additionalProperties":false},"description":"User-defined custom-field filters. Each clause is `{ field_id, operator, value? }`; multiple clauses AND together. Operators: contains, eq, in, not_in, present, absent, gte, lte."},"_or":{"description":"Compound-OR escape hatch: an array of filter branches combined with OR, each ANDed with the top-level keys. One level deep — branches cannot themselves contain `_or`.","minItems":1,"type":"array","items":{"type":"object","properties":{"in":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"description":"Match contacts whose id is in this set (single id or array)."},"not_in":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"description":"Exclude contacts whose id is in this set (single id or array)."},"ignore_merge":{"type":"boolean","description":"Filter by the `ignore_merge` flag (excluded from merge suggestions)."},"is_starred":{"type":"boolean","description":"Match starred (true) or non-starred (false) contacts."},"is_archived":{"type":"boolean","description":"Match archived (true) or active (false) contacts. Defaults to false when omitted."},"has_priority_tier":{"anyOf":[{"type":"integer","minimum":1,"maximum":9007199254740991},{"type":"array","items":{"type":"integer","minimum":1,"maximum":9007199254740991}},{"type":"boolean"}],"description":"Relationship priority tier: a tier number, an array of tiers (OR), or a boolean (true = any tier set, false = none)."},"has_linkedin":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"LinkedIn slug: an exact slug string, or a boolean for presence/absence of a LinkedIn handle."},"has_instagram":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"Instagram slug: an exact slug string, or a boolean for presence/absence of an Instagram handle."},"has_twitter":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"Twitter/X slug: an exact slug string, or a boolean for presence/absence of a Twitter handle."},"has_source":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Contact source: a single source string or an array of sources (OR)."},"has_name":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Full name: a bare string (fuzzy contains), an array of exact names, or `{ contains }` / `{ eq }` for explicit fuzzy vs exact match."},"has_groups":{"anyOf":[{"type":"object","properties":{"not":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},"required":["not"],"additionalProperties":false},{"type":"boolean"},{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"array","items":{"type":"string"}}],"description":"Group membership: a group id, an array of group ids (OR), a boolean for any/no group, or `{ not }` to exclude group id(s)."},"has_user_created_groups":{"type":"boolean","description":"Non-system group membership: true for at least one user-created group; false for no user-created groups, including contacts with zero memberships or only Dex system-group memberships."},"has_grouping_signal":{"type":"boolean","description":"Internal organize prefilter: title, company, location, or LinkedIn summary is non-null and non-empty. Whitespace-only values are removed by the organize serializer.","enum":[true]},"has_groups_all":{"description":"Array of group-id rows: AND across rows, OR within each row (contact must be in at least one group from every row).","type":"array","items":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"has_frequency":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"Keep-in-touch cadence: a frequency string, or a boolean for presence/absence of a cadence."},"has_location":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"Location: a string (fuzzy, accent-insensitive match), or a boolean for presence/absence of a location."},"has_location_exact":{"type":"string","description":"Location: exact string match (not fuzzy)."},"has_job_title":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Job title: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }` for explicit fuzzy vs exact match."},"has_never_keep_in_touch":{"type":"boolean","description":"Filter by the `never_keep_in_touch` flag."},"has_created_at":{"description":"Creation-date range: `{ gte?, lte? }` ISO 8601 datetimes (at least one bound required).","type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false},"has_updated_at":{"description":"Last-updated-date range: `{ gte?, lte? }` ISO 8601 datetimes (at least one bound required).","type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false},"has_birthday":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{},{"type":"boolean"}],"description":"Birthday: a specific date (matches on day + month), or true for any birthday set."},"has_tag":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Match contacts carrying this single tag id."},"has_tags":{"anyOf":[{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"type":"object","properties":{"not":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}]}},"required":["not"],"additionalProperties":false}],"description":"Tags: an array of tag ids (OR), or `{ not }` to exclude tag id(s)."},"has_tags_all":{"description":"Array of tag-id rows: AND across rows, OR within each row (contact must carry at least one tag from every row).","type":"array","items":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"has_company":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Company: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }` for explicit fuzzy vs exact match."},"has_education":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Education: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }`."},"has_description":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Description/notes: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }`."},"has_linkedin_companies":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"LinkedIn companies text: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }`."},"has_linkedin_education":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"LinkedIn education text: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }`."},"has_email":{"type":"boolean","description":"Match contacts that have (true) or lack (false) at least one email."},"has_phone_number":{"type":"boolean","description":"Match contacts that have (true) or lack (false) at least one phone number."},"not_has_name":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose full name fuzzily matches this string / any of these strings."},"not_has_company":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose company fuzzily matches this string / any of these strings."},"not_has_job_title":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose job title fuzzily matches this string / any of these strings."},"not_has_education":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose education fuzzily matches this string / any of these strings."},"not_has_description":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose description fuzzily matches this string / any of these strings."},"not_has_linkedin_companies":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose LinkedIn companies text fuzzily matches this string / any of these strings."},"not_has_linkedin_education":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose LinkedIn education text fuzzily matches this string / any of these strings."},"has_linkedin_last_message_at":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false}],"description":"LinkedIn last-message time: a boolean for presence/absence, or a `{ gte?, lte? }` ISO 8601 range."},"has_last_seen_at":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false}],"description":"Last-seen (last interaction) time — alias for has_interaction: a boolean for presence/absence, or a `{ gte?, lte? }` ISO 8601 range."},"has_distance":{"type":"object","properties":{"lat":{"type":"number"},"lon":{"type":"number"},"meters":{"type":"number"},"label":{"type":"string"}},"required":["lat","lon","meters"],"additionalProperties":false,"description":"Geo radius filter: contacts within `meters` of `{ lat, lon }` (PostGIS ST_DWithin on geocoded coordinates). `label` is an optional display name for the point."},"has_interaction":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false}],"description":"Interaction (last-seen) time: a boolean for presence/absence, or a `{ gte?, lte? }` ISO 8601 range."},"has_next_reminder":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false}],"description":"Next-reminder time: a boolean for presence/absence, or a `{ gte?, lte? }` ISO 8601 range."},"custom_fields":{"minItems":1,"type":"array","items":{"type":"object","properties":{"field_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"operator":{"type":"string","enum":["contains","eq","in","not_in","present","absent","gte","lte"]},"value":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},"required":["field_id","operator"],"additionalProperties":false},"description":"User-defined custom-field filters. Each clause is `{ field_id, operator, value? }`; multiple clauses AND together. Operators: contains, eq, in, not_in, present, absent, gte, lte."}},"additionalProperties":false}}},"additionalProperties":false},"in":"query","name":"where","required":false}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"data":{"type":"object","properties":{"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["count"],"additionalProperties":false}},"required":["error","data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"countContactsV1","summary":"Count contacts","description":"Return the total number of contacts for the authenticated user. Useful for displaying counts in dashboards without fetching full contact records.","x-mint":{"content":"## Use cases\n\n- Display a contact count on a dashboard or summary view\n- Check usage metrics before performing bulk operations\n- Monitor contact database growth over time"}}},"/v1/contacts/filter":{"post":{"tags":["contacts"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":9007199254740991},"in":"query","name":"take","required":false},{"schema":{"type":"integer","minimum":0,"maximum":9007199254740991},"in":"query","name":"skip","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"cursor","required":false},{"schema":{"type":"object","properties":{"in":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"description":"Match contacts whose id is in this set (single id or array)."},"not_in":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"description":"Exclude contacts whose id is in this set (single id or array)."},"ignore_merge":{"type":"boolean","description":"Filter by the `ignore_merge` flag (excluded from merge suggestions)."},"is_starred":{"type":"boolean","description":"Match starred (true) or non-starred (false) contacts."},"is_archived":{"type":"boolean","description":"Match archived (true) or active (false) contacts. Defaults to false when omitted."},"has_priority_tier":{"anyOf":[{"type":"integer","minimum":1,"maximum":9007199254740991},{"type":"array","items":{"type":"integer","minimum":1,"maximum":9007199254740991}},{"type":"boolean"}],"description":"Relationship priority tier: a tier number, an array of tiers (OR), or a boolean (true = any tier set, false = none)."},"has_linkedin":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"LinkedIn slug: an exact slug string, or a boolean for presence/absence of a LinkedIn handle."},"has_instagram":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"Instagram slug: an exact slug string, or a boolean for presence/absence of an Instagram handle."},"has_twitter":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"Twitter/X slug: an exact slug string, or a boolean for presence/absence of a Twitter handle."},"has_source":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Contact source: a single source string or an array of sources (OR)."},"has_name":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Full name: a bare string (fuzzy contains), an array of exact names, or `{ contains }` / `{ eq }` for explicit fuzzy vs exact match."},"has_groups":{"anyOf":[{"type":"object","properties":{"not":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},"required":["not"],"additionalProperties":false},{"type":"boolean"},{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"array","items":{"type":"string"}}],"description":"Group membership: a group id, an array of group ids (OR), a boolean for any/no group, or `{ not }` to exclude group id(s)."},"has_user_created_groups":{"type":"boolean","description":"Non-system group membership: true for at least one user-created group; false for no user-created groups, including contacts with zero memberships or only Dex system-group memberships."},"has_grouping_signal":{"type":"boolean","description":"Internal organize prefilter: title, company, location, or LinkedIn summary is non-null and non-empty. Whitespace-only values are removed by the organize serializer.","enum":[true]},"has_groups_all":{"description":"Array of group-id rows: AND across rows, OR within each row (contact must be in at least one group from every row).","type":"array","items":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"has_frequency":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"Keep-in-touch cadence: a frequency string, or a boolean for presence/absence of a cadence."},"has_location":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"Location: a string (fuzzy, accent-insensitive match), or a boolean for presence/absence of a location."},"has_location_exact":{"type":"string","description":"Location: exact string match (not fuzzy)."},"has_job_title":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Job title: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }` for explicit fuzzy vs exact match."},"has_never_keep_in_touch":{"type":"boolean","description":"Filter by the `never_keep_in_touch` flag."},"has_created_at":{"description":"Creation-date range: `{ gte?, lte? }` ISO 8601 datetimes (at least one bound required).","type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false},"has_updated_at":{"description":"Last-updated-date range: `{ gte?, lte? }` ISO 8601 datetimes (at least one bound required).","type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false},"has_birthday":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{},{"type":"boolean"}],"description":"Birthday: a specific date (matches on day + month), or true for any birthday set."},"has_tag":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Match contacts carrying this single tag id."},"has_tags":{"anyOf":[{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"type":"object","properties":{"not":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}]}},"required":["not"],"additionalProperties":false}],"description":"Tags: an array of tag ids (OR), or `{ not }` to exclude tag id(s)."},"has_tags_all":{"description":"Array of tag-id rows: AND across rows, OR within each row (contact must carry at least one tag from every row).","type":"array","items":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"has_company":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Company: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }` for explicit fuzzy vs exact match."},"has_education":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Education: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }`."},"has_description":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Description/notes: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }`."},"has_linkedin_companies":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"LinkedIn companies text: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }`."},"has_linkedin_education":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"LinkedIn education text: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }`."},"has_email":{"type":"boolean","description":"Match contacts that have (true) or lack (false) at least one email."},"has_phone_number":{"type":"boolean","description":"Match contacts that have (true) or lack (false) at least one phone number."},"not_has_name":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose full name fuzzily matches this string / any of these strings."},"not_has_company":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose company fuzzily matches this string / any of these strings."},"not_has_job_title":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose job title fuzzily matches this string / any of these strings."},"not_has_education":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose education fuzzily matches this string / any of these strings."},"not_has_description":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose description fuzzily matches this string / any of these strings."},"not_has_linkedin_companies":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose LinkedIn companies text fuzzily matches this string / any of these strings."},"not_has_linkedin_education":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose LinkedIn education text fuzzily matches this string / any of these strings."},"has_linkedin_last_message_at":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false}],"description":"LinkedIn last-message time: a boolean for presence/absence, or a `{ gte?, lte? }` ISO 8601 range."},"has_last_seen_at":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false}],"description":"Last-seen (last interaction) time — alias for has_interaction: a boolean for presence/absence, or a `{ gte?, lte? }` ISO 8601 range."},"has_distance":{"type":"object","properties":{"lat":{"type":"number"},"lon":{"type":"number"},"meters":{"type":"number"},"label":{"type":"string"}},"required":["lat","lon","meters"],"additionalProperties":false,"description":"Geo radius filter: contacts within `meters` of `{ lat, lon }` (PostGIS ST_DWithin on geocoded coordinates). `label` is an optional display name for the point."},"has_interaction":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false}],"description":"Interaction (last-seen) time: a boolean for presence/absence, or a `{ gte?, lte? }` ISO 8601 range."},"has_next_reminder":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false}],"description":"Next-reminder time: a boolean for presence/absence, or a `{ gte?, lte? }` ISO 8601 range."},"custom_fields":{"minItems":1,"type":"array","items":{"type":"object","properties":{"field_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"operator":{"type":"string","enum":["contains","eq","in","not_in","present","absent","gte","lte"]},"value":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},"required":["field_id","operator"],"additionalProperties":false},"description":"User-defined custom-field filters. Each clause is `{ field_id, operator, value? }`; multiple clauses AND together. Operators: contains, eq, in, not_in, present, absent, gte, lte."},"_or":{"description":"Compound-OR escape hatch: an array of filter branches combined with OR, each ANDed with the top-level keys. One level deep — branches cannot themselves contain `_or`.","minItems":1,"type":"array","items":{"type":"object","properties":{"in":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"description":"Match contacts whose id is in this set (single id or array)."},"not_in":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"description":"Exclude contacts whose id is in this set (single id or array)."},"ignore_merge":{"type":"boolean","description":"Filter by the `ignore_merge` flag (excluded from merge suggestions)."},"is_starred":{"type":"boolean","description":"Match starred (true) or non-starred (false) contacts."},"is_archived":{"type":"boolean","description":"Match archived (true) or active (false) contacts. Defaults to false when omitted."},"has_priority_tier":{"anyOf":[{"type":"integer","minimum":1,"maximum":9007199254740991},{"type":"array","items":{"type":"integer","minimum":1,"maximum":9007199254740991}},{"type":"boolean"}],"description":"Relationship priority tier: a tier number, an array of tiers (OR), or a boolean (true = any tier set, false = none)."},"has_linkedin":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"LinkedIn slug: an exact slug string, or a boolean for presence/absence of a LinkedIn handle."},"has_instagram":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"Instagram slug: an exact slug string, or a boolean for presence/absence of an Instagram handle."},"has_twitter":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"Twitter/X slug: an exact slug string, or a boolean for presence/absence of a Twitter handle."},"has_source":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Contact source: a single source string or an array of sources (OR)."},"has_name":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Full name: a bare string (fuzzy contains), an array of exact names, or `{ contains }` / `{ eq }` for explicit fuzzy vs exact match."},"has_groups":{"anyOf":[{"type":"object","properties":{"not":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},"required":["not"],"additionalProperties":false},{"type":"boolean"},{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"array","items":{"type":"string"}}],"description":"Group membership: a group id, an array of group ids (OR), a boolean for any/no group, or `{ not }` to exclude group id(s)."},"has_user_created_groups":{"type":"boolean","description":"Non-system group membership: true for at least one user-created group; false for no user-created groups, including contacts with zero memberships or only Dex system-group memberships."},"has_grouping_signal":{"type":"boolean","description":"Internal organize prefilter: title, company, location, or LinkedIn summary is non-null and non-empty. Whitespace-only values are removed by the organize serializer.","enum":[true]},"has_groups_all":{"description":"Array of group-id rows: AND across rows, OR within each row (contact must be in at least one group from every row).","type":"array","items":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"has_frequency":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"Keep-in-touch cadence: a frequency string, or a boolean for presence/absence of a cadence."},"has_location":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"Location: a string (fuzzy, accent-insensitive match), or a boolean for presence/absence of a location."},"has_location_exact":{"type":"string","description":"Location: exact string match (not fuzzy)."},"has_job_title":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Job title: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }` for explicit fuzzy vs exact match."},"has_never_keep_in_touch":{"type":"boolean","description":"Filter by the `never_keep_in_touch` flag."},"has_created_at":{"description":"Creation-date range: `{ gte?, lte? }` ISO 8601 datetimes (at least one bound required).","type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false},"has_updated_at":{"description":"Last-updated-date range: `{ gte?, lte? }` ISO 8601 datetimes (at least one bound required).","type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false},"has_birthday":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{},{"type":"boolean"}],"description":"Birthday: a specific date (matches on day + month), or true for any birthday set."},"has_tag":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Match contacts carrying this single tag id."},"has_tags":{"anyOf":[{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"type":"object","properties":{"not":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}]}},"required":["not"],"additionalProperties":false}],"description":"Tags: an array of tag ids (OR), or `{ not }` to exclude tag id(s)."},"has_tags_all":{"description":"Array of tag-id rows: AND across rows, OR within each row (contact must carry at least one tag from every row).","type":"array","items":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"has_company":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Company: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }` for explicit fuzzy vs exact match."},"has_education":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Education: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }`."},"has_description":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Description/notes: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }`."},"has_linkedin_companies":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"LinkedIn companies text: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }`."},"has_linkedin_education":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"LinkedIn education text: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }`."},"has_email":{"type":"boolean","description":"Match contacts that have (true) or lack (false) at least one email."},"has_phone_number":{"type":"boolean","description":"Match contacts that have (true) or lack (false) at least one phone number."},"not_has_name":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose full name fuzzily matches this string / any of these strings."},"not_has_company":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose company fuzzily matches this string / any of these strings."},"not_has_job_title":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose job title fuzzily matches this string / any of these strings."},"not_has_education":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose education fuzzily matches this string / any of these strings."},"not_has_description":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose description fuzzily matches this string / any of these strings."},"not_has_linkedin_companies":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose LinkedIn companies text fuzzily matches this string / any of these strings."},"not_has_linkedin_education":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose LinkedIn education text fuzzily matches this string / any of these strings."},"has_linkedin_last_message_at":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false}],"description":"LinkedIn last-message time: a boolean for presence/absence, or a `{ gte?, lte? }` ISO 8601 range."},"has_last_seen_at":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false}],"description":"Last-seen (last interaction) time — alias for has_interaction: a boolean for presence/absence, or a `{ gte?, lte? }` ISO 8601 range."},"has_distance":{"type":"object","properties":{"lat":{"type":"number"},"lon":{"type":"number"},"meters":{"type":"number"},"label":{"type":"string"}},"required":["lat","lon","meters"],"additionalProperties":false,"description":"Geo radius filter: contacts within `meters` of `{ lat, lon }` (PostGIS ST_DWithin on geocoded coordinates). `label` is an optional display name for the point."},"has_interaction":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false}],"description":"Interaction (last-seen) time: a boolean for presence/absence, or a `{ gte?, lte? }` ISO 8601 range."},"has_next_reminder":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false}],"description":"Next-reminder time: a boolean for presence/absence, or a `{ gte?, lte? }` ISO 8601 range."},"custom_fields":{"minItems":1,"type":"array","items":{"type":"object","properties":{"field_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"operator":{"type":"string","enum":["contains","eq","in","not_in","present","absent","gte","lte"]},"value":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},"required":["field_id","operator"],"additionalProperties":false},"description":"User-defined custom-field filters. Each clause is `{ field_id, operator, value? }`; multiple clauses AND together. Operators: contains, eq, in, not_in, present, absent, gte, lte."}},"additionalProperties":false}}},"additionalProperties":false},"in":"query","name":"where","required":false},{"schema":{},"in":"query","name":"orderBy","required":false},{"schema":{"type":"object","properties":{"linkedin_data":{"type":"boolean"},"groups_count":{"type":"boolean"},"coordinates":{"type":"boolean"}},"additionalProperties":{"type":"boolean"}},"in":"query","name":"include","required":false},{"schema":{"type":"object","properties":{"linkedin_data":{"type":"boolean"},"groups_count":{"type":"boolean"},"coordinates":{"type":"boolean"}},"additionalProperties":{"type":"boolean"}},"in":"query","name":"select","required":false}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"first_name":{"nullable":true,"type":"string"},"last_name":{"nullable":true,"type":"string"},"full_name":{"nullable":true,"type":"string"},"description":{"nullable":true,"type":"string"},"job_title":{"nullable":true,"type":"string"},"company":{"nullable":true,"type":"string"},"education":{"nullable":true,"type":"string"},"legacy_location":{"nullable":true,"type":"string"},"image_url":{"nullable":true,"type":"string"},"business_card_url":{"nullable":true,"type":"string"},"website":{"nullable":true,"type":"string"},"image_source":{"nullable":true,"type":"string"},"birthday":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"birthday_year":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"linkedin":{"nullable":true,"type":"string"},"twitter":{"nullable":true,"type":"string"},"facebook":{"nullable":true,"type":"string"},"instagram":{"nullable":true,"type":"string"},"telegram":{"nullable":true,"type":"string"},"tiktok":{"nullable":true,"type":"string"},"youtube":{"nullable":true,"type":"string"},"starred":{"type":"boolean"},"is_archived":{"type":"boolean"},"ignore_merge":{"type":"boolean"},"never_keep_in_touch":{"type":"boolean"},"source":{"type":"string"},"priority_tier":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"frequency":{"nullable":true,"type":"string"},"frequency_text":{"nullable":true,"type":"string"},"last_seen_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"last_reminder_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"next_reminder_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"first_met_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"first_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_companies":{"nullable":true,"type":"string"},"linkedin_education":{"nullable":true,"type":"string"},"linkedin_enhance_date":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_last_message_snippet":{"nullable":true,"type":"string"},"linkedin_message_link":{"nullable":true,"type":"string"},"whatsapp_message_link":{"nullable":true,"type":"string"},"whatsapp_message_snippet":{"nullable":true,"type":"string"},"whatsapp_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"imessage_message_link":{"nullable":true,"type":"string"},"imessage_message_snippet":{"nullable":true,"type":"string"},"imessage_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"instagram_message_link":{"nullable":true,"type":"string"},"instagram_message_snippet":{"nullable":true,"type":"string"},"instagram_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"gmail_last_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"gmail_last_interaction_provider":{"nullable":true,"type":"string","enum":["GOOGLE","OFFICE365"]},"gmail_last_interaction_provider_id":{"nullable":true,"type":"string"},"gmail_last_interaction_subject":{"nullable":true,"type":"string"},"gcal_last_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"gcal_last_interaction_provider":{"nullable":true,"type":"string","enum":["GOOGLE","OFFICE365"]},"gcal_last_interaction_provider_id":{"nullable":true,"type":"string"},"gcal_last_interaction_title":{"nullable":true,"type":"string"},"phone_call_interaction_snippet":{"nullable":true,"type":"string"},"phone_call_last_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"web_search_summary":{"nullable":true},"created_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"updated_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"geocode_attempts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"geocode_failed_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"_count":{"type":"object","properties":{"groups_contacts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["groups_contacts"],"additionalProperties":false},"frequency_interval":{},"linkedin_data":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"latitude":{"nullable":true,"type":"number"},"longitude":{"nullable":true,"type":"number"},"contact_emails":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_phone_numbers":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_birthdays":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"contact_locations":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contacts_custom_fields":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"legacy_contact_addresses":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"groups_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"tags_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"timeline_items_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"reminders_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_relations_contact_relations_sourceTocontacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_relations_contact_relations_destinationTocontacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"feed_items":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"keep_in_touch_reminders":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}}},"required":["id"],"additionalProperties":false}},"nextCursor":{"nullable":true,"type":"string"},"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["items","count"],"additionalProperties":{}}},"required":["error","data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"filterContactsV1","summary":"Filter contacts","description":"Retrieve contacts matching advanced filter criteria. Accepts filter conditions in the request body, supporting the same pagination as the list endpoint.","x-mint":{"content":"## Use cases\n\n- Build a dynamic contact list with user-defined filters\n- Find contacts matching specific criteria (e.g., by company, location, or tags)\n- Power saved views or segments in your application\n\nThis endpoint uses POST because filter criteria can be complex and may exceed URL length limits. The response format is identical to the List contacts endpoint."}}},"/v1/contacts/search":{"get":{"tags":["contacts"],"parameters":[{"schema":{"type":"string","minLength":1},"in":"query","name":"fullName","required":true},{"schema":{"type":"integer","minimum":1,"maximum":9007199254740991},"in":"query","name":"take","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"cursor","required":false}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"data":{"type":"object","properties":{"contacts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"first_name":{"nullable":true,"type":"string"},"last_name":{"nullable":true,"type":"string"},"full_name":{"nullable":true,"type":"string"},"description":{"nullable":true,"type":"string"},"job_title":{"nullable":true,"type":"string"},"company":{"nullable":true,"type":"string"},"education":{"nullable":true,"type":"string"},"legacy_location":{"nullable":true,"type":"string"},"image_url":{"nullable":true,"type":"string"},"business_card_url":{"nullable":true,"type":"string"},"website":{"nullable":true,"type":"string"},"image_source":{"nullable":true,"type":"string"},"birthday":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"birthday_year":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"linkedin":{"nullable":true,"type":"string"},"twitter":{"nullable":true,"type":"string"},"facebook":{"nullable":true,"type":"string"},"instagram":{"nullable":true,"type":"string"},"telegram":{"nullable":true,"type":"string"},"tiktok":{"nullable":true,"type":"string"},"youtube":{"nullable":true,"type":"string"},"starred":{"type":"boolean"},"is_archived":{"type":"boolean"},"ignore_merge":{"type":"boolean"},"never_keep_in_touch":{"type":"boolean"},"source":{"type":"string"},"priority_tier":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"frequency":{"nullable":true,"type":"string"},"frequency_text":{"nullable":true,"type":"string"},"last_seen_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"last_reminder_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"next_reminder_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"first_met_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"first_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_companies":{"nullable":true,"type":"string"},"linkedin_education":{"nullable":true,"type":"string"},"linkedin_enhance_date":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_last_message_snippet":{"nullable":true,"type":"string"},"linkedin_message_link":{"nullable":true,"type":"string"},"whatsapp_message_link":{"nullable":true,"type":"string"},"whatsapp_message_snippet":{"nullable":true,"type":"string"},"whatsapp_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"imessage_message_link":{"nullable":true,"type":"string"},"imessage_message_snippet":{"nullable":true,"type":"string"},"imessage_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"instagram_message_link":{"nullable":true,"type":"string"},"instagram_message_snippet":{"nullable":true,"type":"string"},"instagram_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"gmail_last_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"gmail_last_interaction_provider":{"nullable":true,"type":"string","enum":["GOOGLE","OFFICE365"]},"gmail_last_interaction_provider_id":{"nullable":true,"type":"string"},"gmail_last_interaction_subject":{"nullable":true,"type":"string"},"gcal_last_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"gcal_last_interaction_provider":{"nullable":true,"type":"string","enum":["GOOGLE","OFFICE365"]},"gcal_last_interaction_provider_id":{"nullable":true,"type":"string"},"gcal_last_interaction_title":{"nullable":true,"type":"string"},"phone_call_interaction_snippet":{"nullable":true,"type":"string"},"phone_call_last_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"web_search_summary":{"nullable":true},"created_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"updated_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"geocode_attempts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"geocode_failed_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"_count":{"type":"object","properties":{"groups_contacts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["groups_contacts"],"additionalProperties":false},"frequency_interval":{},"linkedin_data":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"latitude":{"nullable":true,"type":"number"},"longitude":{"nullable":true,"type":"number"},"contact_emails":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_phone_numbers":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_birthdays":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"contact_locations":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contacts_custom_fields":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"legacy_contact_addresses":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"groups_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"tags_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"timeline_items_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"reminders_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_relations_contact_relations_sourceTocontacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_relations_contact_relations_destinationTocontacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"feed_items":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"keep_in_touch_reminders":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}}},"required":["id"],"additionalProperties":false}}},"required":["contacts"],"additionalProperties":false}},"required":["error","data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"searchContactsTypeaheadV1","summary":"Search contacts","description":"Search contacts by name, email, company, or other text fields. Returns contacts matching the search query, ranked by relevance.","x-mint":{"content":"## Use cases\n\n- Power a real-time search bar in your contact list\n- Find contacts by partial name or email match\n- Look up contacts by company name\n\nThis performs a basic text search across common contact fields. For more advanced filtering with structured criteria, use the Filter contacts endpoint instead."}}},"/v1/contacts/merge":{"post":{"tags":["contacts"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contactIds":{"minItems":1,"type":"array","items":{"minItems":2,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}}},"required":["contactIds"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"data":{"type":"object","properties":{"mergedContactIds":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"required":["mergedContactIds"],"additionalProperties":false}},"required":["error","data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"mergeContactsV1","summary":"Merge contacts","description":"Merge two or more duplicate contacts into a single contact record. The primary contact is kept and enriched with data from the secondary contacts, which are then deleted.","x-mint":{"content":"## Use cases\n\n- Deduplicate contacts that were imported from multiple sources\n- Combine a manually-created contact with one synced from email\n- Clean up after a bulk import that created duplicates\n\nThe secondary contacts will be permanently deleted after the merge. Their notes, tags, and group memberships are transferred to the primary contact."}}},"/v1/custom-fields/":{"get":{"tags":["custom-fields"],"parameters":[{"schema":{"type":"object","propertyNames":{},"additionalProperties":{"type":"boolean"}},"in":"query","name":"select","required":false}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"data":{"type":"object","properties":{"custom_fields":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"name":{"type":"string"},"field_type":{"type":"string"},"categories":{"type":"array","items":{"type":"string"}},"ranking":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id"],"additionalProperties":false}}},"required":["custom_fields"],"additionalProperties":false}},"required":["error","data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"listCustomFieldsV1","summary":"List custom fields","description":"Retrieve all custom field definitions for the authenticated user. Custom fields allow you to add structured data to contacts beyond the built-in fields.","x-mint":{"content":"## Use cases\n\n- Display available custom fields on a contact form\n- Sync custom field definitions to an external system\n- List all custom fields on a settings or configuration page"}},"post":{"tags":["custom-fields"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"custom_field":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"field_type":{"type":"string","enum":["input","autocomplete","datepicker"]},"categories":{"type":"array","items":{"type":"object","properties":{"category":{"type":"string","minLength":1,"maxLength":100}},"required":["category"],"additionalProperties":false}}},"required":["name","field_type"],"additionalProperties":false}},"required":["custom_field"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"data":{"type":"object","properties":{"custom_field":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"name":{"type":"string"},"field_type":{"type":"string"},"categories":{"type":"array","items":{"type":"string"}},"ranking":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id"],"additionalProperties":false}},"required":["custom_field"],"additionalProperties":false}},"required":["error","data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"createCustomFieldV1","summary":"Create a custom field","description":"Create a new custom field definition. Once created, the field can be set on any contact to store additional structured data.","x-mint":{"content":"## Use cases\n\n- Add a new field type for tracking custom data (e.g., \"LinkedIn URL\", \"Birthday\", \"Lead Source\")\n- Set up custom fields during onboarding or data import\n- Extend the contact schema to match your specific workflow"}}},"/v1/custom-fields/reorder":{"put":{"tags":["custom-fields"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"updates":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"object","properties":{"customFieldId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"ranking":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["customFieldId","ranking"],"additionalProperties":false}}},"required":["updates"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"data":{"type":"object","properties":{"custom_fields":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"name":{"type":"string"},"field_type":{"type":"string"},"categories":{"type":"array","items":{"type":"string"}},"ranking":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id"],"additionalProperties":false}}},"required":["custom_fields"],"additionalProperties":false}},"required":["error","data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"reorderCustomFieldsV1","summary":"Reorder custom fields","description":"Update the display order of custom fields by providing new ranking values. The order is reflected everywhere custom fields are displayed.","x-mint":{"content":"## Use cases\n\n- Let users drag-and-drop custom fields to set their preferred display order\n- Ensure custom fields appear in a consistent order across web, mobile, and API responses\n- Persist field ordering preferences across sessions\n\nPass an array of `{ customFieldId, ranking }` objects. All custom fields should be included to avoid gaps in the ordering."}}},"/v1/custom-fields/{customFieldId}":{"put":{"tags":["custom-fields"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"custom_field":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"field_type":{"type":"string","enum":["input","autocomplete","datepicker"]},"categories":{"type":"array","items":{"type":"object","properties":{"category":{"type":"string","minLength":1,"maxLength":100}},"required":["category"],"additionalProperties":false}}},"additionalProperties":false}},"required":["custom_field"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"customFieldId","required":true}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"data":{"type":"object","properties":{"custom_field":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"name":{"type":"string"},"field_type":{"type":"string"},"categories":{"type":"array","items":{"type":"string"}},"ranking":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id"],"additionalProperties":false}},"required":["custom_field"],"additionalProperties":false}},"required":["error","data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"updateCustomFieldV1","summary":"Update a custom field","description":"Update a custom field definition by its ID. You can modify the field name or other properties.","x-mint":{"content":"## Use cases\n\n- Rename a custom field to better reflect its purpose\n- Update field configuration or validation rules\n- Correct a typo in a custom field name"}},"delete":{"tags":["custom-fields"],"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"customFieldId","required":true}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"message":{"type":"string"}},"required":["error","message"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"deleteCustomFieldV1","summary":"Delete a custom field","description":"Permanently delete a custom field definition and remove its values from all contacts.","x-mint":{"content":"## Use cases\n\n- Remove a custom field that is no longer needed\n- Clean up unused fields from the contact schema\n- Delete a field as part of a data model reorganization\n\nDeleting a custom field permanently removes its values from all contacts. This action cannot be undone."}}},"/v1/custom-fields/batch-update-contacts":{"post":{"tags":["custom-fields"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"custom_fields":{"minItems":1,"type":"array","items":{"type":"object","properties":{"contact_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"custom_field_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"text_value":{"type":"string"},"date_value":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"array_value":{"type":"array","items":{"type":"string"}}},"required":["contact_id","custom_field_id"],"additionalProperties":false}}},"required":["custom_fields"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"data":{"type":"object","properties":{"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["count"],"additionalProperties":false}},"required":["error","data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"batchUpdateContactCustomFieldsV1","summary":"Batch update custom field values","description":"Set or update custom field values for multiple contacts in a single request. Useful for bulk-populating custom fields across your contact database.","x-mint":{"content":"## Use cases\n\n- Bulk-set a custom field value across many contacts (e.g., set \"Lead Source\" for all imported contacts)\n- Populate custom fields during a data migration\n- Update custom field values in batch after syncing data from an external system"}}},"/v1/groups/":{"get":{"tags":["groups"],"parameters":[{"schema":{"type":"object","properties":{"name":{},"number_of_contacts":{}},"additionalProperties":false},"in":"query","name":"orderBy","required":false},{"schema":{"type":"object","properties":{"has_subgroups":{"type":"boolean"},"has_parent":{"type":"boolean"},"has_name":{"type":"string","minLength":1,"maxLength":100},"not_in":{"type":"array","items":{"type":"string"}}},"additionalProperties":false},"in":"query","name":"where","required":false},{"schema":{"type":"object","properties":{"parent_group":{"type":"boolean"},"sub_groups":{"type":"boolean"},"sub_groups_name_order":{},"contacts_count":{"type":"boolean"},"sub_groups_count":{"type":"boolean"},"is_favorite":{"type":"boolean"}},"additionalProperties":false},"in":"query","name":"include","required":false},{"schema":{"type":"object","properties":{"parent_group":{"type":"boolean"},"sub_groups":{"type":"boolean"},"sub_groups_name_order":{},"contacts_count":{"type":"boolean"},"sub_groups_count":{"type":"boolean"},"is_favorite":{"type":"boolean"}},"additionalProperties":{"type":"boolean"}},"in":"query","name":"select","required":false},{"schema":{"type":"integer","minimum":1,"maximum":9007199254740991},"in":"query","name":"take","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"cursor","required":false}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"data":{"type":"object","properties":{"groups":{"type":"array","items":{"$ref":"#/definitions/__schema0"}}},"required":["groups"],"additionalProperties":false}},"required":["error","data"],"additionalProperties":false,"definitions":{"__schema0":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"name":{"type":"string"},"emoji":{"type":"string"},"description":{"nullable":true,"type":"string"},"parent_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"ranking":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"created_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"is_favorite":{"type":"boolean"},"sub_groups":{"type":"array","items":{"$ref":"#/definitions/__schema0"}},"parent_groups":{"nullable":true,"allOf":[{"$ref":"#/definitions/__schema0"}]},"_count":{"type":"object","properties":{"groups_contacts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"sub_groups":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["groups_contacts"],"additionalProperties":false}},"required":["id"],"additionalProperties":false}}}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"listGroupsV1","summary":"List groups","description":"Retrieve all groups for the authenticated user. Groups are collections of contacts used to organize your network (e.g., \"Coworkers\", \"College Friends\").","x-mint":{"content":"## Use cases\n\n- Display a sidebar or navigation menu of contact groups\n- Sync group structure to an external system\n- List all groups to let users pick which group to add a contact to"}},"post":{"tags":["groups"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"group":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"emoji":{"type":"string"},"description":{"type":"string"},"parent_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]},"parent":{},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"groups_contacts":{"type":"array","items":{"type":"object","properties":{"contact_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"contact":{}},"required":["contact_id"],"additionalProperties":false}}},"required":["name"],"additionalProperties":false}},"required":["group"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"data":{"type":"object","properties":{"group":{"$ref":"#/definitions/__schema0"}},"required":["group"],"additionalProperties":false}},"required":["error","data"],"additionalProperties":false,"definitions":{"__schema0":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"name":{"type":"string"},"emoji":{"type":"string"},"description":{"nullable":true,"type":"string"},"parent_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"ranking":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"created_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"is_favorite":{"type":"boolean"},"sub_groups":{"type":"array","items":{"$ref":"#/definitions/__schema0"}},"parent_groups":{"nullable":true,"allOf":[{"$ref":"#/definitions/__schema0"}]},"_count":{"type":"object","properties":{"groups_contacts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"sub_groups":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["groups_contacts"],"additionalProperties":false}},"required":["id"],"additionalProperties":false}}}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"createGroupV1","summary":"Create a group","description":"Create a new group for organizing contacts. Provide a name and optional metadata for the group.","x-mint":{"content":"## Use cases\n\n- Let users create custom groups to organize their contacts\n- Programmatically create groups when importing data from another CRM\n- Set up default groups for new users during onboarding"}}},"/v1/groups/count":{"get":{"tags":["groups"],"parameters":[{"schema":{"type":"object","properties":{"has_subgroups":{"type":"boolean"},"has_parent":{"type":"boolean"},"has_name":{"type":"string","minLength":1,"maxLength":100},"not_in":{"type":"array","items":{"type":"string"}}},"additionalProperties":false},"in":"query","name":"where","required":false}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"data":{"type":"object","properties":{"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["count"],"additionalProperties":false}},"required":["error","data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"countGroupsV1","summary":"Count groups","description":"Return the total number of groups for the authenticated user.","x-mint":{"content":"## Use cases\n\n- Display a group count on a dashboard\n- Check how many groups a user has for plan limit enforcement\n- Monitor group usage over time"}}},"/v1/groups/{groupId}":{"get":{"tags":["groups"],"parameters":[{"schema":{"type":"object","properties":{"parent_group":{"type":"boolean"},"sub_groups":{"type":"boolean"},"sub_groups_name_order":{},"contacts_count":{"type":"boolean"},"sub_groups_count":{"type":"boolean"},"is_favorite":{"type":"boolean"}},"additionalProperties":false},"in":"query","name":"include","required":false},{"schema":{"type":"object","properties":{"parent_group":{"type":"boolean"},"sub_groups":{"type":"boolean"},"sub_groups_name_order":{},"contacts_count":{"type":"boolean"},"sub_groups_count":{"type":"boolean"},"is_favorite":{"type":"boolean"}},"additionalProperties":{"type":"boolean"}},"in":"query","name":"select","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"groupId","required":true}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"data":{"type":"object","properties":{"group":{"$ref":"#/definitions/__schema0"}},"required":["group"],"additionalProperties":false}},"required":["error","data"],"additionalProperties":false,"definitions":{"__schema0":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"name":{"type":"string"},"emoji":{"type":"string"},"description":{"nullable":true,"type":"string"},"parent_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"ranking":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"created_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"is_favorite":{"type":"boolean"},"sub_groups":{"type":"array","items":{"$ref":"#/definitions/__schema0"}},"parent_groups":{"nullable":true,"allOf":[{"$ref":"#/definitions/__schema0"}]},"_count":{"type":"object","properties":{"groups_contacts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"sub_groups":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["groups_contacts"],"additionalProperties":false}},"required":["id"],"additionalProperties":false}}}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getGroupV1","summary":"Get a group","description":"Retrieve a single group by its unique ID, including its name and metadata.","x-mint":{"content":"## Use cases\n\n- Display group details on a group page\n- Fetch group metadata before editing it\n- Verify a group exists before adding contacts to it"}},"put":{"tags":["groups"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"group":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"emoji":{"type":"string"},"description":{"type":"string"},"parent_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]},"parent":{}},"additionalProperties":false}},"required":["group"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"groupId","required":true}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"data":{"type":"object","properties":{"group":{"$ref":"#/definitions/__schema0"}},"required":["group"],"additionalProperties":false}},"required":["error","data"],"additionalProperties":false,"definitions":{"__schema0":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"name":{"type":"string"},"emoji":{"type":"string"},"description":{"nullable":true,"type":"string"},"parent_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"ranking":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"created_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"is_favorite":{"type":"boolean"},"sub_groups":{"type":"array","items":{"$ref":"#/definitions/__schema0"}},"parent_groups":{"nullable":true,"allOf":[{"$ref":"#/definitions/__schema0"}]},"_count":{"type":"object","properties":{"groups_contacts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"sub_groups":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["groups_contacts"],"additionalProperties":false}},"required":["id"],"additionalProperties":false}}}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"updateGroupV1","summary":"Update a group","description":"Update a group's name or other properties by its ID. Only the fields included in the request body are modified.","x-mint":{"content":"## Use cases\n\n- Rename a group\n- Update group metadata or settings\n- Modify group properties as part of a bulk reorganization"}},"delete":{"tags":["groups"],"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"groupId","required":true}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"message":{"type":"string"}},"required":["error","message"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"deleteGroupV1","summary":"Delete a group","description":"Permanently delete a group by its ID. The contacts in the group are not deleted — only their association with this group is removed.","x-mint":{"content":"## Use cases\n\n- Remove a group that is no longer needed\n- Clean up empty or unused groups\n- Delete a group as part of a reorganization\n\nDeleting a group does not delete the contacts in it. The contacts remain in your account and can still be found in other groups or the main contact list."}}},"/v1/groups/contact-counts":{"get":{"tags":["groups"],"parameters":[{"schema":{"type":"string"},"in":"query","name":"groupIds","required":false}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"data":{"type":"object","properties":{"counts":{"type":"object","additionalProperties":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}}},"required":["counts"],"additionalProperties":false}},"required":["error","data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getGroupContactCountsV1","summary":"Get contact counts per group","description":"Retrieve the number of contacts in each group. Returns a map of group IDs to their respective contact counts.","x-mint":{"content":"## Use cases\n\n- Display contact counts next to group names in a sidebar\n- Identify empty or low-membership groups for cleanup\n- Build analytics on group sizes"}}},"/v1/groups/{groupId}/contacts":{"get":{"tags":["groups"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":9007199254740991},"in":"query","name":"take","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"cursor","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"groupId","required":true}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"first_name":{"nullable":true,"type":"string"},"last_name":{"nullable":true,"type":"string"},"full_name":{"nullable":true,"type":"string"},"description":{"nullable":true,"type":"string"},"job_title":{"nullable":true,"type":"string"},"company":{"nullable":true,"type":"string"},"education":{"nullable":true,"type":"string"},"legacy_location":{"nullable":true,"type":"string"},"image_url":{"nullable":true,"type":"string"},"business_card_url":{"nullable":true,"type":"string"},"website":{"nullable":true,"type":"string"},"image_source":{"nullable":true,"type":"string"},"birthday":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"birthday_year":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"linkedin":{"nullable":true,"type":"string"},"twitter":{"nullable":true,"type":"string"},"facebook":{"nullable":true,"type":"string"},"instagram":{"nullable":true,"type":"string"},"telegram":{"nullable":true,"type":"string"},"tiktok":{"nullable":true,"type":"string"},"youtube":{"nullable":true,"type":"string"},"starred":{"type":"boolean"},"is_archived":{"type":"boolean"},"ignore_merge":{"type":"boolean"},"never_keep_in_touch":{"type":"boolean"},"source":{"type":"string"},"priority_tier":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"frequency":{"nullable":true,"type":"string"},"frequency_text":{"nullable":true,"type":"string"},"last_seen_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"last_reminder_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"next_reminder_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"first_met_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"first_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_companies":{"nullable":true,"type":"string"},"linkedin_education":{"nullable":true,"type":"string"},"linkedin_enhance_date":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_last_message_snippet":{"nullable":true,"type":"string"},"linkedin_message_link":{"nullable":true,"type":"string"},"whatsapp_message_link":{"nullable":true,"type":"string"},"whatsapp_message_snippet":{"nullable":true,"type":"string"},"whatsapp_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"imessage_message_link":{"nullable":true,"type":"string"},"imessage_message_snippet":{"nullable":true,"type":"string"},"imessage_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"instagram_message_link":{"nullable":true,"type":"string"},"instagram_message_snippet":{"nullable":true,"type":"string"},"instagram_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"gmail_last_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"gmail_last_interaction_provider":{"nullable":true,"type":"string","enum":["GOOGLE","OFFICE365"]},"gmail_last_interaction_provider_id":{"nullable":true,"type":"string"},"gmail_last_interaction_subject":{"nullable":true,"type":"string"},"gcal_last_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"gcal_last_interaction_provider":{"nullable":true,"type":"string","enum":["GOOGLE","OFFICE365"]},"gcal_last_interaction_provider_id":{"nullable":true,"type":"string"},"gcal_last_interaction_title":{"nullable":true,"type":"string"},"phone_call_interaction_snippet":{"nullable":true,"type":"string"},"phone_call_last_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"web_search_summary":{"nullable":true},"created_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"updated_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"geocode_attempts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"geocode_failed_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"_count":{"type":"object","properties":{"groups_contacts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["groups_contacts"],"additionalProperties":false},"frequency_interval":{},"linkedin_data":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"latitude":{"nullable":true,"type":"number"},"longitude":{"nullable":true,"type":"number"},"contact_emails":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_phone_numbers":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_birthdays":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"contact_locations":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contacts_custom_fields":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"legacy_contact_addresses":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"groups_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"tags_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"timeline_items_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"reminders_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_relations_contact_relations_sourceTocontacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_relations_contact_relations_destinationTocontacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"feed_items":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"keep_in_touch_reminders":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}}},"required":["id"],"additionalProperties":false}},"nextCursor":{"nullable":true,"type":"string"},"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["items","count"],"additionalProperties":false}},"required":["error","data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"listGroupContactsV1","summary":"List contacts in a group","description":"Retrieve all contacts that belong to a specific group. Supports pagination for groups with many contacts.","x-mint":{"content":"## Use cases\n\n- Display the contact list for a selected group\n- Export contacts from a specific group\n- Sync group membership to an external system"}},"put":{"tags":["groups"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contactIds":{"minItems":1,"maxItems":500,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"required":["contactIds"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"groupId","required":true}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"data":{"type":"object","properties":{"result":{"type":"object","properties":{"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["count"],"additionalProperties":false}},"required":["result"],"additionalProperties":false}},"required":["error","data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"addContactsToGroupV1","summary":"Add contacts to a group","description":"Add one or more contacts to a group by providing an array of contact IDs. Contacts that are already in the group are ignored.","x-mint":{"content":"## Use cases\n\n- Let users drag-and-drop contacts into a group\n- Bulk-add contacts to a group after filtering or searching\n- Automatically organize imported contacts into groups\n\nIf a contact is already a member of the group, it will be silently skipped — no error is returned."}},"post":{"tags":["groups"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contactIds":{"minItems":1,"maxItems":500,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"required":["contactIds"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"groupId","required":true}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"message":{"type":"string"}},"required":["error","message"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"removeContactsFromGroupV1","summary":"Remove contacts from a group","description":"Remove one or more contacts from a group. The contacts themselves are not deleted — only their group membership is removed.","x-mint":{"content":"## Use cases\n\n- Let users remove contacts from a group via the UI\n- Clean up group membership after a reorganization\n- Unassign contacts that no longer belong to a group\n\nRemoving a contact from a group does not delete the contact. It only removes the association between the contact and this group."}}},"/v1/reminders/{reminderId}":{"get":{"tags":["reminders"],"parameters":[{"schema":{"type":"object","properties":{"recurrence":{"type":"boolean"},"contacts":{"type":"boolean"}},"additionalProperties":{"type":"boolean"}},"in":"query","name":"include","required":false},{"schema":{"type":"object","properties":{"recurrence":{"type":"boolean"},"contacts":{"type":"boolean"}},"additionalProperties":{"type":"boolean"}},"in":"query","name":"select","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"reminderId","required":true}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"text":{"nullable":true,"type":"string"},"due_at_date":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"due_at_time":{"nullable":true,"anyOf":[{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},{"type":"string"}]},"is_complete":{"type":"boolean"},"email_sent":{"type":"boolean"},"push_notification_sent":{"type":"boolean"},"recurrence":{"nullable":true,"type":"string"},"last_completed_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"next_occurrence_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"created_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"is_overdue":{"type":"boolean"},"next_cursor":{"type":"string"},"reminders_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"users":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}}},"required":["id"],"additionalProperties":false}},"required":["error","data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getReminderV1","summary":"Get a reminder","description":"Retrieve a single reminder by its unique ID, including its title, due date, associated contact, and recurrence settings.","x-mint":{"content":"## Use cases\n\n- Display reminder details on a detail or edit page\n- Fetch the latest reminder state before updating it\n- Verify a reminder exists before performing operations on it"}},"put":{"tags":["reminders"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reminder":{"type":"object","properties":{"text":{"anyOf":[{"type":"string"},{"type":"null"}]},"due_at_date":{},"due_at_time":{"anyOf":[{},{"type":"null"}]},"is_complete":{"type":"boolean"},"recurrence":{"anyOf":[{"type":"string"},{"type":"null"}]},"reminders_contacts":{"type":"array","items":{"type":"object","properties":{"contact_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"contacts":{}},"required":["contact_id"],"additionalProperties":false}},"last_completed_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}]},"next_occurrence_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}]},"email_sent":{"type":"boolean"},"push_notification_sent":{"type":"boolean"}},"additionalProperties":false}},"required":["reminder"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"reminderId","required":true}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"data":{"type":"object","properties":{"reminder":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"text":{"nullable":true,"type":"string"},"due_at_date":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"due_at_time":{"nullable":true,"anyOf":[{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},{"type":"string"}]},"is_complete":{"type":"boolean"},"email_sent":{"type":"boolean"},"push_notification_sent":{"type":"boolean"},"recurrence":{"nullable":true,"type":"string"},"last_completed_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"next_occurrence_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"created_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"is_overdue":{"type":"boolean"},"next_cursor":{"type":"string"},"reminders_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"users":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}}},"required":["id"],"additionalProperties":false}},"required":["reminder"],"additionalProperties":false}},"required":["error","data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"updateReminderV1","summary":"Update a reminder","description":"Update a reminder by its ID. You can modify the title, due date, associated contact, recurrence, or completion status.","x-mint":{"content":"## Use cases\n\n- Reschedule a reminder to a different date\n- Mark a reminder as completed\n- Change the recurrence frequency of a keep-in-touch reminder\n- Reassign a reminder to a different contact"}},"delete":{"tags":["reminders"],"parameters":[{"schema":{"type":"string"},"in":"path","name":"reminderId","required":true}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"message":{"type":"string"}},"required":["error","message"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"deleteReminderV1","summary":"Delete a reminder","description":"Permanently delete a reminder by its ID. For recurring reminders, this stops all future occurrences.","x-mint":{"content":"## Use cases\n\n- Remove a reminder that is no longer relevant\n- Cancel a recurring keep-in-touch cadence\n- Clean up completed or outdated reminders\n\nDeleting a recurring reminder cancels all future occurrences. This action cannot be undone."}}},"/v1/reminders/":{"get":{"tags":["reminders"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":9007199254740991},"in":"query","name":"take","required":false},{"schema":{"type":"integer","minimum":0,"maximum":9007199254740991},"in":"query","name":"skip","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"cursor","required":false},{"schema":{"type":"object","properties":{"in":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"not_in":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"is_complete":{"type":"boolean"},"is_overdue":{"type":"boolean"},"has_contacts":{"anyOf":[{"type":"object","properties":{"not":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}]}},"required":["not"],"additionalProperties":false},{"type":"boolean"},{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}]},"has_due_at_date":{"type":"object","properties":{"gte":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"lte":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}},"additionalProperties":false},"has_created_at":{"type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false}},"additionalProperties":false},"in":"query","name":"where","required":false},{"schema":{},"in":"query","name":"orderBy","required":false},{"schema":{"type":"object","properties":{"recurrence":{"type":"boolean"},"contacts":{"type":"boolean"}},"additionalProperties":{"type":"boolean"}},"in":"query","name":"include","required":false},{"schema":{"type":"object","properties":{"recurrence":{"type":"boolean"},"contacts":{"type":"boolean"}},"additionalProperties":{"type":"boolean"}},"in":"query","name":"select","required":false}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"text":{"nullable":true,"type":"string"},"due_at_date":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"due_at_time":{"nullable":true,"anyOf":[{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},{"type":"string"}]},"is_complete":{"type":"boolean"},"email_sent":{"type":"boolean"},"push_notification_sent":{"type":"boolean"},"recurrence":{"nullable":true,"type":"string"},"last_completed_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"next_occurrence_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"created_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"is_overdue":{"type":"boolean"},"next_cursor":{"type":"string"},"reminders_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"users":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}}},"required":["id"],"additionalProperties":false}},"nextCursor":{"nullable":true,"type":"string"}},"required":["items"],"additionalProperties":false}},"required":["error","data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"listRemindersV1","summary":"List reminders","description":"Retrieve all reminders for the authenticated user. Supports filtering by contact, date range, and completion status.","x-mint":{"content":"## Use cases\n\n- Display a list of upcoming reminders in a dashboard\n- Show all reminders associated with a specific contact\n- Sync reminders to an external calendar or task management system"}},"post":{"tags":["reminders"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reminder":{"type":"object","properties":{"text":{"anyOf":[{"type":"string"},{"type":"null"}]},"due_at_date":{},"due_at_time":{"anyOf":[{},{"type":"null"}]},"is_complete":{"type":"boolean"},"recurrence":{"anyOf":[{"type":"string"},{"type":"null"}]},"reminders_contacts":{"type":"array","items":{"type":"object","properties":{"contact_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"contacts":{}},"required":["contact_id"],"additionalProperties":false}},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["due_at_date"],"additionalProperties":false}},"required":["reminder"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"data":{"type":"object","properties":{"reminder":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"text":{"nullable":true,"type":"string"},"due_at_date":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"due_at_time":{"nullable":true,"anyOf":[{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},{"type":"string"}]},"is_complete":{"type":"boolean"},"email_sent":{"type":"boolean"},"push_notification_sent":{"type":"boolean"},"recurrence":{"nullable":true,"type":"string"},"last_completed_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"next_occurrence_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"created_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"is_overdue":{"type":"boolean"},"next_cursor":{"type":"string"},"reminders_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"users":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}}},"required":["id"],"additionalProperties":false}},"required":["reminder"],"additionalProperties":false}},"required":["error","data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"createReminderV1","summary":"Create a reminder","description":"Create a new reminder for the authenticated user. A reminder can be linked to a contact and optionally set to recur on a schedule.","x-mint":{"content":"## Use cases\n\n- Set a follow-up reminder after a meeting or call\n- Create a keep-in-touch cadence for an important contact\n- Schedule a reminder to reach out before a birthday or event\n\nTo create a recurring reminder, include the recurrence fields in the request. One-time reminders only need a due date."}}},"/v1/reminders/recurring":{"get":{"tags":["reminders"],"parameters":[{"schema":{"type":"object","properties":{"recurrence":{"type":"boolean"},"contacts":{"type":"boolean"}},"additionalProperties":{"type":"boolean"}},"in":"query","name":"include","required":false}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"text":{"nullable":true,"type":"string"},"due_at_date":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"due_at_time":{"nullable":true,"anyOf":[{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},{"type":"string"}]},"is_complete":{"type":"boolean"},"email_sent":{"type":"boolean"},"push_notification_sent":{"type":"boolean"},"recurrence":{"nullable":true,"type":"string"},"last_completed_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"next_occurrence_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"created_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"is_overdue":{"type":"boolean"},"next_cursor":{"type":"string"},"reminders_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"users":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}}},"required":["id"],"additionalProperties":false}}},"required":["items"],"additionalProperties":false}},"required":["error","data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"listRecurringRemindersV1","summary":"List recurring reminders","description":"Retrieve all recurring (keep-in-touch) reminders for the authenticated user. These are repeating reminders set to maintain contact with specific people.","x-mint":{"content":"## Use cases\n\n- Display a keep-in-touch dashboard showing recurring outreach commitments\n- Review and manage all recurring reminder schedules\n- Identify contacts with active keep-in-touch cadences"}}},"/v1/search/contacts":{"get":{"tags":["search"],"parameters":[{"schema":{"type":"string"},"in":"query","name":"searchQuery","required":false},{"schema":{"type":"boolean"},"in":"query","name":"archived","required":false},{"schema":{"type":"boolean"},"in":"query","name":"minimal","required":false},{"schema":{"type":"boolean"},"in":"query","name":"exactMatch","required":false},{"schema":{"type":"boolean"},"in":"query","name":"enhanced","required":false},{"schema":{"type":"string"},"in":"query","name":"near","required":false},{"schema":{"type":"number","exclusiveMinimum":0},"in":"query","name":"radiusKm","required":false},{"schema":{"type":"integer","minimum":1,"maximum":9007199254740991},"in":"query","name":"take","required":false},{"schema":{"type":"boolean"},"in":"query","name":"fallbackNameToEmail","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false},{"schema":{"anyOf":[{"type":"object","properties":{"not":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}]}},"required":["not"],"additionalProperties":false},{"type":"boolean"},{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}]},"in":"query","name":"has_groups","required":false}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"first_name":{"nullable":true,"type":"string"},"last_name":{"nullable":true,"type":"string"},"full_name":{"nullable":true,"type":"string"},"description":{"nullable":true,"type":"string"},"job_title":{"nullable":true,"type":"string"},"company":{"nullable":true,"type":"string"},"education":{"nullable":true,"type":"string"},"legacy_location":{"nullable":true,"type":"string"},"image_url":{"nullable":true,"type":"string"},"business_card_url":{"nullable":true,"type":"string"},"website":{"nullable":true,"type":"string"},"image_source":{"nullable":true,"type":"string"},"birthday":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"birthday_year":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"linkedin":{"nullable":true,"type":"string"},"twitter":{"nullable":true,"type":"string"},"facebook":{"nullable":true,"type":"string"},"instagram":{"nullable":true,"type":"string"},"telegram":{"nullable":true,"type":"string"},"tiktok":{"nullable":true,"type":"string"},"youtube":{"nullable":true,"type":"string"},"starred":{"type":"boolean"},"is_archived":{"type":"boolean"},"ignore_merge":{"type":"boolean"},"never_keep_in_touch":{"type":"boolean"},"source":{"type":"string"},"priority_tier":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"frequency":{"nullable":true,"type":"string"},"frequency_text":{"nullable":true,"type":"string"},"last_seen_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"last_reminder_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"next_reminder_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"first_met_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"first_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_companies":{"nullable":true,"type":"string"},"linkedin_education":{"nullable":true,"type":"string"},"linkedin_enhance_date":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_last_message_snippet":{"nullable":true,"type":"string"},"linkedin_message_link":{"nullable":true,"type":"string"},"whatsapp_message_link":{"nullable":true,"type":"string"},"whatsapp_message_snippet":{"nullable":true,"type":"string"},"whatsapp_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"imessage_message_link":{"nullable":true,"type":"string"},"imessage_message_snippet":{"nullable":true,"type":"string"},"imessage_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"instagram_message_link":{"nullable":true,"type":"string"},"instagram_message_snippet":{"nullable":true,"type":"string"},"instagram_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"gmail_last_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"gmail_last_interaction_provider":{"nullable":true,"type":"string","enum":["GOOGLE","OFFICE365"]},"gmail_last_interaction_provider_id":{"nullable":true,"type":"string"},"gmail_last_interaction_subject":{"nullable":true,"type":"string"},"gcal_last_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"gcal_last_interaction_provider":{"nullable":true,"type":"string","enum":["GOOGLE","OFFICE365"]},"gcal_last_interaction_provider_id":{"nullable":true,"type":"string"},"gcal_last_interaction_title":{"nullable":true,"type":"string"},"phone_call_interaction_snippet":{"nullable":true,"type":"string"},"phone_call_last_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"web_search_summary":{"nullable":true},"created_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"updated_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"geocode_attempts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"geocode_failed_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"_count":{"type":"object","properties":{"groups_contacts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["groups_contacts"],"additionalProperties":false},"frequency_interval":{},"linkedin_data":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"latitude":{"nullable":true,"type":"number"},"longitude":{"nullable":true,"type":"number"},"contact_emails":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_phone_numbers":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_birthdays":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"contact_locations":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contacts_custom_fields":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"legacy_contact_addresses":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"groups_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"tags_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"timeline_items_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"reminders_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_relations_contact_relations_sourceTocontacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_relations_contact_relations_destinationTocontacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"feed_items":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"keep_in_touch_reminders":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}}},"required":["id"],"additionalProperties":false}}},"required":["error","data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"searchContactsV1","summary":"Search contacts (global)","description":"Full-text search across all contacts. Part of the global search API that searches across multiple entity types.","x-mint":{"content":"## Use cases\n\n- Power a global search bar that searches across contacts\n- Find contacts matching a keyword across all fields\n- Build a unified search experience alongside other entity types"}}},"/v1/search/timeline":{"get":{"tags":["search"],"parameters":[{"schema":{"type":"string"},"in":"query","name":"searchQuery","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"contactId","required":false},{"schema":{"type":"string"},"in":"query","name":"startDate","required":false},{"schema":{"type":"string"},"in":"query","name":"endDate","required":false},{"schema":{"type":"integer","minimum":1,"maximum":9007199254740991},"in":"query","name":"take","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false},{"schema":{"type":"boolean"},"in":"query","name":"includeContactDetails","required":false}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"note":{"nullable":true,"type":"string"},"custom_emoji":{"nullable":true,"type":"string"},"meeting_type":{"nullable":true,"type":"string"},"meeting_type_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"event_time":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"created_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"google_calendar_event_id_v3":{"nullable":true,"type":"string"},"oauth_credential_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"calendar_account_email":{"nullable":true,"type":"string"},"calendar_account_provider":{"nullable":true,"type":"string","enum":["GOOGLE","OFFICE365"]},"reminder_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"channels":{"type":"array","items":{"type":"string","enum":["whatsapp","imessage","linkedin","instagram"]}},"next_cursor":{"type":"string"},"meeting_types":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"timeline_items_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"attachments":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["id","channels","meeting_types"],"additionalProperties":false}},"nextCursor":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["items","nextCursor","count"],"additionalProperties":{}}},"required":["error","data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"searchNotesV1","summary":"Search notes","description":"Full-text search across all notes and timeline entries. Part of the global search API.","x-mint":{"content":"## Use cases\n\n- Search for notes containing specific keywords or topics\n- Find past interactions or meeting notes\n- Power a global search bar that includes note results"}}},"/v1/search/groups":{"get":{"tags":["search"],"parameters":[{"schema":{"type":"string"},"in":"query","name":"searchQuery","required":false},{"schema":{"type":"integer","minimum":1,"maximum":9007199254740991},"in":"query","name":"take","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"data":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/definitions/__schema0"}},"nextCursor":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["items","nextCursor","count"],"additionalProperties":{}}},"required":["error","data"],"additionalProperties":false,"definitions":{"__schema0":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"name":{"type":"string"},"emoji":{"type":"string"},"description":{"nullable":true,"type":"string"},"parent_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"ranking":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"created_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"is_favorite":{"type":"boolean"},"sub_groups":{"type":"array","items":{"$ref":"#/definitions/__schema0"}},"parent_groups":{"nullable":true,"allOf":[{"$ref":"#/definitions/__schema0"}]},"_count":{"type":"object","properties":{"groups_contacts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"sub_groups":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["groups_contacts"],"additionalProperties":false}},"required":["id"],"additionalProperties":false}}}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"searchGroupsV1","summary":"Search groups","description":"Search groups by name. Part of the global search API that searches across multiple entity types.","x-mint":{"content":"## Use cases\n\n- Power a global search bar that includes group results\n- Find groups matching a keyword\n- Build a search experience for quickly navigating to a group"}}},"/v1/search/tags":{"get":{"tags":["search"],"parameters":[{"schema":{"type":"string"},"in":"query","name":"searchQuery","required":false},{"schema":{"type":"integer","minimum":1,"maximum":9007199254740991},"in":"query","name":"take","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"name":{"type":"string"},"_count":{"type":"object","properties":{"tags_contacts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["tags_contacts"],"additionalProperties":false}},"required":["id"],"additionalProperties":false}}},"required":["error","data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"searchTagsV1","summary":"Search tags","description":"Search tags by name. Part of the global search API that searches across multiple entity types.","x-mint":{"content":"## Use cases\n\n- Power a global search bar that includes tag results\n- Find tags matching a keyword for quick navigation\n- Build a tag autocomplete with search functionality"}}},"/v1/search/views":{"get":{"tags":["search"],"parameters":[{"schema":{"type":"string"},"in":"query","name":"searchQuery","required":false},{"schema":{"type":"integer","minimum":1,"maximum":9007199254740991},"in":"query","name":"take","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"name":{"nullable":true,"type":"string"},"emoji":{"nullable":true,"type":"string"},"filters":{},"description":{"nullable":true,"type":"string"},"created_at":{"type":"string"},"updated_at":{"type":"string"},"ranking":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"additionalProperties":{}}}},"required":["error","data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"searchViewsV1","summary":"Search views","description":"Search saved views by name. Part of the global search API that searches across multiple entity types.","x-mint":{"content":"## Use cases\n\n- Power a global search bar that includes saved view results\n- Find views matching a keyword for quick navigation\n- Help users discover existing saved views"}}},"/v1/search/reminders":{"get":{"tags":["search"],"parameters":[{"schema":{"type":"string"},"in":"query","name":"searchQuery","required":false},{"schema":{"type":"string"},"in":"query","name":"startDate","required":false},{"schema":{"type":"string"},"in":"query","name":"endDate","required":false},{"schema":{"type":"boolean"},"in":"query","name":"isComplete","required":false},{"schema":{"type":"integer","minimum":1,"maximum":9007199254740991},"in":"query","name":"take","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"text":{"nullable":true,"type":"string"},"due_at_date":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"due_at_time":{"nullable":true,"anyOf":[{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},{"type":"string"}]},"is_complete":{"type":"boolean"},"email_sent":{"type":"boolean"},"push_notification_sent":{"type":"boolean"},"recurrence":{"nullable":true,"type":"string"},"last_completed_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"next_occurrence_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"created_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"is_overdue":{"type":"boolean"},"next_cursor":{"type":"string"},"reminders_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"users":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}}},"required":["id"],"additionalProperties":false}},"nextCursor":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["items","nextCursor","count"],"additionalProperties":{}}},"required":["error","data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"searchRemindersV1","summary":"Search reminders","description":"Search reminders by title or content. Part of the global search API that searches across multiple entity types.","x-mint":{"content":"## Use cases\n\n- Power a global search bar that includes reminder results\n- Find reminders matching a keyword\n- Help users quickly locate a specific reminder"}}},"/v1/tags/":{"get":{"tags":["tags"],"parameters":[{"schema":{"type":"object","properties":{"contacts_count":{"type":"boolean"}},"additionalProperties":false},"in":"query","name":"include","required":false},{"schema":{"type":"object","properties":{"contacts_count":{"type":"boolean"}},"additionalProperties":{"type":"boolean"}},"in":"query","name":"select","required":false},{"schema":{"type":"object","properties":{"name":{"type":"string","enum":["asc","desc"]},"contacts_count":{"type":"string","enum":["asc","desc"]}},"additionalProperties":false},"in":"query","name":"orderBy","required":false},{"schema":{"type":"integer","minimum":1,"maximum":9007199254740991},"in":"query","name":"take","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"cursor","required":false}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"name":{"type":"string"},"_count":{"type":"object","properties":{"tags_contacts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["tags_contacts"],"additionalProperties":false}},"required":["id"],"additionalProperties":false}},"nextCursor":{"nullable":true,"type":"string"}},"required":["items"],"additionalProperties":false}},"required":["error","data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"listTagsV1","summary":"List tags","description":"Retrieve all tags for the authenticated user. Tags are labels that can be attached to contacts for flexible categorization (e.g., \"VIP\", \"Investor\", \"Met at conference\").","x-mint":{"content":"## Use cases\n\n- Populate a tag picker or autocomplete dropdown\n- Sync tags to an external system\n- Display all available tags in a settings or management page"}},"post":{"tags":["tags"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tag":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":99}},"required":["name"],"additionalProperties":false}},"required":["tag"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"object","properties":{"contacts_count":{"type":"boolean"}},"additionalProperties":false},"in":"query","name":"include","required":false}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"data":{"type":"object","properties":{"tag":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"name":{"type":"string"},"_count":{"type":"object","properties":{"tags_contacts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["tags_contacts"],"additionalProperties":false}},"required":["id"],"additionalProperties":false}},"required":["tag"],"additionalProperties":false}},"required":["error","data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"createTagV1","summary":"Create a tag","description":"Create a new tag with a name and optional color. Tags can then be assigned to contacts for categorization.","x-mint":{"content":"## Use cases\n\n- Let users create custom tags from a tag management page\n- Programmatically create tags during a data import\n- Set up default tags for new users during onboarding"}}},"/v1/tags/count":{"get":{"tags":["tags"],"parameters":[{"schema":{"type":"object","properties":{"name":{"type":"string","enum":["asc","desc"]},"contacts_count":{"type":"string","enum":["asc","desc"]}},"additionalProperties":false},"in":"query","name":"orderBy","required":false}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"data":{"type":"object","properties":{"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["count"],"additionalProperties":false}},"required":["error","data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"countTagsV1","summary":"Count tags","description":"Return the total number of tags for the authenticated user.","x-mint":{"content":"## Use cases\n\n- Display a tag count on a dashboard or settings page\n- Monitor tag usage for plan limit enforcement\n- Track categorization coverage over time"}}},"/v1/tags/{tagId}":{"get":{"tags":["tags"],"parameters":[{"schema":{"type":"object","properties":{"contacts_count":{"type":"boolean"}},"additionalProperties":false},"in":"query","name":"include","required":false},{"schema":{"type":"object","properties":{"contacts_count":{"type":"boolean"}},"additionalProperties":{"type":"boolean"}},"in":"query","name":"select","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"tagId","required":true}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"data":{"type":"object","properties":{"tag":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"name":{"type":"string"},"_count":{"type":"object","properties":{"tags_contacts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["tags_contacts"],"additionalProperties":false}},"required":["id"],"additionalProperties":false}},"required":["tag"],"additionalProperties":false}},"required":["error","data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getTagV1","summary":"Get a tag","description":"Retrieve a single tag by its unique ID, including its name and color.","x-mint":{"content":"## Use cases\n\n- Display tag details on a tag management page\n- Fetch tag metadata before editing it\n- Resolve a tag ID to its name for display purposes"}},"put":{"tags":["tags"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tag":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":99}},"additionalProperties":false}},"required":["tag"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"tagId","required":true}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"data":{"type":"object","properties":{"tag":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"name":{"type":"string"},"_count":{"type":"object","properties":{"tags_contacts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["tags_contacts"],"additionalProperties":false}},"required":["id"],"additionalProperties":false}},"required":["tag"],"additionalProperties":false}},"required":["error","data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"updateTagV1","summary":"Update a tag","description":"Update a tag's name or color by its ID. Only the fields included in the request body are modified.","x-mint":{"content":"## Use cases\n\n- Rename a tag to better reflect its purpose\n- Change a tag's color for visual organization\n- Correct a typo in a tag name"}},"delete":{"tags":["tags"],"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"tagId","required":true}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"}},"required":["error"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"deleteTagV1","summary":"Delete a tag","description":"Permanently delete a tag by its ID. The tag is removed from all contacts it was assigned to.","x-mint":{"content":"## Use cases\n\n- Remove a tag that is no longer relevant\n- Clean up unused or duplicate tags\n- Delete a tag as part of a tag taxonomy reorganization\n\nDeleting a tag automatically removes it from all contacts. The contacts themselves are not affected."}}},"/v1/tags/contact-counts":{"get":{"tags":["tags"],"parameters":[{"schema":{"type":"string"},"in":"query","name":"tagIds","required":false}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"data":{"type":"object","properties":{"counts":{"type":"object","additionalProperties":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}}},"required":["counts"],"additionalProperties":false}},"required":["error","data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getTagContactCountsV1","summary":"Get contact counts per tag","description":"Retrieve the number of contacts associated with each tag. Returns a map of tag IDs to their respective contact counts.","x-mint":{"content":"## Use cases\n\n- Display contact counts next to tag names in a sidebar or list\n- Identify unused tags with zero contacts for cleanup\n- Build analytics on how contacts are categorized"}}},"/v1/tags/bulk-create":{"post":{"tags":["tags"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"minItems":1,"type":"array","items":{"type":"string","minLength":1,"maxLength":99}}}}},"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"data":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"name":{"type":"string"},"_count":{"type":"object","properties":{"tags_contacts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["tags_contacts"],"additionalProperties":false}},"required":["id"],"additionalProperties":false}},"failed":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["name","error"],"additionalProperties":false}}},"required":["tags"],"additionalProperties":false}},"required":["error","data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"bulkCreateTagsV1","summary":"Bulk create tags","description":"Create multiple tags in a single request. Useful for importing a set of tags or setting up tag structures programmatically.","x-mint":{"content":"## Use cases\n\n- Import tags from another CRM or system\n- Set up a predefined tag taxonomy for a new account\n- Create multiple tags at once during onboarding\n\nTags with duplicate names will return an error. Ensure all tag names in the request are unique."}}},"/v1/tags/batch-delete":{"post":{"tags":["tags"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tagIds":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"deleteAll":{"type":"boolean"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"data":{"type":"object","properties":{"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"tag_ids":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"required":["count","tag_ids"],"additionalProperties":false}},"required":["error","data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"batchDeleteTagsV1","summary":"Batch delete tags","description":"Delete multiple tags in a single request by providing an array of tag IDs.","x-mint":{"content":"## Use cases\n\n- Bulk clean up unused or duplicate tags\n- Remove a set of tags as part of a reorganization\n- Delete imported tags that are no longer needed\n\nThis permanently deletes the specified tags and removes them from all associated contacts."}}},"/v1/tags/contacts/add":{"post":{"tags":["tags"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contactIds":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"tagIds":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"required":["contactIds","tagIds"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"message":{"type":"string"},"data":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"object","properties":{"user_id":{"type":"string"},"contact_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"tag_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["user_id","contact_id","tag_id"],"additionalProperties":false}}},"required":["tags"],"additionalProperties":false}},"required":["error","message","data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"addTagsToContactsV1","summary":"Add tags to contacts","description":"Assign one or more tags to one or more contacts. Accepts arrays of tag IDs and contact IDs to create the associations.","x-mint":{"content":"## Use cases\n\n- Tag contacts in bulk after filtering or searching\n- Apply a tag to multiple contacts selected in a list view\n- Automatically tag contacts during an import based on source data\n\nExisting tag-contact associations are silently skipped — no error is returned for duplicate assignments."}}},"/v1/tags/contacts/remove":{"post":{"tags":["tags"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contactIds":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"tagIds":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"required":["contactIds","tagIds"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"message":{"type":"string"},"data":{"type":"object","properties":{"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["count"],"additionalProperties":false}},"required":["error","message","data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"removeTagsFromContactsV1","summary":"Remove tags from contacts","description":"Remove one or more tag assignments from one or more contacts. The tags and contacts themselves are not deleted.","x-mint":{"content":"## Use cases\n\n- Remove a tag from multiple contacts after a reclassification\n- Clean up tag assignments in bulk\n- Untag contacts that no longer match a category\n\nThis only removes the association between tags and contacts. Neither the tags nor the contacts are deleted."}}},"/v1/tags/contacts/{contactId}/create-assign":{"post":{"tags":["tags"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tagNames":{"type":"array","items":{"type":"string","minLength":1,"maxLength":99}}},"required":["tagNames"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"contactId","required":true}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"message":{"type":"string"},"data":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"name":{"type":"string"},"_count":{"type":"object","properties":{"tags_contacts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["tags_contacts"],"additionalProperties":false}},"required":["id"],"additionalProperties":false}}},"required":["tags"],"additionalProperties":false}},"required":["error","message","data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"createAndAssignTagsV1","summary":"Create and assign tags to a contact","description":"Create new tags and immediately assign them to a specific contact in a single operation. Tags that already exist with the same name are reused.","x-mint":{"content":"## Use cases\n\n- Let users type new tags directly on a contact detail page\n- Quickly categorize a contact with new labels without a separate tag creation step\n- Import contacts with tags where the tags may not exist yet\n\nIf a tag with the same name already exists, it will be reused rather than creating a duplicate."}}},"/v1/timeline/":{"get":{"tags":["timeline"],"parameters":[{"schema":{},"in":"query","name":"orderBy","required":false},{"schema":{"type":"integer","minimum":1,"maximum":9007199254740991},"in":"query","name":"take","required":false},{"schema":{"type":"object","properties":{"timeline_items_contacts":{"type":"boolean"},"attachments":{"type":"boolean"}},"additionalProperties":false},"in":"query","name":"include","required":false},{"schema":{"type":"object","properties":{"timeline_items_contacts":{"type":"boolean"},"attachments":{"type":"boolean"}},"additionalProperties":{"type":"boolean"}},"in":"query","name":"select","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"cursor","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"contactId","required":false}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"note":{"nullable":true,"type":"string"},"custom_emoji":{"nullable":true,"type":"string"},"meeting_type":{"nullable":true,"type":"string"},"meeting_type_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"event_time":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"created_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"google_calendar_event_id_v3":{"nullable":true,"type":"string"},"oauth_credential_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"calendar_account_email":{"nullable":true,"type":"string"},"calendar_account_provider":{"nullable":true,"type":"string","enum":["GOOGLE","OFFICE365"]},"reminder_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"channels":{"type":"array","items":{"type":"string","enum":["whatsapp","imessage","linkedin","instagram"]}},"next_cursor":{"type":"string"},"meeting_types":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"timeline_items_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"attachments":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["id","channels","meeting_types"],"additionalProperties":false}},"nextCursor":{"nullable":true,"type":"string"},"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["items","count"],"additionalProperties":false}},"required":["error","data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"listNotesV1","summary":"List notes","description":"Retrieve notes for the authenticated user. Supports filtering by contact, note type, and date range, with cursor-based pagination.","x-mint":{"content":"## Use cases\n\n- Display a timeline of interactions for a specific contact\n- Show a global activity feed across all contacts\n- Export interaction history for reporting or backup\n\nResults are paginated. Use the `nextCursor` value from the response to fetch the next page."}},"post":{"tags":["timeline"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"object","properties":{"note":{"type":"string","maxLength":50000},"custom_emoji":{"type":"string"},"event_time":{},"meeting_type":{"anyOf":[{"type":"string","enum":["call","coffee","email","meal","meeting","networking","note","other","party","text"]},{"type":"null"}]},"meeting_type_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"meeting_types":{},"attachments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"url":{"type":"string","format":"uri"},"file_name":{"type":"string"},"file_size":{"type":"number"}},"required":["url","file_name"],"additionalProperties":false}},"timeline_items_contacts":{"type":"array","items":{"type":"object","properties":{"contact_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"contacts":{}},"required":["contact_id"],"additionalProperties":false}},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"google_calendar_event_id_v3":{"type":"string"},"oauth_credential_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"reminder_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["event_time"],"additionalProperties":false}},"required":["note"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"data":{"type":"object","properties":{"note":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"note":{"nullable":true,"type":"string"},"custom_emoji":{"nullable":true,"type":"string"},"meeting_type":{"nullable":true,"type":"string"},"meeting_type_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"event_time":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"created_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"google_calendar_event_id_v3":{"nullable":true,"type":"string"},"oauth_credential_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"calendar_account_email":{"nullable":true,"type":"string"},"calendar_account_provider":{"nullable":true,"type":"string","enum":["GOOGLE","OFFICE365"]},"reminder_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"channels":{"type":"array","items":{"type":"string","enum":["whatsapp","imessage","linkedin","instagram"]}},"next_cursor":{"type":"string"},"meeting_types":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"timeline_items_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"attachments":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["id","channels","meeting_types"],"additionalProperties":false}},"required":["note"],"additionalProperties":false}},"required":["error","data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"createNoteV1","summary":"Create a note","description":"Create a new note or timeline entry. A note can be associated with one or more contacts and includes a type (e.g., meeting, call, email) and rich text content.","x-mint":{"content":"## Use cases\n\n- Log a meeting note or call summary after an interaction\n- Record an email exchange or important conversation\n- Add a personal note or observation about a contact\n\nNotes support rich text content. Use the `note_type` field to categorize the interaction (e.g., \"meeting\", \"call\", \"email\")."}}},"/v1/timeline/count":{"get":{"tags":["timeline"],"parameters":[{"schema":{"type":"object","properties":{"has_contacts":{"anyOf":[{"type":"object","properties":{"not":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},"required":["not"],"additionalProperties":false},{"type":"boolean"},{"type":"string"},{"type":"array","items":{"type":"string"}}]},"created_at":{"type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"required":["gte","lte"],"additionalProperties":false},"has_calendar_event":{"anyOf":[{"type":"boolean"},{"type":"string"}]}},"additionalProperties":false},"in":"query","name":"where","required":false}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"data":{"type":"object","properties":{"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["count"],"additionalProperties":false}},"required":["error","data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"countNotesV1","summary":"Count notes","description":"Return the total number of notes matching the given filters. Useful for displaying counts without fetching full note records.","x-mint":{"content":"## Use cases\n\n- Display a note count on a contact profile or dashboard\n- Show interaction frequency metrics\n- Monitor note-taking activity over time"}}},"/v1/timeline/{noteId}":{"get":{"tags":["timeline"],"parameters":[{"schema":{"type":"object","properties":{"timeline_items_contacts":{"type":"boolean"},"attachments":{"type":"boolean"}},"additionalProperties":false},"in":"query","name":"include","required":false},{"schema":{"type":"object","properties":{"timeline_items_contacts":{"type":"boolean"},"attachments":{"type":"boolean"}},"additionalProperties":{"type":"boolean"}},"in":"query","name":"select","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"noteId","required":true}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"data":{"type":"object","properties":{"note":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"note":{"nullable":true,"type":"string"},"custom_emoji":{"nullable":true,"type":"string"},"meeting_type":{"nullable":true,"type":"string"},"meeting_type_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"event_time":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"created_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"google_calendar_event_id_v3":{"nullable":true,"type":"string"},"oauth_credential_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"calendar_account_email":{"nullable":true,"type":"string"},"calendar_account_provider":{"nullable":true,"type":"string","enum":["GOOGLE","OFFICE365"]},"reminder_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"channels":{"type":"array","items":{"type":"string","enum":["whatsapp","imessage","linkedin","instagram"]}},"next_cursor":{"type":"string"},"meeting_types":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"timeline_items_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"attachments":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["id","channels","meeting_types"],"additionalProperties":false}},"required":["note"],"additionalProperties":false}},"required":["error","data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getNoteV1","summary":"Get a note","description":"Retrieve a single note by its unique ID. Notes are timeline entries that record interactions, meeting notes, and other activities related to contacts.","x-mint":{"content":"## Use cases\n\n- Display a note detail or edit view\n- Fetch the latest note content before updating it\n- Retrieve a specific interaction record for display in your application"}},"put":{"tags":["timeline"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"object","properties":{"note":{"type":"string","maxLength":50000},"custom_emoji":{"type":"string"},"event_time":{},"meeting_type":{"anyOf":[{"type":"string","enum":["call","coffee","email","meal","meeting","networking","note","other","party","text"]},{"type":"null"}]},"meeting_type_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"meeting_types":{},"attachments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"url":{"type":"string","format":"uri"},"file_name":{"type":"string"},"file_size":{"type":"number"}},"required":["url","file_name"],"additionalProperties":false}},"timeline_items_contacts":{"type":"array","items":{"type":"object","properties":{"contact_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"contacts":{}},"required":["contact_id"],"additionalProperties":false}},"oauth_credential_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"reminder_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"additionalProperties":false}},"required":["note"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"noteId","required":true}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"data":{"type":"object","properties":{"note":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"note":{"nullable":true,"type":"string"},"custom_emoji":{"nullable":true,"type":"string"},"meeting_type":{"nullable":true,"type":"string"},"meeting_type_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"event_time":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"created_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"google_calendar_event_id_v3":{"nullable":true,"type":"string"},"oauth_credential_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"calendar_account_email":{"nullable":true,"type":"string"},"calendar_account_provider":{"nullable":true,"type":"string","enum":["GOOGLE","OFFICE365"]},"reminder_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"channels":{"type":"array","items":{"type":"string","enum":["whatsapp","imessage","linkedin","instagram"]}},"next_cursor":{"type":"string"},"meeting_types":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"timeline_items_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"attachments":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["id","channels","meeting_types"],"additionalProperties":false}},"required":["note"],"additionalProperties":false}},"required":["error","data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"updateNoteV1","summary":"Update a note","description":"Update a note by its ID. You can modify the content, associated contacts, note type, or date.","x-mint":{"content":"## Use cases\n\n- Edit a note to add details after an interaction\n- Change the associated contacts or note type\n- Fix a typo or update the date of a note"}},"delete":{"tags":["timeline"],"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"noteId","required":true}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"message":{"type":"string"}},"required":["error","message"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"deleteNoteV1","summary":"Delete a note","description":"Permanently delete a note by its ID. This removes the timeline entry from all associated contacts.","x-mint":{"content":"## Use cases\n\n- Remove a note that was created by mistake\n- Delete an outdated or irrelevant timeline entry\n- Clean up imported notes that are no longer needed\n\nThis action is permanent and cannot be undone."}}},"/v1/timeline/note-types":{"get":{"tags":["timeline"],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"name":{"type":"string"},"emoji":{"nullable":true,"type":"string"},"created_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]}},"required":["id","name","created_at"],"additionalProperties":false}}},"required":["error","data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"listNoteTypesV1","summary":"List note types","description":"Retrieve all available note types (e.g., meeting, call, email, note). Use these types when creating or filtering notes.","x-mint":{"content":"## Use cases\n\n- Populate a note type selector when creating a new note\n- Filter timeline entries by interaction type\n- Display note type labels in a timeline view"}}},"/v1/unified-timeline/":{"get":{"tags":["unified-timeline"],"parameters":[{"schema":{"type":"string"},"in":"query","name":"sources","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"contactId","required":false},{"schema":{"type":"integer","minimum":1,"maximum":500},"in":"query","name":"take","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false},{"schema":{"type":"string"},"in":"query","name":"startDate","required":false},{"schema":{"type":"string"},"in":"query","name":"endDate","required":false},{"schema":{"type":"boolean"},"in":"query","name":"upcoming","required":false},{"schema":{"type":"string"},"in":"query","name":"searchQuery","required":false},{"schema":{"type":"boolean"},"in":"query","name":"includeContactDetails","required":false}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"data":{"type":"object","properties":{"items":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["NOTE"]},"date":{"type":"string"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"note":{"nullable":true,"type":"string"},"custom_emoji":{"nullable":true,"type":"string"},"meeting_type":{"nullable":true,"type":"string"},"meeting_type_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"event_time":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"created_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"google_calendar_event_id_v3":{"nullable":true,"type":"string"},"oauth_credential_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"calendar_account_email":{"nullable":true,"type":"string"},"calendar_account_provider":{"nullable":true,"type":"string","enum":["GOOGLE","OFFICE365"]},"reminder_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"channels":{"type":"array","items":{"type":"string","enum":["whatsapp","imessage","linkedin","instagram"]}},"next_cursor":{"type":"string"},"meeting_types":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"timeline_items_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"attachments":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["id","channels","meeting_types"],"additionalProperties":false}},"required":["type","date","data"],"additionalProperties":{}},{"type":"object","properties":{"type":{"type":"string","enum":["REMINDER"]},"date":{"type":"string"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"text":{"nullable":true,"type":"string"},"due_at_date":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"due_at_time":{"nullable":true,"anyOf":[{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},{"type":"string"}]},"is_complete":{"type":"boolean"},"email_sent":{"type":"boolean"},"push_notification_sent":{"type":"boolean"},"recurrence":{"nullable":true,"type":"string"},"last_completed_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"next_occurrence_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"created_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"is_overdue":{"type":"boolean"},"next_cursor":{"type":"string"},"reminders_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"users":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}}},"required":["id"],"additionalProperties":false}},"required":["type","date","data"],"additionalProperties":{}},{"type":"object","properties":{"type":{"type":"string","enum":["EMAIL"]},"date":{"type":"string"},"data":{"type":"object","properties":{"providerId":{"type":"string"},"threadId":{"nullable":true,"type":"string"},"subjectOrTitle":{"type":"string"},"snippet":{"nullable":true,"type":"string"},"dateTime":{"type":"string"},"endDateTime":{"nullable":true,"type":"string"},"isAllDay":{"type":"boolean"},"participants":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string"},"name":{"nullable":true,"type":"string"}},"required":["email"],"additionalProperties":false}},"providerLink":{"nullable":true,"type":"string"},"email":{"type":"string"},"iCalUID":{"nullable":true,"type":"string"},"isRecurring":{"type":"boolean"},"provider":{"type":"string"}},"additionalProperties":{}}},"required":["type","date","data"],"additionalProperties":{}},{"type":"object","properties":{"type":{"type":"string","enum":["CALENDAR"]},"date":{"type":"string"},"data":{"type":"object","properties":{"providerId":{"type":"string"},"threadId":{"nullable":true,"type":"string"},"subjectOrTitle":{"type":"string"},"snippet":{"nullable":true,"type":"string"},"dateTime":{"type":"string"},"endDateTime":{"nullable":true,"type":"string"},"isAllDay":{"type":"boolean"},"participants":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string"},"name":{"nullable":true,"type":"string"}},"required":["email"],"additionalProperties":false}},"providerLink":{"nullable":true,"type":"string"},"email":{"type":"string"},"iCalUID":{"nullable":true,"type":"string"},"isRecurring":{"type":"boolean"},"provider":{"type":"string"}},"additionalProperties":{}}},"required":["type","date","data"],"additionalProperties":{}},{"type":"object","properties":{"type":{"type":"string","enum":["FEED"]},"date":{"type":"string"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"contact_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"feed_type":{"type":"string"},"body":{"type":"object","properties":{"name":{"type":"string"},"title_before":{"nullable":true,"type":"string"},"title_after":{"type":"string"},"linkedin_url":{"type":"string"}},"required":["name","title_before","title_after","linkedin_url"],"additionalProperties":{}},"created_at":{"type":"string"}},"required":["id","user_id","feed_type","body","created_at"],"additionalProperties":{}}},"required":["type","date","data"],"additionalProperties":{}}]}},"nextCursor":{"nullable":true,"type":"string"},"hasMore":{"type":"boolean"},"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"timedOutSources":{"type":"array","items":{"type":"string","enum":["notes","reminders","emails","calendar","feed"]}}},"required":["items","nextCursor","hasMore","count","timedOutSources"],"additionalProperties":{}}},"required":["error","data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"listTimelineItemsV1","summary":"Get unified timeline","description":"Retrieve a unified, paginated timeline combining notes, reminders, emails, and calendar events. Supports filtering by source type, contact, date range, and text search.","x-mint":{"content":"## Use cases\n\n- Display a unified activity feed on the timeline page\n- Show all interactions with a specific contact in one timeline\n- Search across notes and reminders with a single API call\n- Filter timeline to specific source types (e.g., only emails and calendar events)"}}},"/v1/users/me":{"get":{"tags":["users"],"parameters":[{"schema":{"type":"array","items":{"type":"string"}},"in":"query","name":"include","required":false,"description":"Related records to include (e.g. mobile_settings, workflow_settings)"},{"schema":{"type":"boolean"},"in":"query","name":"fresh","required":false,"description":"Skip the cache and fetch the latest data from the database"}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","description":"Unique user identifier (Firebase UID)"},"first_name":{"nullable":true,"description":"User's first name","type":"string"},"last_name":{"nullable":true,"description":"User's last name","type":"string"},"email":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$","description":"User's email address"},"image_url":{"nullable":true,"description":"Profile image URL","type":"string"},"time_zone":{"type":"string","description":"User's time zone (IANA format)"},"pricing_plan":{"type":"string","description":"Current subscription plan"},"onboarded_web":{"type":"boolean","description":"Whether the user has completed web onboarding"},"onboarded_mobile":{"type":"boolean","description":"Whether the user has completed mobile onboarding"},"created_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}],"description":"Account creation timestamp"},"updated_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}],"description":"Last profile update timestamp"}},"additionalProperties":{}}},"required":["error","data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getCurrentUserV1","summary":"Get current user","description":"Retrieve the profile of the currently authenticated user. Returns account details including name, email, time zone, subscription plan, and onboarding status.","x-mint":{"content":"## Use cases\n\n- Display the current user's profile in your application\n- Check the user's subscription plan before accessing plan-gated features\n- Verify the authenticated user's identity and account status\n\nThis endpoint returns the user associated with the API key or access token used in the request. No user ID parameter is needed."}}},"/v2":{"get":{"responses":{"200":{"description":"The API is reachable. Returns a plain-text greeting; use it as an unauthenticated liveness probe for the v2 surface.","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"text/plain":{"schema":{"type":"string","example":"Welcome to Dex Lightning API!"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getApiRootV2","summary":"API root (v2)","description":"Unauthenticated liveness check for the v2 surface. Takes no parameters and returns a plain-text greeting with a 200 status. Use it to confirm connectivity and DNS before authenticating; it does not validate your API key.","security":[]}},"/v2/reminders/{reminderId}":{"get":{"tags":["reminders"],"parameters":[{"schema":{"type":"object","properties":{"recurrence":{"type":"boolean"},"contacts":{"type":"boolean"}},"additionalProperties":{"type":"boolean"}},"in":"query","name":"include","required":false},{"schema":{"type":"object","properties":{"recurrence":{"type":"boolean"},"contacts":{"type":"boolean"}},"additionalProperties":{"type":"boolean"}},"in":"query","name":"select","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"reminderId","required":true}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"reminder":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"text":{"nullable":true,"type":"string"},"due_at_date":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"due_at_time":{"nullable":true,"anyOf":[{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},{"type":"string"}]},"is_complete":{"type":"boolean"},"email_sent":{"type":"boolean"},"push_notification_sent":{"type":"boolean"},"recurrence":{"nullable":true,"type":"string"},"last_completed_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"next_occurrence_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"created_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"is_overdue":{"type":"boolean"},"next_cursor":{"type":"string"},"reminders_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"users":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}}},"required":["id"],"additionalProperties":false}},"required":["reminder"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getReminderV2","summary":"Get a reminder (v2)","description":"Retrieve a single reminder by its unique ID. Returns the canonical /v2 envelope `{ data: { reminder } }` — see Migration notes below.","x-mint":{"content":"## Use cases\n\n- Display reminder details on a detail or edit page\n- Fetch the latest reminder state before updating it\n\n## Migration from /v1\n\nThe /v1 endpoint returns `{ error: false, data: { ...reminder } }` (reminder spread directly into `data`). The /v2 endpoint returns `{ data: { reminder: {...} } }` — namespaced under `data.reminder`, and no `error` field on success (HTTP status is the source of truth)."}},"patch":{"tags":["reminders"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reminder":{"type":"object","properties":{"text":{"anyOf":[{"type":"string"},{"type":"null"}]},"due_at_date":{},"due_at_time":{"anyOf":[{},{"type":"null"}]},"is_complete":{"type":"boolean"},"recurrence":{"anyOf":[{"type":"string"},{"type":"null"}]},"reminders_contacts":{"type":"array","items":{"type":"object","properties":{"contact_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"contacts":{}},"required":["contact_id"],"additionalProperties":false}},"last_completed_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}]},"next_occurrence_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{"type":"null"}]},"email_sent":{"type":"boolean"},"push_notification_sent":{"type":"boolean"}},"additionalProperties":false}},"required":["reminder"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string"},"in":"path","name":"reminderId","required":true},{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","minLength":8,"maxLength":255,"pattern":"^[\\w\\-:.]+$","example":"01HV8N6X7K3P9Q5R2T4Y6W8Z0A"},"description":"Required. UUID per logical operation, reused on every retry. See `apps/rest-api/src/shared/idempotency.ts` for the full contract. Missing → 400 BadRequest; same key + different body → 409 Conflict."}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"reminder":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"text":{"nullable":true,"type":"string"},"due_at_date":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"due_at_time":{"nullable":true,"anyOf":[{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},{"type":"string"}]},"is_complete":{"type":"boolean"},"email_sent":{"type":"boolean"},"push_notification_sent":{"type":"boolean"},"recurrence":{"nullable":true,"type":"string"},"last_completed_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"next_occurrence_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"created_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"is_overdue":{"type":"boolean"},"next_cursor":{"type":"string"},"reminders_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"users":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}}},"required":["id"],"additionalProperties":false}},"required":["reminder"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"updateReminderV2","summary":"Update a reminder (v2)","description":"Partially update a reminder by its ID. **Requires an `Idempotency-Key` header**. Returns `{ data: { reminder: {...} } }` with the post-update row.","x-mint":{"content":"## Use cases\n\n- Reschedule a reminder to a different date\n- Mark a reminder as completed\n- Reassign a reminder to a different contact\n\n## Migration from /v1\n\n/v1 used `PUT /v1/reminders/:id`. /v2 uses `PATCH` because the body is a partial update (PUT semantically means \"replace the resource entirely\").\n\n## Idempotency\n\nSee the create endpoint for the full idempotency contract."}},"delete":{"tags":["reminders"],"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"reminderId","required":true},{"in":"header","name":"Idempotency-Key","required":false,"schema":{"type":"string","minLength":8,"maxLength":255,"pattern":"^[\\w\\-:.]+$","example":"01HV8N6X7K3P9Q5R2T4Y6W8Z0A"},"description":"Optional. Accepted to dedupe retries on this endpoint. See `apps/rest-api/src/shared/idempotency.ts`."}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"affected":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"ids":{"type":"array","items":{"type":"string"}},"failed":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","error"],"additionalProperties":false}}},"required":["affected"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"deleteReminderV2","summary":"Delete a reminder (v2)","description":"Permanently delete a reminder by its ID. `Idempotency-Key` is optional on DELETE (the operation is HTTP-idempotent by semantics). Returns `{ data: { affected: 1, ids: [reminderId] } }`.","x-mint":{"content":"## Use cases\n\n- Remove a reminder that is no longer relevant\n- Cancel a recurring keep-in-touch cadence\n\nDeleting a recurring reminder cancels all future occurrences. This action cannot be undone."}}},"/v2/reminders/":{"get":{"tags":["reminders"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":9007199254740991},"in":"query","name":"take","required":false},{"schema":{"type":"integer","minimum":0,"maximum":9007199254740991},"in":"query","name":"skip","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"cursor","required":false},{"schema":{"type":"object","properties":{"in":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"not_in":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"is_complete":{"type":"boolean"},"is_overdue":{"type":"boolean"},"has_contacts":{"anyOf":[{"type":"object","properties":{"not":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}]}},"required":["not"],"additionalProperties":false},{"type":"boolean"},{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}]},"has_due_at_date":{"type":"object","properties":{"gte":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"lte":{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}},"additionalProperties":false},"has_created_at":{"type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false}},"additionalProperties":false},"in":"query","name":"where","required":false},{"schema":{},"in":"query","name":"orderBy","required":false},{"schema":{"type":"object","properties":{"recurrence":{"type":"boolean"},"contacts":{"type":"boolean"}},"additionalProperties":{"type":"boolean"}},"in":"query","name":"include","required":false},{"schema":{"type":"object","properties":{"recurrence":{"type":"boolean"},"contacts":{"type":"boolean"}},"additionalProperties":{"type":"boolean"}},"in":"query","name":"select","required":false}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"reminders":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"text":{"nullable":true,"type":"string"},"due_at_date":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"due_at_time":{"nullable":true,"anyOf":[{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},{"type":"string"}]},"is_complete":{"type":"boolean"},"email_sent":{"type":"boolean"},"push_notification_sent":{"type":"boolean"},"recurrence":{"nullable":true,"type":"string"},"last_completed_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"next_occurrence_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"created_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"is_overdue":{"type":"boolean"},"next_cursor":{"type":"string"},"reminders_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"users":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}}},"required":["id"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"nextCursor":{"nullable":true,"type":"string"},"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"additionalProperties":false}},"required":["reminders"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"listRemindersV2","summary":"List reminders (v2)","description":"Retrieve all reminders for the authenticated user. Supports filtering, sorting, and cursor pagination. Returns `{ data: { reminders: [...], pagination?: { nextCursor, count } } }`.","x-mint":{"content":"## Use cases\n\n- Display an upcoming-reminders dashboard with infinite scroll\n- Show all reminders associated with a specific contact\n- Sync reminders to an external calendar\n\n## Migration from /v1\n\nThe /v1 list returns `{ data: { items: [...], nextCursor } }`. The /v2 list returns `{ data: { reminders: [...], pagination: { nextCursor } } }` — entity plural at the top level, pagination namespaced."}},"post":{"tags":["reminders"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reminder":{"type":"object","properties":{"text":{"anyOf":[{"type":"string"},{"type":"null"}]},"due_at_date":{},"due_at_time":{"anyOf":[{},{"type":"null"}]},"is_complete":{"type":"boolean"},"recurrence":{"anyOf":[{"type":"string"},{"type":"null"}]},"reminders_contacts":{"type":"array","items":{"type":"object","properties":{"contact_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"contacts":{}},"required":["contact_id"],"additionalProperties":false}},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["due_at_date"],"additionalProperties":false}},"required":["reminder"],"additionalProperties":false}}}},"responses":{"201":{"description":"Created","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"reminder":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"text":{"nullable":true,"type":"string"},"due_at_date":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"due_at_time":{"nullable":true,"anyOf":[{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},{"type":"string"}]},"is_complete":{"type":"boolean"},"email_sent":{"type":"boolean"},"push_notification_sent":{"type":"boolean"},"recurrence":{"nullable":true,"type":"string"},"last_completed_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"next_occurrence_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"created_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"is_overdue":{"type":"boolean"},"next_cursor":{"type":"string"},"reminders_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"users":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}}},"required":["id"],"additionalProperties":false}},"required":["reminder"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"createReminderV2","summary":"Create a reminder (v2)","description":"Create a new reminder for the authenticated user. **Requires an `Idempotency-Key` header** — see Idempotency below. Returns `{ data: { reminder: {...} } }` with status 201.","x-mint":{"content":"## Use cases\n\n- Set a follow-up reminder after a meeting or call\n- Create a keep-in-touch cadence for an important contact\n\n## Idempotency\n\nEvery write on /v2 requires an `Idempotency-Key` header containing a UUID. Generate it client-side per LOGICAL operation and reuse the same key on every retry — that lets the server replay the original response instead of executing the write twice. TanStack DB collections pass `mutationId` directly; ad-hoc callers use `crypto.randomUUID()`.\n\nThe SDK throws if you call `sdk.v2.reminders.create()` without an `idempotencyKey` option."},"parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","minLength":8,"maxLength":255,"pattern":"^[\\w\\-:.]+$","example":"01HV8N6X7K3P9Q5R2T4Y6W8Z0A"},"description":"Required. UUID per logical operation, reused on every retry. See `apps/rest-api/src/shared/idempotency.ts` for the full contract. Missing → 400 BadRequest; same key + different body → 409 Conflict."}]}},"/v2/reminders/recurring":{"get":{"tags":["reminders"],"parameters":[{"schema":{"type":"object","properties":{"recurrence":{"type":"boolean"},"contacts":{"type":"boolean"}},"additionalProperties":{"type":"boolean"}},"in":"query","name":"include","required":false}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"reminders":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"text":{"nullable":true,"type":"string"},"due_at_date":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"due_at_time":{"nullable":true,"anyOf":[{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},{"type":"string"}]},"is_complete":{"type":"boolean"},"email_sent":{"type":"boolean"},"push_notification_sent":{"type":"boolean"},"recurrence":{"nullable":true,"type":"string"},"last_completed_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"next_occurrence_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"created_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"is_overdue":{"type":"boolean"},"next_cursor":{"type":"string"},"reminders_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"users":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}}},"required":["id"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"nextCursor":{"nullable":true,"type":"string"},"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"additionalProperties":false}},"required":["reminders"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"listRecurringRemindersV2","summary":"List recurring reminders (v2)","description":"Retrieve all recurring (keep-in-touch) reminders for the authenticated user. Non-paginated — returns `{ data: { reminders: [...] } }` without a pagination object.","x-mint":{"content":"## Use cases\n\n- Display a keep-in-touch dashboard showing recurring outreach commitments\n- Review and manage all recurring reminder schedules"}}},"/v2/agenda/calendar/events":{"get":{"tags":["agenda"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":9007199254740991},"in":"query","name":"limit","required":false},{"schema":{"type":"string","minLength":1,"maxLength":500},"in":"query","name":"searchQuery","required":false},{"schema":{"type":"object","properties":{"start":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"end":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false},"in":"query","name":"dateRange","required":false}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"calendar_events":{"type":"array","items":{"type":"object","properties":{"providerId":{"type":"string"},"type":{"type":"string","enum":["EMAIL","CALENDAR"]},"subjectOrTitle":{"type":"string"},"dateTime":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"endDateTime":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"isAllDay":{"nullable":true,"type":"boolean"},"participants":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string"},"name":{"nullable":true,"type":"string"}},"required":["email"],"additionalProperties":false}},"providerLink":{"nullable":true,"type":"string"},"email":{"type":"string"},"iCalUID":{"nullable":true,"type":"string"},"summaryOfEvent":{"nullable":true,"type":"string"},"descriptionOfEvent":{"nullable":true,"type":"string"},"conferenceData":{"nullable":true,"type":"object","properties":{"conferenceId":{"nullable":true,"type":"string"},"entryPoints":{"nullable":true,"type":"array","items":{"type":"object","properties":{"uri":{"nullable":true,"type":"string"},"label":{"nullable":true,"type":"string"},"accessCode":{"nullable":true,"type":"string"}},"additionalProperties":false}}},"additionalProperties":false},"isRecurring":{"nullable":true,"type":"boolean"},"provider":{"nullable":true,"type":"string"}},"required":["providerId","type","subjectOrTitle","dateTime","participants","email"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"nextCursor":{"nullable":true,"type":"string"},"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"additionalProperties":false}},"required":["calendar_events"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"listCalendarEventsV2","summary":"List calendar events (v2)","description":"External calendar events fetched live from the authenticated user's connected Google / Office365 credentials via the sync-engine — there's no DB table. Optional `limit` and `dateRange.{start,end}` (ISO datetimes) scope the window; optional `searchQuery` free-text-filters by title, description, location, and attendees. Returns `{ data: { calendar_events, pagination } }`; an empty list when no calendar is connected."},"post":{"tags":["agenda"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"summary":{"type":"string","minLength":1},"description":{"type":"string"},"location":{"type":"string"},"attendees":{"maxItems":100,"type":"array","items":{"type":"object","properties":{"email":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"display_name":{"type":"string"}},"required":["email"],"additionalProperties":false}},"account_email":{"type":"string"},"account_provider":{"type":"string","enum":["GOOGLE","OFFICE365"]},"start_datetime":{"description":"Event start, ISO 8601 with offset (timed events)","type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"end_datetime":{"description":"Event end, ISO 8601 with offset (timed events)","type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"timezone":{"description":"IANA timezone for the event (e.g. \"America/New_York\")","type":"string","minLength":1},"start_date":{"description":"Event start date, YYYY-MM-DD (all-day events)","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"end_date":{"description":"Event end date, YYYY-MM-DD, EXCLUSIVE (all-day events; a one-day event on the 10th ends on the 11th)","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}},"required":["summary"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"calendar_event":{"type":"object","properties":{"providerId":{"type":"string"},"type":{"type":"string","enum":["EMAIL","CALENDAR"]},"subjectOrTitle":{"type":"string"},"dateTime":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"endDateTime":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"isAllDay":{"nullable":true,"type":"boolean"},"participants":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string"},"name":{"nullable":true,"type":"string"}},"required":["email"],"additionalProperties":false}},"providerLink":{"nullable":true,"type":"string"},"email":{"type":"string"},"iCalUID":{"nullable":true,"type":"string"},"summaryOfEvent":{"nullable":true,"type":"string"},"descriptionOfEvent":{"nullable":true,"type":"string"},"conferenceData":{"nullable":true,"type":"object","properties":{"conferenceId":{"nullable":true,"type":"string"},"entryPoints":{"nullable":true,"type":"array","items":{"type":"object","properties":{"uri":{"nullable":true,"type":"string"},"label":{"nullable":true,"type":"string"},"accessCode":{"nullable":true,"type":"string"}},"additionalProperties":false}}},"additionalProperties":false},"isRecurring":{"nullable":true,"type":"boolean"},"provider":{"nullable":true,"type":"string"}},"required":["providerId","type","subjectOrTitle","dateTime","participants","email"],"additionalProperties":false}},"required":["calendar_event"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"createCalendarEventV2","summary":"Create a calendar event (v2)","description":"Create an event on the connected calendar (primary account by default). Set start_datetime/end_datetime for a timed event, or start_date/end_date for an all-day event (end date exclusive). **Requires an `Idempotency-Key` header.** Returns `{ data: { calendar_event } }`.","x-mint":{"content":"## Use cases\n\n- Schedule a meeting with contacts as attendees\n- Block out an all-day engagement\n\n## Idempotency\n\nEvery write on /v2 requires an `Idempotency-Key` header (a UUID generated per logical operation, reused on retry).\n\n## Account selection\n\nOmit `account_email` and the write targets the primary connected calendar, falling back to the oldest — in both cases preferring an account that actually holds the write scope. Name `account_email` to target a specific calendar; a named account is never silently retargeted.\n\nRequires the connected account to have calendar write permission. An account connected before Dex began requesting write scopes holds read-only access and must re-grant it (Settings → Sync & Integrations → Grant calendar access) before writes succeed."}}},"/v2/agenda/email/messages":{"get":{"tags":["agenda"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":9007199254740991},"in":"query","name":"limit","required":false},{"schema":{"type":"string","minLength":1,"maxLength":500},"in":"query","name":"searchQuery","required":false},{"schema":{"type":"object","properties":{"start":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"end":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false},"in":"query","name":"dateRange","required":false}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"email_messages":{"type":"array","items":{"type":"object","properties":{"providerId":{"type":"string"},"threadId":{"nullable":true,"type":"string"},"type":{"type":"string","enum":["EMAIL","CALENDAR"]},"subjectOrTitle":{"type":"string"},"snippet":{"nullable":true,"type":"string"},"dateTime":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"from":{"nullable":true,"type":"object","properties":{"email":{"type":"string"},"name":{"nullable":true,"type":"string"}},"required":["email"],"additionalProperties":false},"participants":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string"},"name":{"nullable":true,"type":"string"}},"required":["email"],"additionalProperties":false}},"providerLink":{"nullable":true,"type":"string"},"email":{"type":"string"},"provider":{"nullable":true,"type":"string"}},"required":["providerId","type","subjectOrTitle","dateTime","participants","email"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"nextCursor":{"nullable":true,"type":"string"},"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"additionalProperties":false}},"required":["email_messages"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"listEmailMessagesV2","summary":"Search emails (v2)","description":"Free-text email search across ALL of the authenticated user's connected mail accounts, fetched live from the providers (Google / Microsoft) — Dex stores no message content. `searchQuery` matches subject, body, and participants as plain text (provider search operators are neutralized); optional `limit` (default 25) and `dateRange.{start,end}` scope the window, defaulting to roughly the last 6 months. Returns `{ data: { email_messages, pagination } }` with sender, participants, subject, snippet, and a provider deep link per message.","x-mint":{"content":"## Use cases\n\n- Find correspondence with a person, company, or email domain (e.g. everyone you have emailed at an organization)\n- Locate a specific email by topic before logging a note or creating a contact\n\nRequires a connected Google or Microsoft account with mail access — returns a 400 with an actionable message when none is connected. Results are message metadata (subject, snippet, participants), not full bodies; use the `providerLink` to open the message in the provider UI."}}},"/v2/agenda/calendar/events/{eventId}":{"get":{"tags":["agenda"],"parameters":[{"schema":{"type":"string"},"in":"query","name":"account_email","required":false},{"schema":{"type":"string","enum":["GOOGLE","OFFICE365"]},"in":"query","name":"account_provider","required":false},{"schema":{"type":"string","minLength":1},"in":"path","name":"eventId","required":true}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"calendar_event":{"type":"object","properties":{"providerId":{"type":"string"},"type":{"type":"string","enum":["EMAIL","CALENDAR"]},"subjectOrTitle":{"type":"string"},"dateTime":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"endDateTime":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"isAllDay":{"nullable":true,"type":"boolean"},"participants":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string"},"name":{"nullable":true,"type":"string"}},"required":["email"],"additionalProperties":false}},"providerLink":{"nullable":true,"type":"string"},"email":{"type":"string"},"iCalUID":{"nullable":true,"type":"string"},"summaryOfEvent":{"nullable":true,"type":"string"},"descriptionOfEvent":{"nullable":true,"type":"string"},"conferenceData":{"nullable":true,"type":"object","properties":{"conferenceId":{"nullable":true,"type":"string"},"entryPoints":{"nullable":true,"type":"array","items":{"type":"object","properties":{"uri":{"nullable":true,"type":"string"},"label":{"nullable":true,"type":"string"},"accessCode":{"nullable":true,"type":"string"}},"additionalProperties":false}}},"additionalProperties":false},"isRecurring":{"nullable":true,"type":"boolean"},"provider":{"nullable":true,"type":"string"}},"required":["providerId","type","subjectOrTitle","dateTime","participants","email"],"additionalProperties":false}},"required":["calendar_event"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getCalendarEventV2","summary":"Get a calendar event (v2)","description":"Retrieve a single calendar event by its provider event ID, including attendees, conferencing links, and recurrence flags. Reads from the primary connected calendar unless `account_email` selects another connected account; when no `account_email` is given and the primary account does not have the event, every connected calendar account is searched for it. Returns `{ data: { calendar_event } }`.","x-mint":{"content":"## Use cases\n\n- Inspect attendees and conferencing details for a meeting\n- Fetch the latest event state before updating it\n\nEvents are fetched live from the provider (Google / Microsoft) — nothing is stored in Dex. The `email` field on a listed event tells you which connected account to pass as `account_email`."}},"patch":{"tags":["agenda"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"summary":{"type":"string","minLength":1},"description":{"type":"string"},"location":{"type":"string"},"attendees":{"maxItems":100,"type":"array","items":{"type":"object","properties":{"email":{"type":"string","format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"display_name":{"type":"string"}},"required":["email"],"additionalProperties":false}},"account_email":{"type":"string"},"account_provider":{"type":"string","enum":["GOOGLE","OFFICE365"]},"start_datetime":{"description":"Event start, ISO 8601 with offset (timed events)","type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"end_datetime":{"description":"Event end, ISO 8601 with offset (timed events)","type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"timezone":{"description":"IANA timezone for the event (e.g. \"America/New_York\")","type":"string","minLength":1},"start_date":{"description":"Event start date, YYYY-MM-DD (all-day events)","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},"end_date":{"description":"Event end date, YYYY-MM-DD, EXCLUSIVE (all-day events; a one-day event on the 10th ends on the 11th)","type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","minLength":1},"in":"path","name":"eventId","required":true}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"calendar_event":{"type":"object","properties":{"providerId":{"type":"string"},"type":{"type":"string","enum":["EMAIL","CALENDAR"]},"subjectOrTitle":{"type":"string"},"dateTime":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"endDateTime":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"isAllDay":{"nullable":true,"type":"boolean"},"participants":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string"},"name":{"nullable":true,"type":"string"}},"required":["email"],"additionalProperties":false}},"providerLink":{"nullable":true,"type":"string"},"email":{"type":"string"},"iCalUID":{"nullable":true,"type":"string"},"summaryOfEvent":{"nullable":true,"type":"string"},"descriptionOfEvent":{"nullable":true,"type":"string"},"conferenceData":{"nullable":true,"type":"object","properties":{"conferenceId":{"nullable":true,"type":"string"},"entryPoints":{"nullable":true,"type":"array","items":{"type":"object","properties":{"uri":{"nullable":true,"type":"string"},"label":{"nullable":true,"type":"string"},"accessCode":{"nullable":true,"type":"string"}},"additionalProperties":false}}},"additionalProperties":false},"isRecurring":{"nullable":true,"type":"boolean"},"provider":{"nullable":true,"type":"string"}},"required":["providerId","type","subjectOrTitle","dateTime","participants","email"],"additionalProperties":false}},"required":["calendar_event"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"updateCalendarEventV2","summary":"Update a calendar event (v2)","description":"Partially update an event by its provider event ID. Only provided fields change; sending new times can switch an event between timed and all-day. **Requires an `Idempotency-Key` header.** Returns `{ data: { calendar_event } }`.","x-mint":{"content":"## Use cases\n\n- Reschedule a meeting\n- Rename an event or update its description, location, or attendee list\n\n## Migration from /v1\n\nThere was no /v1 calendar update endpoint — this is a new /v2 surface. It uses `PATCH` (partial update) and requires an `Idempotency-Key` header."}},"delete":{"tags":["agenda"],"parameters":[{"schema":{"type":"string"},"in":"query","name":"account_email","required":false},{"schema":{"type":"string","enum":["GOOGLE","OFFICE365"]},"in":"query","name":"account_provider","required":false},{"schema":{"type":"string","minLength":1},"in":"path","name":"eventId","required":true}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"affected":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"ids":{"type":"array","items":{"type":"string"}},"failed":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","error"],"additionalProperties":false}}},"required":["affected"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"deleteCalendarEventV2","summary":"Delete a calendar event (v2)","description":"Delete an event from the connected calendar by its provider event ID. Deleting an event you organize cancels it for all attendees. Returns `{ data: { affected, ids } }`. `Idempotency-Key` is optional.","x-mint":{"content":"## Use cases\n\n- Cancel a meeting\n- Remove an obsolete event\n\nThis is irreversible and, for events with attendees, cancels the meeting for everyone."}}},"/v2/contacts/{contactId}":{"get":{"tags":["contacts"],"parameters":[{"schema":{"type":"object","properties":{"linkedin_data":{"type":"boolean"},"groups_count":{"type":"boolean"},"coordinates":{"type":"boolean"}},"additionalProperties":{"type":"boolean"}},"in":"query","name":"include","required":false},{"schema":{"type":"object","properties":{"linkedin_data":{"type":"boolean"},"groups_count":{"type":"boolean"},"coordinates":{"type":"boolean"}},"additionalProperties":{"type":"boolean"}},"in":"query","name":"select","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"contactId","required":true}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"contact":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"first_name":{"nullable":true,"type":"string"},"last_name":{"nullable":true,"type":"string"},"full_name":{"nullable":true,"type":"string"},"description":{"nullable":true,"type":"string"},"job_title":{"nullable":true,"type":"string"},"company":{"nullable":true,"type":"string"},"education":{"nullable":true,"type":"string"},"legacy_location":{"nullable":true,"type":"string"},"image_url":{"nullable":true,"type":"string"},"business_card_url":{"nullable":true,"type":"string"},"website":{"nullable":true,"type":"string"},"image_source":{"nullable":true,"type":"string"},"birthday":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"birthday_year":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"linkedin":{"nullable":true,"type":"string"},"twitter":{"nullable":true,"type":"string"},"facebook":{"nullable":true,"type":"string"},"instagram":{"nullable":true,"type":"string"},"telegram":{"nullable":true,"type":"string"},"tiktok":{"nullable":true,"type":"string"},"youtube":{"nullable":true,"type":"string"},"starred":{"type":"boolean"},"is_archived":{"type":"boolean"},"ignore_merge":{"type":"boolean"},"never_keep_in_touch":{"type":"boolean"},"source":{"type":"string"},"priority_tier":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"frequency":{"nullable":true,"type":"string"},"frequency_text":{"nullable":true,"type":"string"},"last_seen_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"last_reminder_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"next_reminder_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"first_met_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"first_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_companies":{"nullable":true,"type":"string"},"linkedin_education":{"nullable":true,"type":"string"},"linkedin_enhance_date":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_last_message_snippet":{"nullable":true,"type":"string"},"linkedin_message_link":{"nullable":true,"type":"string"},"whatsapp_message_link":{"nullable":true,"type":"string"},"whatsapp_message_snippet":{"nullable":true,"type":"string"},"whatsapp_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"imessage_message_link":{"nullable":true,"type":"string"},"imessage_message_snippet":{"nullable":true,"type":"string"},"imessage_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"instagram_message_link":{"nullable":true,"type":"string"},"instagram_message_snippet":{"nullable":true,"type":"string"},"instagram_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"gmail_last_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"gmail_last_interaction_provider":{"nullable":true,"type":"string","enum":["GOOGLE","OFFICE365"]},"gmail_last_interaction_provider_id":{"nullable":true,"type":"string"},"gmail_last_interaction_subject":{"nullable":true,"type":"string"},"gcal_last_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"gcal_last_interaction_provider":{"nullable":true,"type":"string","enum":["GOOGLE","OFFICE365"]},"gcal_last_interaction_provider_id":{"nullable":true,"type":"string"},"gcal_last_interaction_title":{"nullable":true,"type":"string"},"phone_call_interaction_snippet":{"nullable":true,"type":"string"},"phone_call_last_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"web_search_summary":{"nullable":true},"created_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"updated_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"geocode_attempts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"geocode_failed_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"_count":{"type":"object","properties":{"groups_contacts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["groups_contacts"],"additionalProperties":false},"frequency_interval":{},"linkedin_data":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"latitude":{"nullable":true,"type":"number"},"longitude":{"nullable":true,"type":"number"},"contact_emails":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_phone_numbers":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_birthdays":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"contact_locations":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contacts_custom_fields":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"legacy_contact_addresses":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"groups_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"tags_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"timeline_items_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"reminders_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_relations_contact_relations_sourceTocontacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_relations_contact_relations_destinationTocontacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"feed_items":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"keep_in_touch_reminders":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}}},"required":["id"],"additionalProperties":false}},"required":["contact"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getContactV2","summary":"Get a contact (v2)","description":"Retrieve a contact by ID. Email and phone relations are omitted by default; request them with `?include[contact_emails]=true` or `?include[contact_phone_numbers]=true`.","x-mint":{"content":"## Use cases\n\n- Display contact detail pages\n- Fetch the latest state before an update\n\n## Related data\n\nRelations are omitted unless requested. Add `?include[contact_emails]=true` for email addresses or `?include[contact_phone_numbers]=true` for phone numbers. Use `select` instead when you want a narrow projection; `include` and `select` cannot be combined.\n\n## Migration from /v1\n\n/v1: `{ error: false, data: { ...contact } }` (contact fields spread onto `data`).\n/v2: `{ data: { contact: {...} } }` — namespaced under `data.contact`, no `error` field on success."}},"patch":{"tags":["contacts"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"full_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"first_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"job_title":{"anyOf":[{"type":"string"},{"type":"null"}]},"legacy_location":{"anyOf":[{"type":"string"},{"type":"null"}]},"company":{"anyOf":[{"type":"string"},{"type":"null"}]},"education":{"anyOf":[{"type":"string"},{"type":"null"}]},"starred":{"type":"boolean"},"source":{"type":"string","enum":["linkedin_sync","facebook_import","cal_ingest","email_ingest","web_import","csv_import","whatsapp_sync","imessage_sync","phone_calls_sync","mobile","mobile_import","instagram_sync","oauth_interaction"]},"coordinates":{"type":"object","properties":{"operation":{"type":"string","enum":["set","delete"]},"data":{"type":"object","properties":{"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180}},"additionalProperties":false}},"required":["operation"],"additionalProperties":false},"priority_tier":{"anyOf":[{"type":"integer","minimum":1,"maximum":32767},{"type":"null"}]},"image_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"image_source":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"business_card_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"website":{"anyOf":[{},{"type":"null"}]},"birthday":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"birthday_year":{"anyOf":[{"type":"number","minimum":1900,"maximum":2100},{"type":"null"}]},"frequency":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_seen_at":{"anyOf":[{},{"type":"null"}]},"first_met_at":{"anyOf":[{},{"type":"null"}]},"never_keep_in_touch":{"type":"boolean"},"next_reminder_at":{},"linkedin":{"anyOf":[{"type":"string"},{"type":"null"}]},"twitter":{"anyOf":[{"type":"string"},{"type":"null"}]},"facebook":{"anyOf":[{"type":"string"},{"type":"null"}]},"instagram":{"anyOf":[{"type":"string"},{"type":"null"}]},"telegram":{"anyOf":[{"type":"string"},{"type":"null"}]},"tiktok":{"anyOf":[{"type":"string"},{"type":"null"}]},"youtube":{"anyOf":[{"type":"string"},{"type":"null"}]},"whatsapp_message_link":{"type":"string"},"whatsapp_message_snippet":{"anyOf":[{"type":"string"},{"type":"null"}]},"whatsapp_last_message_at":{"anyOf":[{},{"type":"null"}]},"imessage_message_link":{"type":"string"},"imessage_message_snippet":{"anyOf":[{"type":"string"},{"type":"null"}]},"imessage_last_message_at":{"anyOf":[{},{"type":"null"}]},"linkedin_message_link":{"type":"string","maxLength":600},"linkedin_last_message_snippet":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"linkedin_last_message_at":{"anyOf":[{},{"type":"null"}]},"linkedin_data":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"instagram_message_link":{"type":"string"},"instagram_message_snippet":{"anyOf":[{"type":"string"},{"type":"null"}]},"instagram_last_message_at":{"anyOf":[{},{"type":"null"}]},"gmail_last_interaction_at":{"anyOf":[{},{"type":"null"}]},"gmail_last_interaction_provider_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"gmail_last_interaction_subject":{"anyOf":[{"type":"string"},{"type":"null"}]},"gmail_last_interaction_provider":{"anyOf":[{"type":"string","enum":["GOOGLE","OFFICE365"]},{"type":"null"}]},"gcal_last_interaction_at":{"anyOf":[{},{"type":"null"}]},"gcal_last_interaction_provider_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"gcal_last_interaction_title":{"anyOf":[{"type":"string"},{"type":"null"}]},"gcal_last_interaction_provider":{"anyOf":[{"type":"string","enum":["GOOGLE","OFFICE365"]},{"type":"null"}]},"phone_call_last_interaction_at":{"anyOf":[{},{"type":"null"}]},"phone_call_interaction_snippet":{"anyOf":[{"type":"string"},{"type":"null"}]},"web_search_summary":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"legacy_contact_addresses":{"type":"array","items":{"type":"object","properties":{"formatted":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false}},"contact_emails":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string","maxLength":320},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"ranking":{"type":"number"}},"required":["email"],"additionalProperties":false}},"contact_phone_numbers":{"type":"array","items":{"type":"object","properties":{"phone_number":{"type":"string","maxLength":50},"country_code":{"anyOf":[{"type":"string","maxLength":4},{"type":"null"}]},"phone_number_sanitized":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"ranking":{"type":"number"}},"required":["phone_number"],"additionalProperties":false}},"groups_contacts":{"type":"array","items":{"type":"object","properties":{"group_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["group_id"],"additionalProperties":false}},"tags_contacts":{"anyOf":[{"type":"object","properties":{"append":{"type":"array","items":{"type":"object","properties":{"tag_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["tag_id"],"additionalProperties":false}},"remove":{"type":"array","items":{"type":"object","properties":{"tag_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"contact_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["tag_id","contact_id"],"additionalProperties":false}},"replace":{}},"additionalProperties":false},{"type":"object","properties":{"append":{},"remove":{},"replace":{"type":"array","items":{"type":"object","properties":{"tag_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["tag_id"],"additionalProperties":false}}},"additionalProperties":false}]},"custom_fields":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"type":{"type":"string","enum":["input"]},"text_value":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}]},"custom_field":{}},"required":["id","type","text_value"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"type":{"type":"string","enum":["autocomplete"]},"text_value":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}]},"custom_field":{}},"required":["id","type","text_value"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"type":{"type":"string","enum":["datepicker"]},"text_value":{"anyOf":[{"type":"string"},{"type":"null"}]},"date_value":{"anyOf":[{},{"type":"null"}]},"custom_field":{}},"required":["id","type"],"additionalProperties":false}]}},"contact_birthdays":{"type":"object","properties":{"contact_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"last_dismissal_year":{"type":"number","minimum":1900,"maximum":2100}},"additionalProperties":false},"is_archived":{"type":"boolean"},"ignore_merge":{"type":"boolean"},"related_contacts":{"anyOf":[{"type":"object","properties":{"append":{"type":"array","items":{"type":"object","properties":{"destination":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"source_contact":{},"destination_contact":{}},"required":["destination"],"additionalProperties":false}},"remove":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"source":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"destination":{}},"required":["source","destination"],"additionalProperties":false},{"type":"object","properties":{"source":{},"destination":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["source","destination"],"additionalProperties":false}]}},"replace":{}},"additionalProperties":false},{"type":"object","properties":{"append":{},"remove":{},"replace":{"type":"array","items":{"type":"object","properties":{"destination":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"source_contact":{},"destination_contact":{}},"required":["destination"],"additionalProperties":false}}},"additionalProperties":false}]}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"contactId","required":true},{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","minLength":8,"maxLength":255,"pattern":"^[\\w\\-:.]+$","example":"01HV8N6X7K3P9Q5R2T4Y6W8Z0A"},"description":"Required. UUID per logical operation, reused on every retry. See `apps/rest-api/src/shared/idempotency.ts` for the full contract. Missing → 400 BadRequest; same key + different body → 409 Conflict."}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"contact":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"first_name":{"nullable":true,"type":"string"},"last_name":{"nullable":true,"type":"string"},"full_name":{"nullable":true,"type":"string"},"description":{"nullable":true,"type":"string"},"job_title":{"nullable":true,"type":"string"},"company":{"nullable":true,"type":"string"},"education":{"nullable":true,"type":"string"},"legacy_location":{"nullable":true,"type":"string"},"image_url":{"nullable":true,"type":"string"},"business_card_url":{"nullable":true,"type":"string"},"website":{"nullable":true,"type":"string"},"image_source":{"nullable":true,"type":"string"},"birthday":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"birthday_year":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"linkedin":{"nullable":true,"type":"string"},"twitter":{"nullable":true,"type":"string"},"facebook":{"nullable":true,"type":"string"},"instagram":{"nullable":true,"type":"string"},"telegram":{"nullable":true,"type":"string"},"tiktok":{"nullable":true,"type":"string"},"youtube":{"nullable":true,"type":"string"},"starred":{"type":"boolean"},"is_archived":{"type":"boolean"},"ignore_merge":{"type":"boolean"},"never_keep_in_touch":{"type":"boolean"},"source":{"type":"string"},"priority_tier":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"frequency":{"nullable":true,"type":"string"},"frequency_text":{"nullable":true,"type":"string"},"last_seen_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"last_reminder_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"next_reminder_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"first_met_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"first_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_companies":{"nullable":true,"type":"string"},"linkedin_education":{"nullable":true,"type":"string"},"linkedin_enhance_date":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_last_message_snippet":{"nullable":true,"type":"string"},"linkedin_message_link":{"nullable":true,"type":"string"},"whatsapp_message_link":{"nullable":true,"type":"string"},"whatsapp_message_snippet":{"nullable":true,"type":"string"},"whatsapp_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"imessage_message_link":{"nullable":true,"type":"string"},"imessage_message_snippet":{"nullable":true,"type":"string"},"imessage_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"instagram_message_link":{"nullable":true,"type":"string"},"instagram_message_snippet":{"nullable":true,"type":"string"},"instagram_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"gmail_last_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"gmail_last_interaction_provider":{"nullable":true,"type":"string","enum":["GOOGLE","OFFICE365"]},"gmail_last_interaction_provider_id":{"nullable":true,"type":"string"},"gmail_last_interaction_subject":{"nullable":true,"type":"string"},"gcal_last_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"gcal_last_interaction_provider":{"nullable":true,"type":"string","enum":["GOOGLE","OFFICE365"]},"gcal_last_interaction_provider_id":{"nullable":true,"type":"string"},"gcal_last_interaction_title":{"nullable":true,"type":"string"},"phone_call_interaction_snippet":{"nullable":true,"type":"string"},"phone_call_last_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"web_search_summary":{"nullable":true},"created_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"updated_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"geocode_attempts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"geocode_failed_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"_count":{"type":"object","properties":{"groups_contacts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["groups_contacts"],"additionalProperties":false},"frequency_interval":{},"linkedin_data":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"latitude":{"nullable":true,"type":"number"},"longitude":{"nullable":true,"type":"number"},"contact_emails":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_phone_numbers":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_birthdays":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"contact_locations":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contacts_custom_fields":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"legacy_contact_addresses":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"groups_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"tags_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"timeline_items_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"reminders_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_relations_contact_relations_sourceTocontacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_relations_contact_relations_destinationTocontacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"feed_items":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"keep_in_touch_reminders":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}}},"required":["id"],"additionalProperties":false}},"required":["contact"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"updateContactV2","summary":"Update a contact (v2)","description":"Partially update a contact by its ID. **Requires `Idempotency-Key`.** Returns `{ data: { contact: {...} } }` with the post-update row. Also fires a Pub/Sub message to auto-add the contact to social groups when LinkedIn / Twitter / Instagram / etc. fields are set.","x-mint":{"content":"## Use cases\n\n- Edit contact details from a profile page\n- Mark a contact as starred or archived\n- Patch fields after enrichment (LinkedIn, social lookup)\n\n## Migration from /v1\n\n/v1 used `PUT /v1/contacts/:id`. /v2 uses `PATCH` because the body is a partial update (PUT semantically means \"replace the resource entirely\").\n\n## Idempotency\n\nUpdates aren't HTTP-idempotent in our partial-update model: two concurrent retries could race with another update from a different client. The key serializes retries to one applied update."}},"delete":{"tags":["contacts"],"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"contactId","required":true},{"in":"header","name":"Idempotency-Key","required":false,"schema":{"type":"string","minLength":8,"maxLength":255,"pattern":"^[\\w\\-:.]+$","example":"01HV8N6X7K3P9Q5R2T4Y6W8Z0A"},"description":"Optional. Accepted to dedupe retries on this endpoint. See `apps/rest-api/src/shared/idempotency.ts`."}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"affected":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"ids":{"type":"array","items":{"type":"string"}},"failed":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","error"],"additionalProperties":false}}},"required":["affected"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"deleteContactV2","summary":"Delete a contact (v2)","description":"Permanently delete a contact by its ID. Returns the canonical bulk envelope: `{ data: { affected: 1, ids: [contactId] } }`. `Idempotency-Key` is optional.","x-mint":{"content":"## Use cases\n\n- Remove a contact added by mistake\n- GDPR / data-removal requests\n\n## Single vs. bulk envelope\n\nThe response uses the same shape as the bulk delete endpoint (`{ affected, ids }`) so the client-side cache-invalidation logic can be uniform across single and bulk deletes. There is no `{ message }` field on /v2 deletes (v1 returned `{ message: \"Contact deleted\" }` which was useless to clients)."}}},"/v2/contacts/":{"get":{"tags":["contacts"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":9007199254740991},"in":"query","name":"take","required":false},{"schema":{"type":"integer","minimum":0,"maximum":9007199254740991},"in":"query","name":"skip","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"cursor","required":false},{"schema":{"type":"object","properties":{"in":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"description":"Match contacts whose id is in this set (single id or array)."},"not_in":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"description":"Exclude contacts whose id is in this set (single id or array)."},"ignore_merge":{"type":"boolean","description":"Filter by the `ignore_merge` flag (excluded from merge suggestions)."},"is_starred":{"type":"boolean","description":"Match starred (true) or non-starred (false) contacts."},"is_archived":{"type":"boolean","description":"Match archived (true) or active (false) contacts. Defaults to false when omitted."},"has_priority_tier":{"anyOf":[{"type":"integer","minimum":1,"maximum":9007199254740991},{"type":"array","items":{"type":"integer","minimum":1,"maximum":9007199254740991}},{"type":"boolean"}],"description":"Relationship priority tier: a tier number, an array of tiers (OR), or a boolean (true = any tier set, false = none)."},"has_linkedin":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"LinkedIn slug: an exact slug string, or a boolean for presence/absence of a LinkedIn handle."},"has_instagram":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"Instagram slug: an exact slug string, or a boolean for presence/absence of an Instagram handle."},"has_twitter":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"Twitter/X slug: an exact slug string, or a boolean for presence/absence of a Twitter handle."},"has_source":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Contact source: a single source string or an array of sources (OR)."},"has_name":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Full name: a bare string (fuzzy contains), an array of exact names, or `{ contains }` / `{ eq }` for explicit fuzzy vs exact match."},"has_groups":{"anyOf":[{"type":"object","properties":{"not":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},"required":["not"],"additionalProperties":false},{"type":"boolean"},{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"array","items":{"type":"string"}}],"description":"Group membership: a group id, an array of group ids (OR), a boolean for any/no group, or `{ not }` to exclude group id(s)."},"has_user_created_groups":{"type":"boolean","description":"Non-system group membership: true for at least one user-created group; false for no user-created groups, including contacts with zero memberships or only Dex system-group memberships."},"has_grouping_signal":{"type":"boolean","description":"Internal organize prefilter: title, company, location, or LinkedIn summary is non-null and non-empty. Whitespace-only values are removed by the organize serializer.","enum":[true]},"has_groups_all":{"description":"Array of group-id rows: AND across rows, OR within each row (contact must be in at least one group from every row).","type":"array","items":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"has_frequency":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"Keep-in-touch cadence: a frequency string, or a boolean for presence/absence of a cadence."},"has_location":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"Location: a string (fuzzy, accent-insensitive match), or a boolean for presence/absence of a location."},"has_location_exact":{"type":"string","description":"Location: exact string match (not fuzzy)."},"has_job_title":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Job title: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }` for explicit fuzzy vs exact match."},"has_never_keep_in_touch":{"type":"boolean","description":"Filter by the `never_keep_in_touch` flag."},"has_created_at":{"description":"Creation-date range: `{ gte?, lte? }` ISO 8601 datetimes (at least one bound required).","type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false},"has_updated_at":{"description":"Last-updated-date range: `{ gte?, lte? }` ISO 8601 datetimes (at least one bound required).","type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false},"has_birthday":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{},{"type":"boolean"}],"description":"Birthday: a specific date (matches on day + month), or true for any birthday set."},"has_tag":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Match contacts carrying this single tag id."},"has_tags":{"anyOf":[{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"type":"object","properties":{"not":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}]}},"required":["not"],"additionalProperties":false}],"description":"Tags: an array of tag ids (OR), or `{ not }` to exclude tag id(s)."},"has_tags_all":{"description":"Array of tag-id rows: AND across rows, OR within each row (contact must carry at least one tag from every row).","type":"array","items":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"has_company":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Company: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }` for explicit fuzzy vs exact match."},"has_education":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Education: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }`."},"has_description":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Description/notes: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }`."},"has_linkedin_companies":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"LinkedIn companies text: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }`."},"has_linkedin_education":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"LinkedIn education text: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }`."},"has_email":{"type":"boolean","description":"Match contacts that have (true) or lack (false) at least one email."},"has_phone_number":{"type":"boolean","description":"Match contacts that have (true) or lack (false) at least one phone number."},"not_has_name":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose full name fuzzily matches this string / any of these strings."},"not_has_company":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose company fuzzily matches this string / any of these strings."},"not_has_job_title":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose job title fuzzily matches this string / any of these strings."},"not_has_education":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose education fuzzily matches this string / any of these strings."},"not_has_description":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose description fuzzily matches this string / any of these strings."},"not_has_linkedin_companies":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose LinkedIn companies text fuzzily matches this string / any of these strings."},"not_has_linkedin_education":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose LinkedIn education text fuzzily matches this string / any of these strings."},"has_linkedin_last_message_at":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false}],"description":"LinkedIn last-message time: a boolean for presence/absence, or a `{ gte?, lte? }` ISO 8601 range."},"has_last_seen_at":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false}],"description":"Last-seen (last interaction) time — alias for has_interaction: a boolean for presence/absence, or a `{ gte?, lte? }` ISO 8601 range."},"has_distance":{"type":"object","properties":{"lat":{"type":"number"},"lon":{"type":"number"},"meters":{"type":"number"},"label":{"type":"string"}},"required":["lat","lon","meters"],"additionalProperties":false,"description":"Geo radius filter: contacts within `meters` of `{ lat, lon }` (PostGIS ST_DWithin on geocoded coordinates). `label` is an optional display name for the point."},"has_interaction":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false}],"description":"Interaction (last-seen) time: a boolean for presence/absence, or a `{ gte?, lte? }` ISO 8601 range."},"has_next_reminder":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false}],"description":"Next-reminder time: a boolean for presence/absence, or a `{ gte?, lte? }` ISO 8601 range."},"custom_fields":{"minItems":1,"type":"array","items":{"type":"object","properties":{"field_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"operator":{"type":"string","enum":["contains","eq","in","not_in","present","absent","gte","lte"]},"value":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},"required":["field_id","operator"],"additionalProperties":false},"description":"User-defined custom-field filters. Each clause is `{ field_id, operator, value? }`; multiple clauses AND together. Operators: contains, eq, in, not_in, present, absent, gte, lte."},"_or":{"description":"Compound-OR escape hatch: an array of filter branches combined with OR, each ANDed with the top-level keys. One level deep — branches cannot themselves contain `_or`.","minItems":1,"type":"array","items":{"type":"object","properties":{"in":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"description":"Match contacts whose id is in this set (single id or array)."},"not_in":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"description":"Exclude contacts whose id is in this set (single id or array)."},"ignore_merge":{"type":"boolean","description":"Filter by the `ignore_merge` flag (excluded from merge suggestions)."},"is_starred":{"type":"boolean","description":"Match starred (true) or non-starred (false) contacts."},"is_archived":{"type":"boolean","description":"Match archived (true) or active (false) contacts. Defaults to false when omitted."},"has_priority_tier":{"anyOf":[{"type":"integer","minimum":1,"maximum":9007199254740991},{"type":"array","items":{"type":"integer","minimum":1,"maximum":9007199254740991}},{"type":"boolean"}],"description":"Relationship priority tier: a tier number, an array of tiers (OR), or a boolean (true = any tier set, false = none)."},"has_linkedin":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"LinkedIn slug: an exact slug string, or a boolean for presence/absence of a LinkedIn handle."},"has_instagram":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"Instagram slug: an exact slug string, or a boolean for presence/absence of an Instagram handle."},"has_twitter":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"Twitter/X slug: an exact slug string, or a boolean for presence/absence of a Twitter handle."},"has_source":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Contact source: a single source string or an array of sources (OR)."},"has_name":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Full name: a bare string (fuzzy contains), an array of exact names, or `{ contains }` / `{ eq }` for explicit fuzzy vs exact match."},"has_groups":{"anyOf":[{"type":"object","properties":{"not":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},"required":["not"],"additionalProperties":false},{"type":"boolean"},{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"array","items":{"type":"string"}}],"description":"Group membership: a group id, an array of group ids (OR), a boolean for any/no group, or `{ not }` to exclude group id(s)."},"has_user_created_groups":{"type":"boolean","description":"Non-system group membership: true for at least one user-created group; false for no user-created groups, including contacts with zero memberships or only Dex system-group memberships."},"has_grouping_signal":{"type":"boolean","description":"Internal organize prefilter: title, company, location, or LinkedIn summary is non-null and non-empty. Whitespace-only values are removed by the organize serializer.","enum":[true]},"has_groups_all":{"description":"Array of group-id rows: AND across rows, OR within each row (contact must be in at least one group from every row).","type":"array","items":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"has_frequency":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"Keep-in-touch cadence: a frequency string, or a boolean for presence/absence of a cadence."},"has_location":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"Location: a string (fuzzy, accent-insensitive match), or a boolean for presence/absence of a location."},"has_location_exact":{"type":"string","description":"Location: exact string match (not fuzzy)."},"has_job_title":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Job title: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }` for explicit fuzzy vs exact match."},"has_never_keep_in_touch":{"type":"boolean","description":"Filter by the `never_keep_in_touch` flag."},"has_created_at":{"description":"Creation-date range: `{ gte?, lte? }` ISO 8601 datetimes (at least one bound required).","type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false},"has_updated_at":{"description":"Last-updated-date range: `{ gte?, lte? }` ISO 8601 datetimes (at least one bound required).","type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false},"has_birthday":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{},{"type":"boolean"}],"description":"Birthday: a specific date (matches on day + month), or true for any birthday set."},"has_tag":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Match contacts carrying this single tag id."},"has_tags":{"anyOf":[{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"type":"object","properties":{"not":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}]}},"required":["not"],"additionalProperties":false}],"description":"Tags: an array of tag ids (OR), or `{ not }` to exclude tag id(s)."},"has_tags_all":{"description":"Array of tag-id rows: AND across rows, OR within each row (contact must carry at least one tag from every row).","type":"array","items":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"has_company":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Company: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }` for explicit fuzzy vs exact match."},"has_education":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Education: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }`."},"has_description":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Description/notes: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }`."},"has_linkedin_companies":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"LinkedIn companies text: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }`."},"has_linkedin_education":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"LinkedIn education text: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }`."},"has_email":{"type":"boolean","description":"Match contacts that have (true) or lack (false) at least one email."},"has_phone_number":{"type":"boolean","description":"Match contacts that have (true) or lack (false) at least one phone number."},"not_has_name":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose full name fuzzily matches this string / any of these strings."},"not_has_company":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose company fuzzily matches this string / any of these strings."},"not_has_job_title":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose job title fuzzily matches this string / any of these strings."},"not_has_education":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose education fuzzily matches this string / any of these strings."},"not_has_description":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose description fuzzily matches this string / any of these strings."},"not_has_linkedin_companies":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose LinkedIn companies text fuzzily matches this string / any of these strings."},"not_has_linkedin_education":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose LinkedIn education text fuzzily matches this string / any of these strings."},"has_linkedin_last_message_at":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false}],"description":"LinkedIn last-message time: a boolean for presence/absence, or a `{ gte?, lte? }` ISO 8601 range."},"has_last_seen_at":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false}],"description":"Last-seen (last interaction) time — alias for has_interaction: a boolean for presence/absence, or a `{ gte?, lte? }` ISO 8601 range."},"has_distance":{"type":"object","properties":{"lat":{"type":"number"},"lon":{"type":"number"},"meters":{"type":"number"},"label":{"type":"string"}},"required":["lat","lon","meters"],"additionalProperties":false,"description":"Geo radius filter: contacts within `meters` of `{ lat, lon }` (PostGIS ST_DWithin on geocoded coordinates). `label` is an optional display name for the point."},"has_interaction":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false}],"description":"Interaction (last-seen) time: a boolean for presence/absence, or a `{ gte?, lte? }` ISO 8601 range."},"has_next_reminder":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false}],"description":"Next-reminder time: a boolean for presence/absence, or a `{ gte?, lte? }` ISO 8601 range."},"custom_fields":{"minItems":1,"type":"array","items":{"type":"object","properties":{"field_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"operator":{"type":"string","enum":["contains","eq","in","not_in","present","absent","gte","lte"]},"value":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},"required":["field_id","operator"],"additionalProperties":false},"description":"User-defined custom-field filters. Each clause is `{ field_id, operator, value? }`; multiple clauses AND together. Operators: contains, eq, in, not_in, present, absent, gte, lte."}},"additionalProperties":false}}},"additionalProperties":false},"in":"query","name":"where","required":false},{"schema":{},"in":"query","name":"orderBy","required":false},{"schema":{"type":"object","properties":{"linkedin_data":{"type":"boolean"},"groups_count":{"type":"boolean"},"coordinates":{"type":"boolean"}},"additionalProperties":{"type":"boolean"}},"in":"query","name":"include","required":false},{"schema":{"type":"object","properties":{"linkedin_data":{"type":"boolean"},"groups_count":{"type":"boolean"},"coordinates":{"type":"boolean"}},"additionalProperties":{"type":"boolean"}},"in":"query","name":"select","required":false}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"contacts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"first_name":{"nullable":true,"type":"string"},"last_name":{"nullable":true,"type":"string"},"full_name":{"nullable":true,"type":"string"},"description":{"nullable":true,"type":"string"},"job_title":{"nullable":true,"type":"string"},"company":{"nullable":true,"type":"string"},"education":{"nullable":true,"type":"string"},"legacy_location":{"nullable":true,"type":"string"},"image_url":{"nullable":true,"type":"string"},"business_card_url":{"nullable":true,"type":"string"},"website":{"nullable":true,"type":"string"},"image_source":{"nullable":true,"type":"string"},"birthday":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"birthday_year":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"linkedin":{"nullable":true,"type":"string"},"twitter":{"nullable":true,"type":"string"},"facebook":{"nullable":true,"type":"string"},"instagram":{"nullable":true,"type":"string"},"telegram":{"nullable":true,"type":"string"},"tiktok":{"nullable":true,"type":"string"},"youtube":{"nullable":true,"type":"string"},"starred":{"type":"boolean"},"is_archived":{"type":"boolean"},"ignore_merge":{"type":"boolean"},"never_keep_in_touch":{"type":"boolean"},"source":{"type":"string"},"priority_tier":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"frequency":{"nullable":true,"type":"string"},"frequency_text":{"nullable":true,"type":"string"},"last_seen_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"last_reminder_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"next_reminder_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"first_met_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"first_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_companies":{"nullable":true,"type":"string"},"linkedin_education":{"nullable":true,"type":"string"},"linkedin_enhance_date":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_last_message_snippet":{"nullable":true,"type":"string"},"linkedin_message_link":{"nullable":true,"type":"string"},"whatsapp_message_link":{"nullable":true,"type":"string"},"whatsapp_message_snippet":{"nullable":true,"type":"string"},"whatsapp_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"imessage_message_link":{"nullable":true,"type":"string"},"imessage_message_snippet":{"nullable":true,"type":"string"},"imessage_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"instagram_message_link":{"nullable":true,"type":"string"},"instagram_message_snippet":{"nullable":true,"type":"string"},"instagram_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"gmail_last_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"gmail_last_interaction_provider":{"nullable":true,"type":"string","enum":["GOOGLE","OFFICE365"]},"gmail_last_interaction_provider_id":{"nullable":true,"type":"string"},"gmail_last_interaction_subject":{"nullable":true,"type":"string"},"gcal_last_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"gcal_last_interaction_provider":{"nullable":true,"type":"string","enum":["GOOGLE","OFFICE365"]},"gcal_last_interaction_provider_id":{"nullable":true,"type":"string"},"gcal_last_interaction_title":{"nullable":true,"type":"string"},"phone_call_interaction_snippet":{"nullable":true,"type":"string"},"phone_call_last_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"web_search_summary":{"nullable":true},"created_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"updated_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"geocode_attempts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"geocode_failed_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"_count":{"type":"object","properties":{"groups_contacts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["groups_contacts"],"additionalProperties":false},"frequency_interval":{},"linkedin_data":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"latitude":{"nullable":true,"type":"number"},"longitude":{"nullable":true,"type":"number"},"contact_emails":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_phone_numbers":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_birthdays":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"contact_locations":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contacts_custom_fields":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"legacy_contact_addresses":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"groups_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"tags_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"timeline_items_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"reminders_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_relations_contact_relations_sourceTocontacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_relations_contact_relations_destinationTocontacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"feed_items":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"keep_in_touch_reminders":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}}},"required":["id"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"nextCursor":{"nullable":true,"type":"string"},"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"additionalProperties":false}},"required":["contacts"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"listContactsV2","summary":"List contacts (v2)","description":"Retrieve contacts for the authenticated user with cursor pagination, filtering (`where`), sorting (`orderBy`), and field selection (`include` / `select`). Returns `{ data: { contacts: [...], pagination: { nextCursor, count } } }`.","x-mint":{"content":"## Use cases\n\n- Render the main contacts list with infinite scroll\n- Power filtered views (recent, favorites, by tag, by group)\n- Hydrate a TanStack DB collection on initial load\n\n## Migration from /v1\n\n/v1 list response: `{ data: { items: [...], nextCursor, count } }`.\n/v2 list response: `{ data: { contacts: [...], pagination: { nextCursor, count } } }` — entity plural at the top level, pagination namespaced.\n\nFor very large `where` payloads that exceed URL length limits, use `POST /v2/contacts/filter` instead. Same response shape."}},"post":{"tags":["contacts"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"full_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"first_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"job_title":{"anyOf":[{"type":"string"},{"type":"null"}]},"legacy_location":{"anyOf":[{"type":"string"},{"type":"null"}]},"company":{"anyOf":[{"type":"string"},{"type":"null"}]},"education":{"anyOf":[{"type":"string"},{"type":"null"}]},"starred":{"type":"boolean"},"source":{"type":"string","enum":["linkedin_sync","facebook_import","cal_ingest","email_ingest","web_import","csv_import","whatsapp_sync","imessage_sync","phone_calls_sync","mobile","mobile_import","instagram_sync","oauth_interaction"]},"coordinates":{"type":"object","properties":{"operation":{"type":"string","enum":["set","delete"]},"data":{"type":"object","properties":{"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180}},"additionalProperties":false}},"required":["operation"],"additionalProperties":false},"priority_tier":{"anyOf":[{"type":"integer","minimum":1,"maximum":32767},{"type":"null"}]},"image_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"image_source":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"business_card_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"website":{"anyOf":[{},{"type":"null"}]},"birthday":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"birthday_year":{"anyOf":[{"type":"number","minimum":1900,"maximum":2100},{"type":"null"}]},"frequency":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_seen_at":{"anyOf":[{},{"type":"null"}]},"first_met_at":{"anyOf":[{},{"type":"null"}]},"never_keep_in_touch":{"type":"boolean"},"next_reminder_at":{},"linkedin":{"anyOf":[{"type":"string"},{"type":"null"}]},"twitter":{"anyOf":[{"type":"string"},{"type":"null"}]},"facebook":{"anyOf":[{"type":"string"},{"type":"null"}]},"instagram":{"anyOf":[{"type":"string"},{"type":"null"}]},"telegram":{"anyOf":[{"type":"string"},{"type":"null"}]},"tiktok":{"anyOf":[{"type":"string"},{"type":"null"}]},"youtube":{"anyOf":[{"type":"string"},{"type":"null"}]},"whatsapp_message_link":{"type":"string"},"whatsapp_message_snippet":{"anyOf":[{"type":"string"},{"type":"null"}]},"whatsapp_last_message_at":{"anyOf":[{},{"type":"null"}]},"imessage_message_link":{"type":"string"},"imessage_message_snippet":{"anyOf":[{"type":"string"},{"type":"null"}]},"imessage_last_message_at":{"anyOf":[{},{"type":"null"}]},"linkedin_message_link":{"type":"string","maxLength":600},"linkedin_last_message_snippet":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"linkedin_last_message_at":{"anyOf":[{},{"type":"null"}]},"linkedin_data":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"instagram_message_link":{"type":"string"},"instagram_message_snippet":{"anyOf":[{"type":"string"},{"type":"null"}]},"instagram_last_message_at":{"anyOf":[{},{"type":"null"}]},"gmail_last_interaction_at":{"anyOf":[{},{"type":"null"}]},"gmail_last_interaction_provider_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"gmail_last_interaction_subject":{"anyOf":[{"type":"string"},{"type":"null"}]},"gmail_last_interaction_provider":{"anyOf":[{"type":"string","enum":["GOOGLE","OFFICE365"]},{"type":"null"}]},"gcal_last_interaction_at":{"anyOf":[{},{"type":"null"}]},"gcal_last_interaction_provider_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"gcal_last_interaction_title":{"anyOf":[{"type":"string"},{"type":"null"}]},"gcal_last_interaction_provider":{"anyOf":[{"type":"string","enum":["GOOGLE","OFFICE365"]},{"type":"null"}]},"phone_call_last_interaction_at":{"anyOf":[{},{"type":"null"}]},"phone_call_interaction_snippet":{"anyOf":[{"type":"string"},{"type":"null"}]},"web_search_summary":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"legacy_contact_addresses":{"type":"array","items":{"type":"object","properties":{"formatted":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false}},"contact_emails":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string","maxLength":320},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"ranking":{"type":"number"}},"required":["email"],"additionalProperties":false}},"contact_phone_numbers":{"type":"array","items":{"type":"object","properties":{"phone_number":{"type":"string","maxLength":50},"country_code":{"anyOf":[{"type":"string","maxLength":4},{"type":"null"}]},"phone_number_sanitized":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"ranking":{"type":"number"}},"required":["phone_number"],"additionalProperties":false}},"groups_contacts":{"type":"array","items":{"type":"object","properties":{"group_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["group_id"],"additionalProperties":false}},"tags_contacts":{"type":"array","items":{"type":"object","properties":{"tag_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["tag_id"],"additionalProperties":false}},"custom_fields":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"type":{"type":"string","enum":["input"]},"text_value":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}]},"custom_field":{}},"required":["id","type","text_value"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"type":{"type":"string","enum":["autocomplete"]},"text_value":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}]},"custom_field":{}},"required":["id","type","text_value"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"type":{"type":"string","enum":["datepicker"]},"text_value":{"anyOf":[{"type":"string"},{"type":"null"}]},"date_value":{"anyOf":[{},{"type":"null"}]},"custom_field":{}},"required":["id","type"],"additionalProperties":false}]}},"contact_birthdays":{"type":"object","properties":{"contact_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"last_dismissal_year":{"type":"number","minimum":1900,"maximum":2100}},"additionalProperties":false},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"related_contacts":{"type":"array","items":{"type":"object","properties":{"destination":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"source_contact":{},"destination_contact":{}},"required":["destination"],"additionalProperties":false}}},"additionalProperties":false}}}},"responses":{"201":{"description":"Created","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"contact":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"first_name":{"nullable":true,"type":"string"},"last_name":{"nullable":true,"type":"string"},"full_name":{"nullable":true,"type":"string"},"description":{"nullable":true,"type":"string"},"job_title":{"nullable":true,"type":"string"},"company":{"nullable":true,"type":"string"},"education":{"nullable":true,"type":"string"},"legacy_location":{"nullable":true,"type":"string"},"image_url":{"nullable":true,"type":"string"},"business_card_url":{"nullable":true,"type":"string"},"website":{"nullable":true,"type":"string"},"image_source":{"nullable":true,"type":"string"},"birthday":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"birthday_year":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"linkedin":{"nullable":true,"type":"string"},"twitter":{"nullable":true,"type":"string"},"facebook":{"nullable":true,"type":"string"},"instagram":{"nullable":true,"type":"string"},"telegram":{"nullable":true,"type":"string"},"tiktok":{"nullable":true,"type":"string"},"youtube":{"nullable":true,"type":"string"},"starred":{"type":"boolean"},"is_archived":{"type":"boolean"},"ignore_merge":{"type":"boolean"},"never_keep_in_touch":{"type":"boolean"},"source":{"type":"string"},"priority_tier":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"frequency":{"nullable":true,"type":"string"},"frequency_text":{"nullable":true,"type":"string"},"last_seen_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"last_reminder_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"next_reminder_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"first_met_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"first_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_companies":{"nullable":true,"type":"string"},"linkedin_education":{"nullable":true,"type":"string"},"linkedin_enhance_date":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_last_message_snippet":{"nullable":true,"type":"string"},"linkedin_message_link":{"nullable":true,"type":"string"},"whatsapp_message_link":{"nullable":true,"type":"string"},"whatsapp_message_snippet":{"nullable":true,"type":"string"},"whatsapp_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"imessage_message_link":{"nullable":true,"type":"string"},"imessage_message_snippet":{"nullable":true,"type":"string"},"imessage_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"instagram_message_link":{"nullable":true,"type":"string"},"instagram_message_snippet":{"nullable":true,"type":"string"},"instagram_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"gmail_last_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"gmail_last_interaction_provider":{"nullable":true,"type":"string","enum":["GOOGLE","OFFICE365"]},"gmail_last_interaction_provider_id":{"nullable":true,"type":"string"},"gmail_last_interaction_subject":{"nullable":true,"type":"string"},"gcal_last_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"gcal_last_interaction_provider":{"nullable":true,"type":"string","enum":["GOOGLE","OFFICE365"]},"gcal_last_interaction_provider_id":{"nullable":true,"type":"string"},"gcal_last_interaction_title":{"nullable":true,"type":"string"},"phone_call_interaction_snippet":{"nullable":true,"type":"string"},"phone_call_last_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"web_search_summary":{"nullable":true},"created_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"updated_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"geocode_attempts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"geocode_failed_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"_count":{"type":"object","properties":{"groups_contacts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["groups_contacts"],"additionalProperties":false},"frequency_interval":{},"linkedin_data":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"latitude":{"nullable":true,"type":"number"},"longitude":{"nullable":true,"type":"number"},"contact_emails":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_phone_numbers":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_birthdays":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"contact_locations":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contacts_custom_fields":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"legacy_contact_addresses":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"groups_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"tags_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"timeline_items_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"reminders_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_relations_contact_relations_sourceTocontacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_relations_contact_relations_destinationTocontacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"feed_items":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"keep_in_touch_reminders":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}}},"required":["id"],"additionalProperties":false}},"required":["contact"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"createContactV2","summary":"Create a contact (v2)","description":"Create ONE contact. The common case — TanStack DB optimistic mutations, mobile add-contact, MCP tools. **Requires `Idempotency-Key`.** Returns `{ data: { contact: {...} } }` with status 201. For bulk create, use `POST /v2/contacts/batch`.","x-mint":{"content":"## Use cases\n\n- Add a contact from a profile page\n- Create from social lookup or LinkedIn enrichment\n- MCP `create_contact` tool\n\n## Migration from /v1\n\n/v1 only had `POST /v1/contacts/` which always took an array of contacts. /v2 splits this: `POST /v2/contacts` for ONE contact (the common case), `POST /v2/contacts/batch` for many. Less awkward call sites for the single-contact create path.\n\n## Idempotency\n\nGenerate one UUID per logical create operation and reuse it on every retry. TanStack DB collections pass `mutationId` directly."},"parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","minLength":8,"maxLength":255,"pattern":"^[\\w\\-:.]+$","example":"01HV8N6X7K3P9Q5R2T4Y6W8Z0A"},"description":"Required. UUID per logical operation, reused on every retry. See `apps/rest-api/src/shared/idempotency.ts` for the full contract. Missing → 400 BadRequest; same key + different body → 409 Conflict."}]}},"/v2/contacts/count":{"get":{"tags":["contacts"],"parameters":[{"schema":{"type":"object","properties":{"in":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"description":"Match contacts whose id is in this set (single id or array)."},"not_in":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"description":"Exclude contacts whose id is in this set (single id or array)."},"ignore_merge":{"type":"boolean","description":"Filter by the `ignore_merge` flag (excluded from merge suggestions)."},"is_starred":{"type":"boolean","description":"Match starred (true) or non-starred (false) contacts."},"is_archived":{"type":"boolean","description":"Match archived (true) or active (false) contacts. Defaults to false when omitted."},"has_priority_tier":{"anyOf":[{"type":"integer","minimum":1,"maximum":9007199254740991},{"type":"array","items":{"type":"integer","minimum":1,"maximum":9007199254740991}},{"type":"boolean"}],"description":"Relationship priority tier: a tier number, an array of tiers (OR), or a boolean (true = any tier set, false = none)."},"has_linkedin":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"LinkedIn slug: an exact slug string, or a boolean for presence/absence of a LinkedIn handle."},"has_instagram":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"Instagram slug: an exact slug string, or a boolean for presence/absence of an Instagram handle."},"has_twitter":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"Twitter/X slug: an exact slug string, or a boolean for presence/absence of a Twitter handle."},"has_source":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Contact source: a single source string or an array of sources (OR)."},"has_name":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Full name: a bare string (fuzzy contains), an array of exact names, or `{ contains }` / `{ eq }` for explicit fuzzy vs exact match."},"has_groups":{"anyOf":[{"type":"object","properties":{"not":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},"required":["not"],"additionalProperties":false},{"type":"boolean"},{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"array","items":{"type":"string"}}],"description":"Group membership: a group id, an array of group ids (OR), a boolean for any/no group, or `{ not }` to exclude group id(s)."},"has_user_created_groups":{"type":"boolean","description":"Non-system group membership: true for at least one user-created group; false for no user-created groups, including contacts with zero memberships or only Dex system-group memberships."},"has_grouping_signal":{"type":"boolean","description":"Internal organize prefilter: title, company, location, or LinkedIn summary is non-null and non-empty. Whitespace-only values are removed by the organize serializer.","enum":[true]},"has_groups_all":{"description":"Array of group-id rows: AND across rows, OR within each row (contact must be in at least one group from every row).","type":"array","items":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"has_frequency":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"Keep-in-touch cadence: a frequency string, or a boolean for presence/absence of a cadence."},"has_location":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"Location: a string (fuzzy, accent-insensitive match), or a boolean for presence/absence of a location."},"has_location_exact":{"type":"string","description":"Location: exact string match (not fuzzy)."},"has_job_title":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Job title: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }` for explicit fuzzy vs exact match."},"has_never_keep_in_touch":{"type":"boolean","description":"Filter by the `never_keep_in_touch` flag."},"has_created_at":{"description":"Creation-date range: `{ gte?, lte? }` ISO 8601 datetimes (at least one bound required).","type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false},"has_updated_at":{"description":"Last-updated-date range: `{ gte?, lte? }` ISO 8601 datetimes (at least one bound required).","type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false},"has_birthday":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{},{"type":"boolean"}],"description":"Birthday: a specific date (matches on day + month), or true for any birthday set."},"has_tag":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Match contacts carrying this single tag id."},"has_tags":{"anyOf":[{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"type":"object","properties":{"not":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}]}},"required":["not"],"additionalProperties":false}],"description":"Tags: an array of tag ids (OR), or `{ not }` to exclude tag id(s)."},"has_tags_all":{"description":"Array of tag-id rows: AND across rows, OR within each row (contact must carry at least one tag from every row).","type":"array","items":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"has_company":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Company: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }` for explicit fuzzy vs exact match."},"has_education":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Education: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }`."},"has_description":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Description/notes: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }`."},"has_linkedin_companies":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"LinkedIn companies text: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }`."},"has_linkedin_education":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"LinkedIn education text: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }`."},"has_email":{"type":"boolean","description":"Match contacts that have (true) or lack (false) at least one email."},"has_phone_number":{"type":"boolean","description":"Match contacts that have (true) or lack (false) at least one phone number."},"not_has_name":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose full name fuzzily matches this string / any of these strings."},"not_has_company":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose company fuzzily matches this string / any of these strings."},"not_has_job_title":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose job title fuzzily matches this string / any of these strings."},"not_has_education":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose education fuzzily matches this string / any of these strings."},"not_has_description":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose description fuzzily matches this string / any of these strings."},"not_has_linkedin_companies":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose LinkedIn companies text fuzzily matches this string / any of these strings."},"not_has_linkedin_education":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose LinkedIn education text fuzzily matches this string / any of these strings."},"has_linkedin_last_message_at":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false}],"description":"LinkedIn last-message time: a boolean for presence/absence, or a `{ gte?, lte? }` ISO 8601 range."},"has_last_seen_at":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false}],"description":"Last-seen (last interaction) time — alias for has_interaction: a boolean for presence/absence, or a `{ gte?, lte? }` ISO 8601 range."},"has_distance":{"type":"object","properties":{"lat":{"type":"number"},"lon":{"type":"number"},"meters":{"type":"number"},"label":{"type":"string"}},"required":["lat","lon","meters"],"additionalProperties":false,"description":"Geo radius filter: contacts within `meters` of `{ lat, lon }` (PostGIS ST_DWithin on geocoded coordinates). `label` is an optional display name for the point."},"has_interaction":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false}],"description":"Interaction (last-seen) time: a boolean for presence/absence, or a `{ gte?, lte? }` ISO 8601 range."},"has_next_reminder":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false}],"description":"Next-reminder time: a boolean for presence/absence, or a `{ gte?, lte? }` ISO 8601 range."},"custom_fields":{"minItems":1,"type":"array","items":{"type":"object","properties":{"field_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"operator":{"type":"string","enum":["contains","eq","in","not_in","present","absent","gte","lte"]},"value":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},"required":["field_id","operator"],"additionalProperties":false},"description":"User-defined custom-field filters. Each clause is `{ field_id, operator, value? }`; multiple clauses AND together. Operators: contains, eq, in, not_in, present, absent, gte, lte."},"_or":{"description":"Compound-OR escape hatch: an array of filter branches combined with OR, each ANDed with the top-level keys. One level deep — branches cannot themselves contain `_or`.","minItems":1,"type":"array","items":{"type":"object","properties":{"in":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"description":"Match contacts whose id is in this set (single id or array)."},"not_in":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"description":"Exclude contacts whose id is in this set (single id or array)."},"ignore_merge":{"type":"boolean","description":"Filter by the `ignore_merge` flag (excluded from merge suggestions)."},"is_starred":{"type":"boolean","description":"Match starred (true) or non-starred (false) contacts."},"is_archived":{"type":"boolean","description":"Match archived (true) or active (false) contacts. Defaults to false when omitted."},"has_priority_tier":{"anyOf":[{"type":"integer","minimum":1,"maximum":9007199254740991},{"type":"array","items":{"type":"integer","minimum":1,"maximum":9007199254740991}},{"type":"boolean"}],"description":"Relationship priority tier: a tier number, an array of tiers (OR), or a boolean (true = any tier set, false = none)."},"has_linkedin":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"LinkedIn slug: an exact slug string, or a boolean for presence/absence of a LinkedIn handle."},"has_instagram":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"Instagram slug: an exact slug string, or a boolean for presence/absence of an Instagram handle."},"has_twitter":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"Twitter/X slug: an exact slug string, or a boolean for presence/absence of a Twitter handle."},"has_source":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Contact source: a single source string or an array of sources (OR)."},"has_name":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Full name: a bare string (fuzzy contains), an array of exact names, or `{ contains }` / `{ eq }` for explicit fuzzy vs exact match."},"has_groups":{"anyOf":[{"type":"object","properties":{"not":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},"required":["not"],"additionalProperties":false},{"type":"boolean"},{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"array","items":{"type":"string"}}],"description":"Group membership: a group id, an array of group ids (OR), a boolean for any/no group, or `{ not }` to exclude group id(s)."},"has_user_created_groups":{"type":"boolean","description":"Non-system group membership: true for at least one user-created group; false for no user-created groups, including contacts with zero memberships or only Dex system-group memberships."},"has_grouping_signal":{"type":"boolean","description":"Internal organize prefilter: title, company, location, or LinkedIn summary is non-null and non-empty. Whitespace-only values are removed by the organize serializer.","enum":[true]},"has_groups_all":{"description":"Array of group-id rows: AND across rows, OR within each row (contact must be in at least one group from every row).","type":"array","items":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"has_frequency":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"Keep-in-touch cadence: a frequency string, or a boolean for presence/absence of a cadence."},"has_location":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"Location: a string (fuzzy, accent-insensitive match), or a boolean for presence/absence of a location."},"has_location_exact":{"type":"string","description":"Location: exact string match (not fuzzy)."},"has_job_title":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Job title: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }` for explicit fuzzy vs exact match."},"has_never_keep_in_touch":{"type":"boolean","description":"Filter by the `never_keep_in_touch` flag."},"has_created_at":{"description":"Creation-date range: `{ gte?, lte? }` ISO 8601 datetimes (at least one bound required).","type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false},"has_updated_at":{"description":"Last-updated-date range: `{ gte?, lte? }` ISO 8601 datetimes (at least one bound required).","type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false},"has_birthday":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{},{"type":"boolean"}],"description":"Birthday: a specific date (matches on day + month), or true for any birthday set."},"has_tag":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Match contacts carrying this single tag id."},"has_tags":{"anyOf":[{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"type":"object","properties":{"not":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}]}},"required":["not"],"additionalProperties":false}],"description":"Tags: an array of tag ids (OR), or `{ not }` to exclude tag id(s)."},"has_tags_all":{"description":"Array of tag-id rows: AND across rows, OR within each row (contact must carry at least one tag from every row).","type":"array","items":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"has_company":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Company: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }` for explicit fuzzy vs exact match."},"has_education":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Education: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }`."},"has_description":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Description/notes: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }`."},"has_linkedin_companies":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"LinkedIn companies text: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }`."},"has_linkedin_education":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"LinkedIn education text: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }`."},"has_email":{"type":"boolean","description":"Match contacts that have (true) or lack (false) at least one email."},"has_phone_number":{"type":"boolean","description":"Match contacts that have (true) or lack (false) at least one phone number."},"not_has_name":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose full name fuzzily matches this string / any of these strings."},"not_has_company":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose company fuzzily matches this string / any of these strings."},"not_has_job_title":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose job title fuzzily matches this string / any of these strings."},"not_has_education":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose education fuzzily matches this string / any of these strings."},"not_has_description":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose description fuzzily matches this string / any of these strings."},"not_has_linkedin_companies":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose LinkedIn companies text fuzzily matches this string / any of these strings."},"not_has_linkedin_education":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose LinkedIn education text fuzzily matches this string / any of these strings."},"has_linkedin_last_message_at":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false}],"description":"LinkedIn last-message time: a boolean for presence/absence, or a `{ gte?, lte? }` ISO 8601 range."},"has_last_seen_at":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false}],"description":"Last-seen (last interaction) time — alias for has_interaction: a boolean for presence/absence, or a `{ gte?, lte? }` ISO 8601 range."},"has_distance":{"type":"object","properties":{"lat":{"type":"number"},"lon":{"type":"number"},"meters":{"type":"number"},"label":{"type":"string"}},"required":["lat","lon","meters"],"additionalProperties":false,"description":"Geo radius filter: contacts within `meters` of `{ lat, lon }` (PostGIS ST_DWithin on geocoded coordinates). `label` is an optional display name for the point."},"has_interaction":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false}],"description":"Interaction (last-seen) time: a boolean for presence/absence, or a `{ gte?, lte? }` ISO 8601 range."},"has_next_reminder":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false}],"description":"Next-reminder time: a boolean for presence/absence, or a `{ gte?, lte? }` ISO 8601 range."},"custom_fields":{"minItems":1,"type":"array","items":{"type":"object","properties":{"field_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"operator":{"type":"string","enum":["contains","eq","in","not_in","present","absent","gte","lte"]},"value":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},"required":["field_id","operator"],"additionalProperties":false},"description":"User-defined custom-field filters. Each clause is `{ field_id, operator, value? }`; multiple clauses AND together. Operators: contains, eq, in, not_in, present, absent, gte, lte."}},"additionalProperties":false}}},"additionalProperties":false},"in":"query","name":"where","required":false}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["count"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"countContactsV2","summary":"Count contacts (v2)","description":"Return the count of contacts matching the optional `where` filter. Returns `{ data: { count } }`.","x-mint":{"content":"## Use cases\n\n- Display total contact count in the UI\n- Power \"X contacts\" labels on filtered views\n- Show filter-result counts before fetching the list"}}},"/v2/contacts/filter":{"post":{"tags":["contacts"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"take":{"type":"integer","minimum":1,"maximum":9007199254740991},"skip":{"type":"integer","minimum":0,"maximum":9007199254740991},"cursor":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"where":{"type":"object","properties":{"in":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"description":"Match contacts whose id is in this set (single id or array)."},"not_in":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"description":"Exclude contacts whose id is in this set (single id or array)."},"ignore_merge":{"type":"boolean","description":"Filter by the `ignore_merge` flag (excluded from merge suggestions)."},"is_starred":{"type":"boolean","description":"Match starred (true) or non-starred (false) contacts."},"is_archived":{"type":"boolean","description":"Match archived (true) or active (false) contacts. Defaults to false when omitted."},"has_priority_tier":{"anyOf":[{"type":"integer","minimum":1,"maximum":9007199254740991},{"type":"array","items":{"type":"integer","minimum":1,"maximum":9007199254740991}},{"type":"boolean"}],"description":"Relationship priority tier: a tier number, an array of tiers (OR), or a boolean (true = any tier set, false = none)."},"has_linkedin":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"LinkedIn slug: an exact slug string, or a boolean for presence/absence of a LinkedIn handle."},"has_instagram":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"Instagram slug: an exact slug string, or a boolean for presence/absence of an Instagram handle."},"has_twitter":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"Twitter/X slug: an exact slug string, or a boolean for presence/absence of a Twitter handle."},"has_source":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Contact source: a single source string or an array of sources (OR)."},"has_name":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Full name: a bare string (fuzzy contains), an array of exact names, or `{ contains }` / `{ eq }` for explicit fuzzy vs exact match."},"has_groups":{"anyOf":[{"type":"object","properties":{"not":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},"required":["not"],"additionalProperties":false},{"type":"boolean"},{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"array","items":{"type":"string"}}],"description":"Group membership: a group id, an array of group ids (OR), a boolean for any/no group, or `{ not }` to exclude group id(s)."},"has_user_created_groups":{"type":"boolean","description":"Non-system group membership: true for at least one user-created group; false for no user-created groups, including contacts with zero memberships or only Dex system-group memberships."},"has_grouping_signal":{"type":"boolean","description":"Internal organize prefilter: title, company, location, or LinkedIn summary is non-null and non-empty. Whitespace-only values are removed by the organize serializer.","enum":[true]},"has_groups_all":{"description":"Array of group-id rows: AND across rows, OR within each row (contact must be in at least one group from every row).","type":"array","items":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"has_frequency":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"Keep-in-touch cadence: a frequency string, or a boolean for presence/absence of a cadence."},"has_location":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"Location: a string (fuzzy, accent-insensitive match), or a boolean for presence/absence of a location."},"has_location_exact":{"type":"string","description":"Location: exact string match (not fuzzy)."},"has_job_title":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Job title: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }` for explicit fuzzy vs exact match."},"has_never_keep_in_touch":{"type":"boolean","description":"Filter by the `never_keep_in_touch` flag."},"has_created_at":{"description":"Creation-date range: `{ gte?, lte? }` ISO 8601 datetimes (at least one bound required).","type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false},"has_updated_at":{"description":"Last-updated-date range: `{ gte?, lte? }` ISO 8601 datetimes (at least one bound required).","type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false},"has_birthday":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{},{"type":"boolean"}],"description":"Birthday: a specific date (matches on day + month), or true for any birthday set."},"has_tag":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Match contacts carrying this single tag id."},"has_tags":{"anyOf":[{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"type":"object","properties":{"not":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}]}},"required":["not"],"additionalProperties":false}],"description":"Tags: an array of tag ids (OR), or `{ not }` to exclude tag id(s)."},"has_tags_all":{"description":"Array of tag-id rows: AND across rows, OR within each row (contact must carry at least one tag from every row).","type":"array","items":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"has_company":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Company: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }` for explicit fuzzy vs exact match."},"has_education":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Education: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }`."},"has_description":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Description/notes: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }`."},"has_linkedin_companies":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"LinkedIn companies text: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }`."},"has_linkedin_education":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"LinkedIn education text: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }`."},"has_email":{"type":"boolean","description":"Match contacts that have (true) or lack (false) at least one email."},"has_phone_number":{"type":"boolean","description":"Match contacts that have (true) or lack (false) at least one phone number."},"not_has_name":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose full name fuzzily matches this string / any of these strings."},"not_has_company":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose company fuzzily matches this string / any of these strings."},"not_has_job_title":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose job title fuzzily matches this string / any of these strings."},"not_has_education":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose education fuzzily matches this string / any of these strings."},"not_has_description":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose description fuzzily matches this string / any of these strings."},"not_has_linkedin_companies":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose LinkedIn companies text fuzzily matches this string / any of these strings."},"not_has_linkedin_education":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose LinkedIn education text fuzzily matches this string / any of these strings."},"has_linkedin_last_message_at":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false}],"description":"LinkedIn last-message time: a boolean for presence/absence, or a `{ gte?, lte? }` ISO 8601 range."},"has_last_seen_at":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false}],"description":"Last-seen (last interaction) time — alias for has_interaction: a boolean for presence/absence, or a `{ gte?, lte? }` ISO 8601 range."},"has_distance":{"type":"object","properties":{"lat":{"type":"number"},"lon":{"type":"number"},"meters":{"type":"number"},"label":{"type":"string"}},"required":["lat","lon","meters"],"additionalProperties":false,"description":"Geo radius filter: contacts within `meters` of `{ lat, lon }` (PostGIS ST_DWithin on geocoded coordinates). `label` is an optional display name for the point."},"has_interaction":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false}],"description":"Interaction (last-seen) time: a boolean for presence/absence, or a `{ gte?, lte? }` ISO 8601 range."},"has_next_reminder":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false}],"description":"Next-reminder time: a boolean for presence/absence, or a `{ gte?, lte? }` ISO 8601 range."},"custom_fields":{"minItems":1,"type":"array","items":{"type":"object","properties":{"field_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"operator":{"type":"string","enum":["contains","eq","in","not_in","present","absent","gte","lte"]},"value":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},"required":["field_id","operator"],"additionalProperties":false},"description":"User-defined custom-field filters. Each clause is `{ field_id, operator, value? }`; multiple clauses AND together. Operators: contains, eq, in, not_in, present, absent, gte, lte."},"_or":{"description":"Compound-OR escape hatch: an array of filter branches combined with OR, each ANDed with the top-level keys. One level deep — branches cannot themselves contain `_or`.","minItems":1,"type":"array","items":{"type":"object","properties":{"in":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"description":"Match contacts whose id is in this set (single id or array)."},"not_in":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}],"description":"Exclude contacts whose id is in this set (single id or array)."},"ignore_merge":{"type":"boolean","description":"Filter by the `ignore_merge` flag (excluded from merge suggestions)."},"is_starred":{"type":"boolean","description":"Match starred (true) or non-starred (false) contacts."},"is_archived":{"type":"boolean","description":"Match archived (true) or active (false) contacts. Defaults to false when omitted."},"has_priority_tier":{"anyOf":[{"type":"integer","minimum":1,"maximum":9007199254740991},{"type":"array","items":{"type":"integer","minimum":1,"maximum":9007199254740991}},{"type":"boolean"}],"description":"Relationship priority tier: a tier number, an array of tiers (OR), or a boolean (true = any tier set, false = none)."},"has_linkedin":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"LinkedIn slug: an exact slug string, or a boolean for presence/absence of a LinkedIn handle."},"has_instagram":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"Instagram slug: an exact slug string, or a boolean for presence/absence of an Instagram handle."},"has_twitter":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"Twitter/X slug: an exact slug string, or a boolean for presence/absence of a Twitter handle."},"has_source":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Contact source: a single source string or an array of sources (OR)."},"has_name":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Full name: a bare string (fuzzy contains), an array of exact names, or `{ contains }` / `{ eq }` for explicit fuzzy vs exact match."},"has_groups":{"anyOf":[{"type":"object","properties":{"not":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},"required":["not"],"additionalProperties":false},{"type":"boolean"},{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"array","items":{"type":"string"}}],"description":"Group membership: a group id, an array of group ids (OR), a boolean for any/no group, or `{ not }` to exclude group id(s)."},"has_user_created_groups":{"type":"boolean","description":"Non-system group membership: true for at least one user-created group; false for no user-created groups, including contacts with zero memberships or only Dex system-group memberships."},"has_grouping_signal":{"type":"boolean","description":"Internal organize prefilter: title, company, location, or LinkedIn summary is non-null and non-empty. Whitespace-only values are removed by the organize serializer.","enum":[true]},"has_groups_all":{"description":"Array of group-id rows: AND across rows, OR within each row (contact must be in at least one group from every row).","type":"array","items":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"has_frequency":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"Keep-in-touch cadence: a frequency string, or a boolean for presence/absence of a cadence."},"has_location":{"anyOf":[{"type":"string"},{"type":"boolean"}],"description":"Location: a string (fuzzy, accent-insensitive match), or a boolean for presence/absence of a location."},"has_location_exact":{"type":"string","description":"Location: exact string match (not fuzzy)."},"has_job_title":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Job title: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }` for explicit fuzzy vs exact match."},"has_never_keep_in_touch":{"type":"boolean","description":"Filter by the `never_keep_in_touch` flag."},"has_created_at":{"description":"Creation-date range: `{ gte?, lte? }` ISO 8601 datetimes (at least one bound required).","type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false},"has_updated_at":{"description":"Last-updated-date range: `{ gte?, lte? }` ISO 8601 datetimes (at least one bound required).","type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false},"has_birthday":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},{},{"type":"boolean"}],"description":"Birthday: a specific date (matches on day + month), or true for any birthday set."},"has_tag":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Match contacts carrying this single tag id."},"has_tags":{"anyOf":[{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},{"type":"object","properties":{"not":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}]}},"required":["not"],"additionalProperties":false}],"description":"Tags: an array of tag ids (OR), or `{ not }` to exclude tag id(s)."},"has_tags_all":{"description":"Array of tag-id rows: AND across rows, OR within each row (contact must carry at least one tag from every row).","type":"array","items":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"has_company":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Company: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }` for explicit fuzzy vs exact match."},"has_education":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Education: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }`."},"has_description":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"Description/notes: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }`."},"has_linkedin_companies":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"LinkedIn companies text: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }`."},"has_linkedin_education":{"anyOf":[{"type":"string"},{"type":"boolean"},{"anyOf":[{"type":"object","properties":{"contains":{"type":"string","minLength":1}},"required":["contains"],"additionalProperties":false},{"type":"object","properties":{"eq":{"type":"string"}},"required":["eq"],"additionalProperties":false}]}],"description":"LinkedIn education text: a bare string (fuzzy contains), a boolean for presence/absence, or `{ contains }` / `{ eq }`."},"has_email":{"type":"boolean","description":"Match contacts that have (true) or lack (false) at least one email."},"has_phone_number":{"type":"boolean","description":"Match contacts that have (true) or lack (false) at least one phone number."},"not_has_name":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose full name fuzzily matches this string / any of these strings."},"not_has_company":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose company fuzzily matches this string / any of these strings."},"not_has_job_title":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose job title fuzzily matches this string / any of these strings."},"not_has_education":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose education fuzzily matches this string / any of these strings."},"not_has_description":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose description fuzzily matches this string / any of these strings."},"not_has_linkedin_companies":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose LinkedIn companies text fuzzily matches this string / any of these strings."},"not_has_linkedin_education":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Exclude contacts whose LinkedIn education text fuzzily matches this string / any of these strings."},"has_linkedin_last_message_at":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false}],"description":"LinkedIn last-message time: a boolean for presence/absence, or a `{ gte?, lte? }` ISO 8601 range."},"has_last_seen_at":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false}],"description":"Last-seen (last interaction) time — alias for has_interaction: a boolean for presence/absence, or a `{ gte?, lte? }` ISO 8601 range."},"has_distance":{"type":"object","properties":{"lat":{"type":"number"},"lon":{"type":"number"},"meters":{"type":"number"},"label":{"type":"string"}},"required":["lat","lon","meters"],"additionalProperties":false,"description":"Geo radius filter: contacts within `meters` of `{ lat, lon }` (PostGIS ST_DWithin on geocoded coordinates). `label` is an optional display name for the point."},"has_interaction":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false}],"description":"Interaction (last-seen) time: a boolean for presence/absence, or a `{ gte?, lte? }` ISO 8601 range."},"has_next_reminder":{"anyOf":[{"type":"boolean"},{"type":"object","properties":{"gte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"},"lte":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"}},"additionalProperties":false}],"description":"Next-reminder time: a boolean for presence/absence, or a `{ gte?, lte? }` ISO 8601 range."},"custom_fields":{"minItems":1,"type":"array","items":{"type":"object","properties":{"field_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"operator":{"type":"string","enum":["contains","eq","in","not_in","present","absent","gte","lte"]},"value":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},"required":["field_id","operator"],"additionalProperties":false},"description":"User-defined custom-field filters. Each clause is `{ field_id, operator, value? }`; multiple clauses AND together. Operators: contains, eq, in, not_in, present, absent, gte, lte."}},"additionalProperties":false}}},"additionalProperties":false},"orderBy":{},"include":{"type":"object","properties":{"linkedin_data":{"type":"boolean"},"groups_count":{"type":"boolean"},"coordinates":{"type":"boolean"}},"additionalProperties":{"type":"boolean"}},"select":{"type":"object","properties":{"linkedin_data":{"type":"boolean"},"groups_count":{"type":"boolean"},"coordinates":{"type":"boolean"}},"additionalProperties":{"type":"boolean"}},"near":{"type":"string","minLength":1},"radiusKm":{"type":"number","exclusiveMinimum":0,"maximum":20037}},"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"contacts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"first_name":{"nullable":true,"type":"string"},"last_name":{"nullable":true,"type":"string"},"full_name":{"nullable":true,"type":"string"},"description":{"nullable":true,"type":"string"},"job_title":{"nullable":true,"type":"string"},"company":{"nullable":true,"type":"string"},"education":{"nullable":true,"type":"string"},"legacy_location":{"nullable":true,"type":"string"},"image_url":{"nullable":true,"type":"string"},"business_card_url":{"nullable":true,"type":"string"},"website":{"nullable":true,"type":"string"},"image_source":{"nullable":true,"type":"string"},"birthday":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"birthday_year":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"linkedin":{"nullable":true,"type":"string"},"twitter":{"nullable":true,"type":"string"},"facebook":{"nullable":true,"type":"string"},"instagram":{"nullable":true,"type":"string"},"telegram":{"nullable":true,"type":"string"},"tiktok":{"nullable":true,"type":"string"},"youtube":{"nullable":true,"type":"string"},"starred":{"type":"boolean"},"is_archived":{"type":"boolean"},"ignore_merge":{"type":"boolean"},"never_keep_in_touch":{"type":"boolean"},"source":{"type":"string"},"priority_tier":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"frequency":{"nullable":true,"type":"string"},"frequency_text":{"nullable":true,"type":"string"},"last_seen_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"last_reminder_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"next_reminder_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"first_met_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"first_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_companies":{"nullable":true,"type":"string"},"linkedin_education":{"nullable":true,"type":"string"},"linkedin_enhance_date":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_last_message_snippet":{"nullable":true,"type":"string"},"linkedin_message_link":{"nullable":true,"type":"string"},"whatsapp_message_link":{"nullable":true,"type":"string"},"whatsapp_message_snippet":{"nullable":true,"type":"string"},"whatsapp_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"imessage_message_link":{"nullable":true,"type":"string"},"imessage_message_snippet":{"nullable":true,"type":"string"},"imessage_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"instagram_message_link":{"nullable":true,"type":"string"},"instagram_message_snippet":{"nullable":true,"type":"string"},"instagram_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"gmail_last_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"gmail_last_interaction_provider":{"nullable":true,"type":"string","enum":["GOOGLE","OFFICE365"]},"gmail_last_interaction_provider_id":{"nullable":true,"type":"string"},"gmail_last_interaction_subject":{"nullable":true,"type":"string"},"gcal_last_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"gcal_last_interaction_provider":{"nullable":true,"type":"string","enum":["GOOGLE","OFFICE365"]},"gcal_last_interaction_provider_id":{"nullable":true,"type":"string"},"gcal_last_interaction_title":{"nullable":true,"type":"string"},"phone_call_interaction_snippet":{"nullable":true,"type":"string"},"phone_call_last_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"web_search_summary":{"nullable":true},"created_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"updated_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"geocode_attempts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"geocode_failed_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"_count":{"type":"object","properties":{"groups_contacts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["groups_contacts"],"additionalProperties":false},"frequency_interval":{},"linkedin_data":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"latitude":{"nullable":true,"type":"number"},"longitude":{"nullable":true,"type":"number"},"contact_emails":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_phone_numbers":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_birthdays":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"contact_locations":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contacts_custom_fields":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"legacy_contact_addresses":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"groups_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"tags_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"timeline_items_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"reminders_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_relations_contact_relations_sourceTocontacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_relations_contact_relations_destinationTocontacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"feed_items":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"keep_in_touch_reminders":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}}},"required":["id"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"nextCursor":{"nullable":true,"type":"string"},"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"additionalProperties":false},"filterHash":{"type":"string"}},"required":["contacts","filterHash"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"filterContactsV2","summary":"Filter contacts (v2)","description":"List contacts with filters sent in the request body. Accepts a Prisma-shaped `where` clause, an optional geographic `near` radius, and pagination. Returns the same shape as `GET /v2/contacts/` with an extra `filterHash` — a 16-char canonical fingerprint of the filter that actually ran. Clients use it as a stable cache key.","x-mint":{"content":"## Use cases\n\n- Power complex filtered views (multi-tag, multi-group, geo-distance) without URL length limits\n- Backend-to-backend integrations that build the `where` programmatically\n- Drive per-view membership caches keyed by `filterHash` (equal filters across clients → equal hash → shared cache entry)\n\n## `where` shape\n\nFlat key/value object (`has_name`, `has_groups`, `has_interaction`, etc.) — see the `ContactFilters` Zod schema in `@dex/zod-helpers/rest-api-schemas/contact`. AND across keys; reach for `_or` only when you need compound OR.\n\n## Geographic proximity\n\n`near` and `radiusKm` are siblings of `where`, NOT keys inside it. `near` is a free-text place (\"Bay Area\", \"Sydney\") geocoded server-side and folded into `where.has_distance`, so callers never need coordinates or a geocoding key. It ANDs with the rest of `where`. `radiusKm` defaults to 50 and requires `near`.\n\n`where.has_distance` remains available for callers that already hold coordinates. `near` and `where.has_distance` are **mutually exclusive** — sending both is a `400 validation_error`, as is `radiusKm` without `near`.\n\nIf the place cannot be geocoded, the response is an empty page — never an unconstrained contact dump. It carries the non-hex sentinel `filterHash: \"geo-unresolved\"` so the empty page can never share a cache key with the unfiltered list. Treat it as \"no match\", not \"geocoding unavailable\".\n\n## `filterHash`\n\nThe response carries `data.filterHash`, a 16-char hex sha256 prefix of the canonicalized `where`. It fingerprints the **effective** filter — i.e. after `near` has been resolved into `has_distance` — so two different places never collide onto one cache key. Canonicalization is structural: identical filters expressed with different key orders, equivalent text-matcher shapes, or shuffled `_or` arms all produce the same hash. Use it as the cache key for the returned page.\n\n## Extension keys\n\n`custom_fields` and `_or` are fully honored by the server's query translator: `custom_fields` filters by user-defined fields (operators `contains`, `eq`, `in`, `not_in`, `present`, `absent`, `gte`, `lte`), and `_or` combines one level of filter branches with OR. Unknown top-level `where` keys are rejected with a `400 validation_error`. Note that `near` and `radiusKm` are siblings of `where`, not members of it — putting them inside `where` trips that same rejection."}}},"/v2/contacts/search":{"get":{"tags":["contacts"],"parameters":[{"schema":{"type":"string","minLength":1},"in":"query","name":"query","required":true},{"schema":{"type":"integer","minimum":1,"maximum":50},"in":"query","name":"take","required":false}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"contacts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"first_name":{"nullable":true,"type":"string"},"last_name":{"nullable":true,"type":"string"},"full_name":{"nullable":true,"type":"string"},"description":{"nullable":true,"type":"string"},"job_title":{"nullable":true,"type":"string"},"company":{"nullable":true,"type":"string"},"education":{"nullable":true,"type":"string"},"legacy_location":{"nullable":true,"type":"string"},"image_url":{"nullable":true,"type":"string"},"business_card_url":{"nullable":true,"type":"string"},"website":{"nullable":true,"type":"string"},"image_source":{"nullable":true,"type":"string"},"birthday":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"birthday_year":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"linkedin":{"nullable":true,"type":"string"},"twitter":{"nullable":true,"type":"string"},"facebook":{"nullable":true,"type":"string"},"instagram":{"nullable":true,"type":"string"},"telegram":{"nullable":true,"type":"string"},"tiktok":{"nullable":true,"type":"string"},"youtube":{"nullable":true,"type":"string"},"starred":{"type":"boolean"},"is_archived":{"type":"boolean"},"ignore_merge":{"type":"boolean"},"never_keep_in_touch":{"type":"boolean"},"source":{"type":"string"},"priority_tier":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"frequency":{"nullable":true,"type":"string"},"frequency_text":{"nullable":true,"type":"string"},"last_seen_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"last_reminder_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"next_reminder_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"first_met_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"first_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_companies":{"nullable":true,"type":"string"},"linkedin_education":{"nullable":true,"type":"string"},"linkedin_enhance_date":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_last_message_snippet":{"nullable":true,"type":"string"},"linkedin_message_link":{"nullable":true,"type":"string"},"whatsapp_message_link":{"nullable":true,"type":"string"},"whatsapp_message_snippet":{"nullable":true,"type":"string"},"whatsapp_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"imessage_message_link":{"nullable":true,"type":"string"},"imessage_message_snippet":{"nullable":true,"type":"string"},"imessage_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"instagram_message_link":{"nullable":true,"type":"string"},"instagram_message_snippet":{"nullable":true,"type":"string"},"instagram_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"gmail_last_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"gmail_last_interaction_provider":{"nullable":true,"type":"string","enum":["GOOGLE","OFFICE365"]},"gmail_last_interaction_provider_id":{"nullable":true,"type":"string"},"gmail_last_interaction_subject":{"nullable":true,"type":"string"},"gcal_last_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"gcal_last_interaction_provider":{"nullable":true,"type":"string","enum":["GOOGLE","OFFICE365"]},"gcal_last_interaction_provider_id":{"nullable":true,"type":"string"},"gcal_last_interaction_title":{"nullable":true,"type":"string"},"phone_call_interaction_snippet":{"nullable":true,"type":"string"},"phone_call_last_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"web_search_summary":{"nullable":true},"created_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"updated_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"geocode_attempts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"geocode_failed_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"_count":{"type":"object","properties":{"groups_contacts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["groups_contacts"],"additionalProperties":false},"frequency_interval":{},"linkedin_data":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"latitude":{"nullable":true,"type":"number"},"longitude":{"nullable":true,"type":"number"},"contact_emails":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_phone_numbers":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_birthdays":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"contact_locations":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contacts_custom_fields":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"legacy_contact_addresses":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"groups_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"tags_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"timeline_items_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"reminders_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_relations_contact_relations_sourceTocontacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_relations_contact_relations_destinationTocontacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"feed_items":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"keep_in_touch_reminders":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}}},"required":["id"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"nextCursor":{"nullable":true,"type":"string"},"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"additionalProperties":false}},"required":["contacts"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"searchContactsTypeaheadV2","summary":"Search contacts by name (v2)","description":"Name-only typeahead. Matches the contact's full name accent-insensitively (`f_unaccent`) and returns full contact rows in the list envelope `{ data: { contacts: [...] } }`. `query` is required — send `POST /v2/contacts/search` if you need an empty-query listing, a wider field fan-out, or geographic search.","x-mint":{"content":"## Use cases\n\n- Power a real-time search-as-you-type box\n- Resolve a contact from a partially typed name (`@`-mentions, pickers)\n\n## Scope\n\nThis endpoint matches **full name only**. It does not search email, company, job title, location or notes — a query that looks like a company name returns no results here. Rows come back complete, so they are safe to write straight into a client-side contacts store.\n\n## Choosing between the search endpoints\n\n| You need | Use |\n| --- | --- |\n| Type-ahead on a name, full rows back | **`GET /v2/contacts/search`** (this endpoint) |\n| Free text across name, email, job title, company, education, location, notes | `POST /v2/contacts/search` |\n| Geographic proximity (`near` / `radiusKm`) | `POST /v2/contacts/search` or `POST /v2/contacts/filter` |\n| List by most recent interaction (empty query) | `POST /v2/contacts/search` |\n| Structured attributes — tags, groups, custom fields, date ranges | `POST /v2/contacts/filter` |\n\nThe POST route returns a narrow projection rather than full rows, so its results are not safe to upsert into a contacts store. Fetch `GET /v2/contacts/{contactId}` for the full record.\n\n## Migration from /v1\n\n/v1 returned `{ error: false, data: { items: [...] } }`. /v2 returns `{ data: { contacts: [...] } }` — entity plural at the top level, no `error` field on success."}},"post":{"tags":["contacts"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"searchQuery":{"type":"string"},"archived":{"type":"boolean"},"minimal":{"type":"boolean"},"exactMatch":{"type":"boolean"},"enhanced":{"type":"boolean"},"near":{"type":"string","minLength":1},"radiusKm":{"type":"number","exclusiveMinimum":0,"maximum":20037},"take":{"type":"integer","minimum":1,"maximum":200},"fallbackNameToEmail":{"type":"boolean"},"has_groups":{"anyOf":[{"type":"object","properties":{"not":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}]}},"required":["not"],"additionalProperties":false},{"type":"boolean"},{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}]}},"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"contacts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"first_name":{"nullable":true,"type":"string"},"last_name":{"nullable":true,"type":"string"},"full_name":{"nullable":true,"type":"string"},"description":{"nullable":true,"type":"string"},"job_title":{"nullable":true,"type":"string"},"company":{"nullable":true,"type":"string"},"education":{"nullable":true,"type":"string"},"legacy_location":{"nullable":true,"type":"string"},"image_url":{"nullable":true,"type":"string"},"business_card_url":{"nullable":true,"type":"string"},"website":{"nullable":true,"type":"string"},"image_source":{"nullable":true,"type":"string"},"birthday":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"birthday_year":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"linkedin":{"nullable":true,"type":"string"},"twitter":{"nullable":true,"type":"string"},"facebook":{"nullable":true,"type":"string"},"instagram":{"nullable":true,"type":"string"},"telegram":{"nullable":true,"type":"string"},"tiktok":{"nullable":true,"type":"string"},"youtube":{"nullable":true,"type":"string"},"starred":{"type":"boolean"},"is_archived":{"type":"boolean"},"ignore_merge":{"type":"boolean"},"never_keep_in_touch":{"type":"boolean"},"source":{"type":"string"},"priority_tier":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"frequency":{"nullable":true,"type":"string"},"frequency_text":{"nullable":true,"type":"string"},"last_seen_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"last_reminder_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"next_reminder_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"first_met_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"first_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_companies":{"nullable":true,"type":"string"},"linkedin_education":{"nullable":true,"type":"string"},"linkedin_enhance_date":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_last_message_snippet":{"nullable":true,"type":"string"},"linkedin_message_link":{"nullable":true,"type":"string"},"whatsapp_message_link":{"nullable":true,"type":"string"},"whatsapp_message_snippet":{"nullable":true,"type":"string"},"whatsapp_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"imessage_message_link":{"nullable":true,"type":"string"},"imessage_message_snippet":{"nullable":true,"type":"string"},"imessage_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"instagram_message_link":{"nullable":true,"type":"string"},"instagram_message_snippet":{"nullable":true,"type":"string"},"instagram_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"gmail_last_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"gmail_last_interaction_provider":{"nullable":true,"type":"string","enum":["GOOGLE","OFFICE365"]},"gmail_last_interaction_provider_id":{"nullable":true,"type":"string"},"gmail_last_interaction_subject":{"nullable":true,"type":"string"},"gcal_last_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"gcal_last_interaction_provider":{"nullable":true,"type":"string","enum":["GOOGLE","OFFICE365"]},"gcal_last_interaction_provider_id":{"nullable":true,"type":"string"},"gcal_last_interaction_title":{"nullable":true,"type":"string"},"phone_call_interaction_snippet":{"nullable":true,"type":"string"},"phone_call_last_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"web_search_summary":{"nullable":true},"created_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"updated_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"geocode_attempts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"geocode_failed_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"_count":{"type":"object","properties":{"groups_contacts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["groups_contacts"],"additionalProperties":false},"frequency_interval":{},"linkedin_data":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"latitude":{"nullable":true,"type":"number"},"longitude":{"nullable":true,"type":"number"},"contact_emails":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_phone_numbers":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_birthdays":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"contact_locations":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contacts_custom_fields":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"legacy_contact_addresses":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"groups_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"tags_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"timeline_items_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"reminders_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_relations_contact_relations_sourceTocontacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_relations_contact_relations_destinationTocontacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"feed_items":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"keep_in_touch_reminders":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}}},"required":["id"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"nextCursor":{"nullable":true,"type":"string"},"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"additionalProperties":false}},"required":["contacts"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"searchContactsV2","summary":"Search contacts, full (v2)","description":"Full-capability contact search: free-text across seven fields with accent folding and similarity ranking, an optional geographic `near` radius, group/archive filters, and an empty-query mode that lists contacts by most recent interaction. Returns the contact list envelope `{ data: { contacts: [...] } }`.","x-mint":{"content":"## Use cases\n\n- Answer natural-language contact lookups (\"engineers in the Bay Area\")\n- List contacts by most recent interaction (send an empty or omitted `searchQuery`)\n- Search across job title, company, education, location, and description — not just name\n\n## Search modes\n\n| Body | Behaviour |\n| --- | --- |\n| `searchQuery` omitted or `\"\"` | Lists contacts ordered by starred, then most recent `last_seen_at`. |\n| `searchQuery` set (default) | Fans out across full name, email, job title, company, education, location, and description. Accent-insensitive (`f_unaccent`), ranked by trigram similarity, starred matches first. |\n| `minimal: true` | Full-name match only — the cheapest mode. Pair with `exactMatch: true` for a prefix-anchored name match. |\n| `enhanced: true` | Every field except description, without the starred pre-pass. Mutually exclusive with `minimal`. |\n\n## Geographic proximity\n\n`near` is a free-text place (\"Bay Area\", \"Sydney\") geocoded server-side and matched against each contact's own coordinates, so it finds people whose stored location differs from the query. `radiusKm` defaults to 50. `near` and `searchQuery` combine with AND.\n\nIf the place cannot be geocoded, the response is an empty list — never an unconstrained contact dump. Treat an empty result as \"no match\", not \"geocoding unavailable\".\n\n## Migration from /v1\n\nReplaces `GET /v1/search/contacts`. The query parameters move into the request body unchanged (including `has_groups`), and the response envelope changes from `{ error: false, data: [...] }` to `{ data: { contacts: [...], pagination: { count } } }`.\n\nContacts are returned as a narrow projection (id, names, job title, avatar, location, description, starred). Call `GET /v2/contacts/{contactId}` for the full record.\n\n## Choosing between the search endpoints\n\n`GET /v2/contacts/search` is a lightweight name-only typeahead that returns full contact rows. Use this POST route when you need the wider field fan-out, geographic search, or the empty-query listing mode. For structured attribute filtering (tags, custom fields, dates), use `POST /v2/contacts/filter`."}}},"/v2/contacts/batch":{"post":{"tags":["contacts"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contacts":{"maxItems":500,"type":"array","items":{"type":"object","properties":{"full_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"first_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"job_title":{"anyOf":[{"type":"string"},{"type":"null"}]},"legacy_location":{"anyOf":[{"type":"string"},{"type":"null"}]},"company":{"anyOf":[{"type":"string"},{"type":"null"}]},"education":{"anyOf":[{"type":"string"},{"type":"null"}]},"starred":{"type":"boolean"},"source":{"type":"string","enum":["linkedin_sync","facebook_import","cal_ingest","email_ingest","web_import","csv_import","whatsapp_sync","imessage_sync","phone_calls_sync","mobile","mobile_import","instagram_sync","oauth_interaction"]},"coordinates":{"type":"object","properties":{"operation":{"type":"string","enum":["set","delete"]},"data":{"type":"object","properties":{"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180}},"additionalProperties":false}},"required":["operation"],"additionalProperties":false},"priority_tier":{"anyOf":[{"type":"integer","minimum":1,"maximum":32767},{"type":"null"}]},"image_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"image_source":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"business_card_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"website":{"anyOf":[{},{"type":"null"}]},"birthday":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"birthday_year":{"anyOf":[{"type":"number","minimum":1900,"maximum":2100},{"type":"null"}]},"frequency":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_seen_at":{"anyOf":[{},{"type":"null"}]},"first_met_at":{"anyOf":[{},{"type":"null"}]},"never_keep_in_touch":{"type":"boolean"},"next_reminder_at":{},"linkedin":{"anyOf":[{"type":"string"},{"type":"null"}]},"twitter":{"anyOf":[{"type":"string"},{"type":"null"}]},"facebook":{"anyOf":[{"type":"string"},{"type":"null"}]},"instagram":{"anyOf":[{"type":"string"},{"type":"null"}]},"telegram":{"anyOf":[{"type":"string"},{"type":"null"}]},"tiktok":{"anyOf":[{"type":"string"},{"type":"null"}]},"youtube":{"anyOf":[{"type":"string"},{"type":"null"}]},"whatsapp_message_link":{"type":"string"},"whatsapp_message_snippet":{"anyOf":[{"type":"string"},{"type":"null"}]},"whatsapp_last_message_at":{"anyOf":[{},{"type":"null"}]},"imessage_message_link":{"type":"string"},"imessage_message_snippet":{"anyOf":[{"type":"string"},{"type":"null"}]},"imessage_last_message_at":{"anyOf":[{},{"type":"null"}]},"linkedin_message_link":{"type":"string","maxLength":600},"linkedin_last_message_snippet":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"linkedin_last_message_at":{"anyOf":[{},{"type":"null"}]},"linkedin_data":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"instagram_message_link":{"type":"string"},"instagram_message_snippet":{"anyOf":[{"type":"string"},{"type":"null"}]},"instagram_last_message_at":{"anyOf":[{},{"type":"null"}]},"gmail_last_interaction_at":{"anyOf":[{},{"type":"null"}]},"gmail_last_interaction_provider_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"gmail_last_interaction_subject":{"anyOf":[{"type":"string"},{"type":"null"}]},"gmail_last_interaction_provider":{"anyOf":[{"type":"string","enum":["GOOGLE","OFFICE365"]},{"type":"null"}]},"gcal_last_interaction_at":{"anyOf":[{},{"type":"null"}]},"gcal_last_interaction_provider_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"gcal_last_interaction_title":{"anyOf":[{"type":"string"},{"type":"null"}]},"gcal_last_interaction_provider":{"anyOf":[{"type":"string","enum":["GOOGLE","OFFICE365"]},{"type":"null"}]},"phone_call_last_interaction_at":{"anyOf":[{},{"type":"null"}]},"phone_call_interaction_snippet":{"anyOf":[{"type":"string"},{"type":"null"}]},"web_search_summary":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"legacy_contact_addresses":{"type":"array","items":{"type":"object","properties":{"formatted":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false}},"contact_emails":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string","maxLength":320},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"ranking":{"type":"number"}},"required":["email"],"additionalProperties":false}},"contact_phone_numbers":{"type":"array","items":{"type":"object","properties":{"phone_number":{"type":"string","maxLength":50},"country_code":{"anyOf":[{"type":"string","maxLength":4},{"type":"null"}]},"phone_number_sanitized":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"ranking":{"type":"number"}},"required":["phone_number"],"additionalProperties":false}},"groups_contacts":{"type":"array","items":{"type":"object","properties":{"group_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["group_id"],"additionalProperties":false}},"tags_contacts":{"type":"array","items":{"type":"object","properties":{"tag_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["tag_id"],"additionalProperties":false}},"custom_fields":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"type":{"type":"string","enum":["input"]},"text_value":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}]},"custom_field":{}},"required":["id","type","text_value"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"type":{"type":"string","enum":["autocomplete"]},"text_value":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}]},"custom_field":{}},"required":["id","type","text_value"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"type":{"type":"string","enum":["datepicker"]},"text_value":{"anyOf":[{"type":"string"},{"type":"null"}]},"date_value":{"anyOf":[{},{"type":"null"}]},"custom_field":{}},"required":["id","type"],"additionalProperties":false}]}},"contact_birthdays":{"type":"object","properties":{"contact_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"last_dismissal_year":{"type":"number","minimum":1900,"maximum":2100}},"additionalProperties":false},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"related_contacts":{"type":"array","items":{"type":"object","properties":{"destination":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"source_contact":{},"destination_contact":{}},"required":["destination"],"additionalProperties":false}}},"additionalProperties":false}},"continueOnError":{"type":"boolean"}},"required":["contacts"],"additionalProperties":false}}}},"responses":{"201":{"description":"Created","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"contacts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"first_name":{"nullable":true,"type":"string"},"last_name":{"nullable":true,"type":"string"},"full_name":{"nullable":true,"type":"string"},"description":{"nullable":true,"type":"string"},"job_title":{"nullable":true,"type":"string"},"company":{"nullable":true,"type":"string"},"education":{"nullable":true,"type":"string"},"legacy_location":{"nullable":true,"type":"string"},"image_url":{"nullable":true,"type":"string"},"business_card_url":{"nullable":true,"type":"string"},"website":{"nullable":true,"type":"string"},"image_source":{"nullable":true,"type":"string"},"birthday":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"birthday_year":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"linkedin":{"nullable":true,"type":"string"},"twitter":{"nullable":true,"type":"string"},"facebook":{"nullable":true,"type":"string"},"instagram":{"nullable":true,"type":"string"},"telegram":{"nullable":true,"type":"string"},"tiktok":{"nullable":true,"type":"string"},"youtube":{"nullable":true,"type":"string"},"starred":{"type":"boolean"},"is_archived":{"type":"boolean"},"ignore_merge":{"type":"boolean"},"never_keep_in_touch":{"type":"boolean"},"source":{"type":"string"},"priority_tier":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"frequency":{"nullable":true,"type":"string"},"frequency_text":{"nullable":true,"type":"string"},"last_seen_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"last_reminder_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"next_reminder_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"first_met_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"first_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_companies":{"nullable":true,"type":"string"},"linkedin_education":{"nullable":true,"type":"string"},"linkedin_enhance_date":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_last_message_snippet":{"nullable":true,"type":"string"},"linkedin_message_link":{"nullable":true,"type":"string"},"whatsapp_message_link":{"nullable":true,"type":"string"},"whatsapp_message_snippet":{"nullable":true,"type":"string"},"whatsapp_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"imessage_message_link":{"nullable":true,"type":"string"},"imessage_message_snippet":{"nullable":true,"type":"string"},"imessage_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"instagram_message_link":{"nullable":true,"type":"string"},"instagram_message_snippet":{"nullable":true,"type":"string"},"instagram_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"gmail_last_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"gmail_last_interaction_provider":{"nullable":true,"type":"string","enum":["GOOGLE","OFFICE365"]},"gmail_last_interaction_provider_id":{"nullable":true,"type":"string"},"gmail_last_interaction_subject":{"nullable":true,"type":"string"},"gcal_last_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"gcal_last_interaction_provider":{"nullable":true,"type":"string","enum":["GOOGLE","OFFICE365"]},"gcal_last_interaction_provider_id":{"nullable":true,"type":"string"},"gcal_last_interaction_title":{"nullable":true,"type":"string"},"phone_call_interaction_snippet":{"nullable":true,"type":"string"},"phone_call_last_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"web_search_summary":{"nullable":true},"created_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"updated_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"geocode_attempts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"geocode_failed_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"_count":{"type":"object","properties":{"groups_contacts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["groups_contacts"],"additionalProperties":false},"frequency_interval":{},"linkedin_data":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"latitude":{"nullable":true,"type":"number"},"longitude":{"nullable":true,"type":"number"},"contact_emails":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_phone_numbers":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_birthdays":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"contact_locations":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contacts_custom_fields":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"legacy_contact_addresses":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"groups_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"tags_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"timeline_items_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"reminders_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_relations_contact_relations_sourceTocontacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_relations_contact_relations_destinationTocontacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"feed_items":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"keep_in_touch_reminders":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}}},"required":["id"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"nextCursor":{"nullable":true,"type":"string"},"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"additionalProperties":false},"batch":{"type":"object","properties":{"requested":{"type":"integer","minimum":0,"maximum":9007199254740991},"committed":{"type":"integer","minimum":0,"maximum":9007199254740991},"committedThrough":{"type":"integer","minimum":0,"maximum":9007199254740991},"chunkSize":{"type":"integer","minimum":0,"exclusiveMinimum":true,"maximum":9007199254740991},"chunks":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer","minimum":0,"maximum":9007199254740991},"offset":{"type":"integer","minimum":0,"maximum":9007199254740991},"count":{"type":"integer","minimum":0,"maximum":9007199254740991},"status":{"type":"string","enum":["committed","failed"]},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["index","offset","count","status"],"additionalProperties":false}},"failedRows":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer","minimum":0,"maximum":9007199254740991},"id":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["index","error"],"additionalProperties":false}}},"required":["requested","committed","committedThrough","chunkSize","chunks"],"additionalProperties":false}},"required":["contacts","batch"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"batchCreateContactsV2","summary":"Bulk-create contacts (v2)","description":"Create multiple contacts in a single request. **Requires `Idempotency-Key`.** Returns the created contacts as `{ data: { contacts: [...] }, ... }` with status 201, alongside a `data.batch` partial-success report.","x-mint":{"content":"## Use cases\n\n- CSV imports\n- Migrate from another CRM\n- Sync contacts from a third-party source\n\n## Idempotency\n\nGenerate one UUID per logical import operation and reuse it on every retry. Without this, a network failure that successfully created contacts but lost the response would cause duplicate rows on retry.\n\nSupply your own `id` (a UUID) on each contact. It becomes the row's primary key and the insert is `ON CONFLICT DO NOTHING`, so re-sending a row you already sent is a no-op. This is what makes a resume safe at row granularity, where `Idempotency-Key` — which is per-request and only caches successful responses — cannot help.\n\n## Partial success\n\nThe request is processed as several independent transactions, so a failure can leave part of it committed. Every 201 carries a `data.batch` report:\n\n```json\n{ \"requested\": 500, \"committed\": 397, \"committedThrough\": 300, \"chunkSize\": 100,\n \"chunks\": [ { \"index\": 3, \"offset\": 300, \"count\": 100, \"status\": \"failed\", \"error\": { \"code\": \"unknown_error\", \"message\": \"...\" } } ],\n \"failedRows\": [ { \"index\": 12, \"id\": \"…\", \"error\": { \"code\": \"validation_error\", \"message\": \"...\" } } ] }\n```\n\nResume from `chunks`: re-send the rows of every entry whose `status` is `\"failed\"` — `[offset, offset + count)` — with the same row ids. `committedThrough` is an **index** into the maximal LEADING run of committed chunks: re-sending `contacts.slice(committedThrough)` is complete and idempotent, but chunks run concurrently, so a failed chunk sitting before a committed one makes that index under-report what is already present. In the example above the leading run stops at 300 while 397 rows are in — a prefix resume re-sends 100 rows the server already has. Every overlap is a no-op, so this costs bandwidth, not correctness. `committed` is a **count** of rows now present. `data.contacts` holds only the rows this call actually inserted (a re-sent row that already existed is absent), so never use its length as progress.\n\nBy default a chunk failure still fails the whole request, as it always has. Send `\"continueOnError\": true` to get the 201-with-report behaviour instead; use a fresh `Idempotency-Key` for the resume request, since its body differs.\n\nThe endpoint accepts `{ contacts: [] }` for an empty bulk-create and returns `{ data: { contacts: [] } }` — useful as a no-op confirmation that the request reached the server."},"parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","minLength":8,"maxLength":255,"pattern":"^[\\w\\-:.]+$","example":"01HV8N6X7K3P9Q5R2T4Y6W8Z0A"},"description":"Required. UUID per logical operation, reused on every retry. See `apps/rest-api/src/shared/idempotency.ts` for the full contract. Missing → 400 BadRequest; same key + different body → 409 Conflict."}]}},"/v2/contacts/batch-update":{"post":{"tags":["contacts"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"updates":{"minItems":1,"type":"array","items":{"type":"object","properties":{"contactId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"data":{"type":"object","properties":{"full_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"first_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"job_title":{"anyOf":[{"type":"string"},{"type":"null"}]},"legacy_location":{"anyOf":[{"type":"string"},{"type":"null"}]},"company":{"anyOf":[{"type":"string"},{"type":"null"}]},"education":{"anyOf":[{"type":"string"},{"type":"null"}]},"starred":{"type":"boolean"},"source":{"type":"string","enum":["linkedin_sync","facebook_import","cal_ingest","email_ingest","web_import","csv_import","whatsapp_sync","imessage_sync","phone_calls_sync","mobile","mobile_import","instagram_sync","oauth_interaction"]},"coordinates":{"type":"object","properties":{"operation":{"type":"string","enum":["set","delete"]},"data":{"type":"object","properties":{"latitude":{"type":"number","minimum":-90,"maximum":90},"longitude":{"type":"number","minimum":-180,"maximum":180}},"additionalProperties":false}},"required":["operation"],"additionalProperties":false},"priority_tier":{"anyOf":[{"type":"integer","minimum":1,"maximum":32767},{"type":"null"}]},"image_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"image_source":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"business_card_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]},"website":{"anyOf":[{},{"type":"null"}]},"birthday":{"anyOf":[{"type":"string","format":"date","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"},{"type":"null"}]},"birthday_year":{"anyOf":[{"type":"number","minimum":1900,"maximum":2100},{"type":"null"}]},"frequency":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_seen_at":{"anyOf":[{},{"type":"null"}]},"first_met_at":{"anyOf":[{},{"type":"null"}]},"never_keep_in_touch":{"type":"boolean"},"next_reminder_at":{},"linkedin":{"anyOf":[{"type":"string"},{"type":"null"}]},"twitter":{"anyOf":[{"type":"string"},{"type":"null"}]},"facebook":{"anyOf":[{"type":"string"},{"type":"null"}]},"instagram":{"anyOf":[{"type":"string"},{"type":"null"}]},"telegram":{"anyOf":[{"type":"string"},{"type":"null"}]},"tiktok":{"anyOf":[{"type":"string"},{"type":"null"}]},"youtube":{"anyOf":[{"type":"string"},{"type":"null"}]},"whatsapp_message_link":{"type":"string"},"whatsapp_message_snippet":{"anyOf":[{"type":"string"},{"type":"null"}]},"whatsapp_last_message_at":{"anyOf":[{},{"type":"null"}]},"imessage_message_link":{"type":"string"},"imessage_message_snippet":{"anyOf":[{"type":"string"},{"type":"null"}]},"imessage_last_message_at":{"anyOf":[{},{"type":"null"}]},"linkedin_message_link":{"type":"string","maxLength":600},"linkedin_last_message_snippet":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}]},"linkedin_last_message_at":{"anyOf":[{},{"type":"null"}]},"linkedin_data":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}]},"instagram_message_link":{"type":"string"},"instagram_message_snippet":{"anyOf":[{"type":"string"},{"type":"null"}]},"instagram_last_message_at":{"anyOf":[{},{"type":"null"}]},"gmail_last_interaction_at":{"anyOf":[{},{"type":"null"}]},"gmail_last_interaction_provider_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"gmail_last_interaction_subject":{"anyOf":[{"type":"string"},{"type":"null"}]},"gmail_last_interaction_provider":{"anyOf":[{"type":"string","enum":["GOOGLE","OFFICE365"]},{"type":"null"}]},"gcal_last_interaction_at":{"anyOf":[{},{"type":"null"}]},"gcal_last_interaction_provider_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"gcal_last_interaction_title":{"anyOf":[{"type":"string"},{"type":"null"}]},"gcal_last_interaction_provider":{"anyOf":[{"type":"string","enum":["GOOGLE","OFFICE365"]},{"type":"null"}]},"phone_call_last_interaction_at":{"anyOf":[{},{"type":"null"}]},"phone_call_interaction_snippet":{"anyOf":[{"type":"string"},{"type":"null"}]},"web_search_summary":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"legacy_contact_addresses":{"type":"array","items":{"type":"object","properties":{"formatted":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false}},"contact_emails":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string","maxLength":320},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"ranking":{"type":"number"}},"required":["email"],"additionalProperties":false}},"contact_phone_numbers":{"type":"array","items":{"type":"object","properties":{"phone_number":{"type":"string","maxLength":50},"country_code":{"anyOf":[{"type":"string","maxLength":4},{"type":"null"}]},"phone_number_sanitized":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}]},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"ranking":{"type":"number"}},"required":["phone_number"],"additionalProperties":false}},"groups_contacts":{"type":"array","items":{"type":"object","properties":{"group_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["group_id"],"additionalProperties":false}},"tags_contacts":{"anyOf":[{"type":"object","properties":{"append":{"type":"array","items":{"type":"object","properties":{"tag_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["tag_id"],"additionalProperties":false}},"remove":{"type":"array","items":{"type":"object","properties":{"tag_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"contact_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["tag_id","contact_id"],"additionalProperties":false}},"replace":{}},"additionalProperties":false},{"type":"object","properties":{"append":{},"remove":{},"replace":{"type":"array","items":{"type":"object","properties":{"tag_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["tag_id"],"additionalProperties":false}}},"additionalProperties":false}]},"custom_fields":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"type":{"type":"string","enum":["input"]},"text_value":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}]},"custom_field":{}},"required":["id","type","text_value"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"type":{"type":"string","enum":["autocomplete"]},"text_value":{"anyOf":[{"type":"string","maxLength":5000},{"type":"null"}]},"custom_field":{}},"required":["id","type","text_value"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"type":{"type":"string","enum":["datepicker"]},"text_value":{"anyOf":[{"type":"string"},{"type":"null"}]},"date_value":{"anyOf":[{},{"type":"null"}]},"custom_field":{}},"required":["id","type"],"additionalProperties":false}]}},"contact_birthdays":{"type":"object","properties":{"contact_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"last_dismissal_year":{"type":"number","minimum":1900,"maximum":2100}},"additionalProperties":false},"is_archived":{"type":"boolean"},"ignore_merge":{"type":"boolean"},"related_contacts":{"anyOf":[{"type":"object","properties":{"append":{"type":"array","items":{"type":"object","properties":{"destination":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"source_contact":{},"destination_contact":{}},"required":["destination"],"additionalProperties":false}},"remove":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"source":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"destination":{}},"required":["source","destination"],"additionalProperties":false},{"type":"object","properties":{"source":{},"destination":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["source","destination"],"additionalProperties":false}]}},"replace":{}},"additionalProperties":false},{"type":"object","properties":{"append":{},"remove":{},"replace":{"type":"array","items":{"type":"object","properties":{"destination":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"source_contact":{},"destination_contact":{}},"required":["destination"],"additionalProperties":false}}},"additionalProperties":false}]}},"additionalProperties":false}},"required":["contactId","data"],"additionalProperties":false}}},"required":["updates"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"affected":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"ids":{"type":"array","items":{"type":"string"}},"failed":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","error"],"additionalProperties":false}}},"required":["affected"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"batchUpdateContactsV2","summary":"Bulk-update contacts (v2)","description":"Update multiple contacts in a single request. Per-row results are settled (some can succeed, others fail). **Requires `Idempotency-Key`.** Returns `{ data: { affected, ids } }` where `ids` lists the contact IDs that were successfully updated.","x-mint":{"content":"## Use cases\n\n- Bulk-edit selections from the contact list\n- Apply field defaults across a tag-filtered group\n- Backfill enrichment data across many contacts at once\n\n## Migration from /v1\n\n/v1 used `PUT /v1/contacts/` with an array body and returned `{ data: { count } }`. /v2 uses `POST /v2/contacts/batch-update` (PUT-on-collection is ambiguous in REST semantics) and surfaces the list of successfully-updated IDs in `data.ids` so cache writers can invalidate just those rows without an extra read."},"parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","minLength":8,"maxLength":255,"pattern":"^[\\w\\-:.]+$","example":"01HV8N6X7K3P9Q5R2T4Y6W8Z0A"},"description":"Required. UUID per logical operation, reused on every retry. See `apps/rest-api/src/shared/idempotency.ts` for the full contract. Missing → 400 BadRequest; same key + different body → 409 Conflict."}]}},"/v2/contacts/batch-delete":{"post":{"tags":["contacts"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contactIds":{"minItems":1,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"required":["contactIds"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"affected":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"ids":{"type":"array","items":{"type":"string"}},"failed":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","error"],"additionalProperties":false}}},"required":["affected"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"batchDeleteContactsV2","summary":"Bulk-delete contacts (v2)","description":"Permanently delete multiple contacts in a single request. Returns `{ data: { affected, ids } }` where `ids` is the array of deleted contact IDs (echoed from the request body). `Idempotency-Key` is optional.","x-mint":{"content":"## Use cases\n\n- Remove a multi-selection of contacts at once\n- Bulk-cleanup of duplicates after a merge audit\n- Tag-driven bulk removal\n\n## Migration from /v1\n\n/v1 used `DELETE /v1/contacts/` with a body. HTTP spec discourages bodies on DELETE and some proxies strip them silently. /v2 uses `POST /v2/contacts/batch-delete` to keep the body intact in transit.\n\nThis is a destructive operation. Deleted contacts cannot be recovered."},"parameters":[{"in":"header","name":"Idempotency-Key","required":false,"schema":{"type":"string","minLength":8,"maxLength":255,"pattern":"^[\\w\\-:.]+$","example":"01HV8N6X7K3P9Q5R2T4Y6W8Z0A"},"description":"Optional. Accepted to dedupe retries on this endpoint. See `apps/rest-api/src/shared/idempotency.ts`."}]}},"/v2/contacts/merge":{"post":{"tags":["contacts"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contactIds":{"minItems":1,"type":"array","items":{"minItems":2,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}}},"required":["contactIds"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"merged":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"first_name":{"nullable":true,"type":"string"},"last_name":{"nullable":true,"type":"string"},"full_name":{"nullable":true,"type":"string"},"description":{"nullable":true,"type":"string"},"job_title":{"nullable":true,"type":"string"},"company":{"nullable":true,"type":"string"},"education":{"nullable":true,"type":"string"},"legacy_location":{"nullable":true,"type":"string"},"image_url":{"nullable":true,"type":"string"},"business_card_url":{"nullable":true,"type":"string"},"website":{"nullable":true,"type":"string"},"image_source":{"nullable":true,"type":"string"},"birthday":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"birthday_year":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"linkedin":{"nullable":true,"type":"string"},"twitter":{"nullable":true,"type":"string"},"facebook":{"nullable":true,"type":"string"},"instagram":{"nullable":true,"type":"string"},"telegram":{"nullable":true,"type":"string"},"tiktok":{"nullable":true,"type":"string"},"youtube":{"nullable":true,"type":"string"},"starred":{"type":"boolean"},"is_archived":{"type":"boolean"},"ignore_merge":{"type":"boolean"},"never_keep_in_touch":{"type":"boolean"},"source":{"type":"string"},"priority_tier":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"frequency":{"nullable":true,"type":"string"},"frequency_text":{"nullable":true,"type":"string"},"last_seen_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"last_reminder_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"next_reminder_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"first_met_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"first_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_companies":{"nullable":true,"type":"string"},"linkedin_education":{"nullable":true,"type":"string"},"linkedin_enhance_date":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_last_message_snippet":{"nullable":true,"type":"string"},"linkedin_message_link":{"nullable":true,"type":"string"},"whatsapp_message_link":{"nullable":true,"type":"string"},"whatsapp_message_snippet":{"nullable":true,"type":"string"},"whatsapp_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"imessage_message_link":{"nullable":true,"type":"string"},"imessage_message_snippet":{"nullable":true,"type":"string"},"imessage_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"instagram_message_link":{"nullable":true,"type":"string"},"instagram_message_snippet":{"nullable":true,"type":"string"},"instagram_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"gmail_last_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"gmail_last_interaction_provider":{"nullable":true,"type":"string","enum":["GOOGLE","OFFICE365"]},"gmail_last_interaction_provider_id":{"nullable":true,"type":"string"},"gmail_last_interaction_subject":{"nullable":true,"type":"string"},"gcal_last_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"gcal_last_interaction_provider":{"nullable":true,"type":"string","enum":["GOOGLE","OFFICE365"]},"gcal_last_interaction_provider_id":{"nullable":true,"type":"string"},"gcal_last_interaction_title":{"nullable":true,"type":"string"},"phone_call_interaction_snippet":{"nullable":true,"type":"string"},"phone_call_last_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"web_search_summary":{"nullable":true},"created_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"updated_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"geocode_attempts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"geocode_failed_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"_count":{"type":"object","properties":{"groups_contacts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["groups_contacts"],"additionalProperties":false},"frequency_interval":{},"linkedin_data":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"latitude":{"nullable":true,"type":"number"},"longitude":{"nullable":true,"type":"number"},"contact_emails":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_phone_numbers":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_birthdays":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"contact_locations":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contacts_custom_fields":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"legacy_contact_addresses":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"groups_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"tags_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"timeline_items_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"reminders_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_relations_contact_relations_sourceTocontacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_relations_contact_relations_destinationTocontacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"feed_items":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"keep_in_touch_reminders":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}}},"required":["id"],"additionalProperties":false}},"failed":{"type":"array","items":{"type":"object","properties":{"contactIds":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["contactIds","error"],"additionalProperties":false}}},"required":["merged","failed"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"mergeContactsV2","summary":"Merge duplicate contacts (v2)","description":"Merge one or more groups of duplicate contacts. The request body is `{ contactIds: string[][] }` — each inner array is a group of ≥2 contact IDs to merge into a single surviving contact. Returns `{ data: { merged: Contact[], failed: [...] } }`: `merged` holds the surviving contacts, `failed` lists any groups that could not be merged. `Idempotency-Key` is REQUIRED.","x-mint":{"content":"## Use cases\n\n- Resolve duplicates from the \"Merge and Fix\" page (one group or all at once)\n\n## Migration from /v1\n\n/v1 `POST /v1/contacts/merge` returned only `{ mergedContactIds }` and was not idempotent. /v2 returns the full surviving contact entities (so clients can update their cache without a refetch) plus a per-group `failed[]` list, and REQUIRES an `Idempotency-Key` so a retried merge replays the original response instead of re-merging.\n\nMerging is destructive: source contacts are absorbed into the survivor and deleted."},"parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","minLength":8,"maxLength":255,"pattern":"^[\\w\\-:.]+$","example":"01HV8N6X7K3P9Q5R2T4Y6W8Z0A"},"description":"Required. UUID per logical operation, reused on every retry. See `apps/rest-api/src/shared/idempotency.ts` for the full contract. Missing → 400 BadRequest; same key + different body → 409 Conflict."}]}},"/v2/favorites/{favoriteId}":{"get":{"tags":["favorites"],"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"favoriteId","required":true}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"favorite":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"group_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"view_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"contact_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"ranking":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"created_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"updated_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"groups":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"views":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"contacts":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}}},"required":["id","created_at","updated_at"],"additionalProperties":false}},"required":["favorite"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getFavoriteV2","summary":"Get a favorite (v2)","description":"Retrieve a single favorite by its unique ID. Returns `{ data: { favorite: {...} } }`. The polymorphic target — exactly one of `group_id`, `view_id`, or `contact_id` — is on the favorite body; relations (`groups`, `views`, `contacts`) are inflated for the matching target only.","x-mint":{"content":"## Use cases\n\n- Hydrate a favorite detail / settings drawer on direct navigation\n- Refetch after a ranking change to display server state\n\n## Migration from /v1\n\n/v1 had no `GET /v1/favorites/:id` endpoint — single-row reads required going through the full list. /v2 adds it so cache writers can refetch one row after an optimistic mutation."}},"patch":{"tags":["favorites"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"ranking":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"favoriteId","required":true}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"favorite":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"group_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"view_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"contact_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"ranking":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"created_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"updated_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"groups":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"views":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"contacts":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}}},"required":["id","created_at","updated_at"],"additionalProperties":false}},"required":["favorite"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"updateFavoriteV2","summary":"Update a favorite (v2)","description":"Partial update of a favorite. Only `ranking` is mutable — the polymorphic target (group / view / contact) is fixed once the row is created. **Requires `Idempotency-Key`.** Returns `{ data: { favorite: {...} } }`.","x-mint":{"content":"## Use cases\n\n- Reorder a single favorite\n- Clear the ranking on a favorite (pass `null`)\n\n## Migration from /v1\n\n/v1 used `PUT /v1/favorites/:id`. /v2 uses `PATCH` because the body is a partial update."}},"delete":{"tags":["favorites"],"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"favoriteId","required":true}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"affected":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"ids":{"type":"array","items":{"type":"string"}},"failed":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","error"],"additionalProperties":false}}},"required":["affected"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"deleteFavoriteV2","summary":"Delete a favorite (v2)","description":"Unstar a group, view, or contact by deleting the favorite row. Returns the canonical bulk envelope: `{ data: { affected: 1, ids: [favoriteId] } }`. `Idempotency-Key` is optional.","x-mint":{"content":"## Use cases\n\n- Unstar a view from the view tab menu\n- Remove a stale favorite pointing at a deleted contact\n\n## Migration from /v1\n\n/v1 returned `{ error: false, message: \"Favorite deleted successfully\" }` and supported the item-keyed convenience routes `DELETE /v1/favorites/group/:groupId` and `DELETE /v1/favorites/view/:viewId`. /v2 standardizes on the canonical bulk envelope; the convenience routes are no longer needed because the favorites collection on the client knows which favorite row a target maps to.\n\n## Single vs. bulk envelope\n\nResponse uses the same shape as the bulk delete endpoint so cache-invalidation logic can be uniform across single and bulk deletes."}}},"/v2/favorites/":{"get":{"tags":["favorites"],"parameters":[{"schema":{"type":"string","enum":["group","view","contact"]},"in":"query","name":"type","required":false},{"schema":{"type":"object","properties":{"ranking":{}},"additionalProperties":false},"in":"query","name":"orderBy","required":false},{"schema":{"type":"integer","minimum":1,"maximum":9007199254740991},"in":"query","name":"take","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"cursor","required":false}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"favorites":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"group_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"view_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"contact_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"ranking":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"created_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"updated_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"groups":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"views":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"contacts":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}}},"required":["id","created_at","updated_at"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"nextCursor":{"nullable":true,"type":"string"},"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"additionalProperties":false}},"required":["favorites"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"listFavoritesV2","summary":"List favorites (v2)","description":"List all of the authenticated user's favorites across groups, views, and contacts. Returns `{ data: { favorites: [...], pagination: { nextCursor, count } } }`. Supports `?take=`, `?cursor=`, and `?orderBy[ranking]=asc|desc`.","x-mint":{"content":"## Use cases\n\n- Populate the favorites strip in the sidebar\n- Hydrate a TanStack DB collection on initial load\n- Render the \"starred\" pseudo-tab\n\n## Migration from /v1\n\n/v1 returned `{ error: false, data: { items: [...], nextCursor } }`. /v2 uses the canonical envelope: `{ data: { favorites: [...], pagination: { nextCursor, count } } }` — entity plural at the top level, pagination namespaced."}},"post":{"tags":["favorites"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"group_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"view_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"contact_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"ranking":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"additionalProperties":false}}}},"responses":{"201":{"description":"Created","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"favorite":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"group_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"view_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"contact_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"ranking":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"created_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"updated_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"groups":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"views":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"contacts":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}}},"required":["id","created_at","updated_at"],"additionalProperties":false}},"required":["favorite"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"createFavoriteV2","summary":"Create a favorite (v2)","description":"Star a group, view, or contact. Body must include **exactly one** of `group_id`, `view_id`, or `contact_id`. `ranking` is optional. **Requires `Idempotency-Key`.** Returns `{ data: { favorite: {...} } }` with status 201.","x-mint":{"content":"## Use cases\n\n- Star a view from the view tab menu\n- Star a contact from the profile page\n- Pin a group to the sidebar\n\n## Migration from /v1\n\n/v1 used `POST /v1/favorites/` with the same body. /v2 wraps the response in the canonical envelope and requires an `Idempotency-Key` so optimistic mutations from TanStack DB can safely retry.\n\n## Idempotency\n\nGenerate one UUID per logical create operation and reuse it on every retry. TanStack DB collections pass `mutationId` directly."}}},"/v2/favorites/count":{"get":{"tags":["favorites"],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["count"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"countFavoritesV2","summary":"Count favorites (v2)","description":"Return the count of the authenticated user's favorites. Cheap path for a sidebar badge / quota check without loading the full list.","x-mint":{"content":"## Use cases\n\n- Sidebar badge counts\n- Quota enforcement before showing a \"create favorite\" CTA"}}},"/v2/favorites/batch":{"post":{"tags":["favorites"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"favorites":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"object","properties":{"group_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"view_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"contact_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"ranking":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"additionalProperties":false}}},"required":["favorites"],"additionalProperties":false}}}},"responses":{"201":{"description":"Created","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"favorites":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"group_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"view_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"contact_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"ranking":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"created_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"updated_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"groups":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"views":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"contacts":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}}},"required":["id","created_at","updated_at"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"nextCursor":{"nullable":true,"type":"string"},"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"additionalProperties":false}},"required":["favorites"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"batchCreateFavoritesV2","summary":"Bulk-create favorites (v2)","description":"Create multiple favorites in a single request. Each entry must include exactly one of `group_id`, `view_id`, or `contact_id`. Returns `{ data: { favorites: [...] } }` with status 201. **Requires `Idempotency-Key`.**","x-mint":{"content":"## Use cases\n\n- Migration tooling that recreates a user's favorites set\n- Template-driven provisioning\n\n## Idempotency\n\nGenerate one UUID per logical batch operation and reuse it on every retry. Retrying with the same key replays the original response."}}},"/v2/favorites/batch-update":{"post":{"tags":["favorites"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"updates":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"object","properties":{"favoriteId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"data":{"type":"object","properties":{"ranking":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"additionalProperties":false}},"required":["favoriteId","data"],"additionalProperties":false}}},"required":["updates"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"affected":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"ids":{"type":"array","items":{"type":"string"}},"failed":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","error"],"additionalProperties":false}}},"required":["affected"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"batchUpdateFavoritesV2","summary":"Bulk-update favorites (v2)","description":"Apply per-row partial updates (typically `ranking` reorderings) to multiple favorites in a single request. Uses `Promise.allSettled` semantics: a 200 response can carry per-row failures in `data.failed[]`. **Requires `Idempotency-Key`.**","x-mint":{"content":"## Use cases\n\n- Drag-to-reorder favorites in the sidebar — rewrite every `ranking` to its new index in one batched roundtrip\n\n## Migration from /v1\n\n/v1 used `POST /v1/favorites/batch-update` with a flat `{ favoriteId, ranking }` body and returned `{ data: { favorites: [...] } }`. /v2 uses `{ favoriteId, data: { ranking } }` (mirroring contacts/views) and the canonical bulk envelope — surfaces successful IDs and per-row failures."}}},"/v2/favorites/batch-delete":{"post":{"tags":["favorites"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"favoriteIds":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"required":["favoriteIds"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"affected":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"ids":{"type":"array","items":{"type":"string"}},"failed":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","error"],"additionalProperties":false}}},"required":["affected"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"batchDeleteFavoritesV2","summary":"Bulk-delete favorites (v2)","description":"Permanently delete multiple favorites in a single request. Returns `{ data: { affected, ids } }`. `Idempotency-Key` is optional.","x-mint":{"content":"## Use cases\n\n- Bulk-unstar a multi-selection of favorites\n- Cleanup tooling\n\n## Migration from /v1\n\n/v1 had no bulk-delete endpoint — callers had to call `DELETE /v1/favorites/:id` per row. /v2 adds one in line with contacts/views for consistency."}}},"/v2/groups/{groupId}":{"get":{"tags":["groups"],"parameters":[{"schema":{"type":"object","properties":{"parent_group":{"type":"boolean"},"sub_groups":{"type":"boolean"},"sub_groups_name_order":{},"contacts_count":{"type":"boolean"},"sub_groups_count":{"type":"boolean"},"is_favorite":{"type":"boolean"}},"additionalProperties":false},"in":"query","name":"include","required":false},{"schema":{"type":"object","properties":{"parent_group":{"type":"boolean"},"sub_groups":{"type":"boolean"},"sub_groups_name_order":{},"contacts_count":{"type":"boolean"},"sub_groups_count":{"type":"boolean"},"is_favorite":{"type":"boolean"}},"additionalProperties":{"type":"boolean"}},"in":"query","name":"select","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"groupId","required":true}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"group":{"$ref":"#/definitions/__schema0"}},"required":["group"],"additionalProperties":false}},"required":["data"],"additionalProperties":false,"definitions":{"__schema0":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"name":{"type":"string"},"emoji":{"type":"string"},"description":{"nullable":true,"type":"string"},"parent_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"ranking":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"created_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"is_favorite":{"type":"boolean"},"sub_groups":{"type":"array","items":{"$ref":"#/definitions/__schema0"}},"parent_groups":{"nullable":true,"allOf":[{"$ref":"#/definitions/__schema0"}]},"_count":{"type":"object","properties":{"groups_contacts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"sub_groups":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["groups_contacts"],"additionalProperties":false}},"required":["id"],"additionalProperties":false}}}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getGroupV2","summary":"Get a group (v2)","description":"Retrieve a single group by its unique ID. Returns the canonical envelope: `{ data: { group: {...} } }`. Pass `?include[is_favorite]=true` to inflate the response with a computed `is_favorite` boolean, or `?include[parent_group]=true` / `?include[sub_groups]=true` to hydrate the parent / children relations.","x-mint":{"content":"## Use cases\n\n- Hydrate a group detail page on direct navigation\n- Refetch after a mutation to display server state\n\n## Migration from /v1\n\n/v1 returned `{ error: false, data: { group: {...} } }`. /v2 drops the `error` field (HTTP status is the source of truth) and uses `{ data: { group: {...} } }`."}},"patch":{"tags":["groups"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"group":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"emoji":{"type":"string"},"description":{"type":"string"},"parent_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]},"parent":{}},"additionalProperties":false}},"required":["group"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"groupId","required":true},{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","minLength":8,"maxLength":255,"pattern":"^[\\w\\-:.]+$","example":"01HV8N6X7K3P9Q5R2T4Y6W8Z0A"},"description":"Required. UUID per logical operation, reused on every retry. See `apps/rest-api/src/shared/idempotency.ts` for the full contract. Missing → 400 BadRequest; same key + different body → 409 Conflict."}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"group":{"$ref":"#/definitions/__schema0"}},"required":["group"],"additionalProperties":false}},"required":["data"],"additionalProperties":false,"definitions":{"__schema0":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"name":{"type":"string"},"emoji":{"type":"string"},"description":{"nullable":true,"type":"string"},"parent_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"ranking":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"created_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"is_favorite":{"type":"boolean"},"sub_groups":{"type":"array","items":{"$ref":"#/definitions/__schema0"}},"parent_groups":{"nullable":true,"allOf":[{"$ref":"#/definitions/__schema0"}]},"_count":{"type":"object","properties":{"groups_contacts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"sub_groups":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["groups_contacts"],"additionalProperties":false}},"required":["id"],"additionalProperties":false}}}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"updateGroupV2","summary":"Update a group (v2)","description":"Partial update of a group. Send only the fields that change (`name`, `emoji`, `description`, `parent_id`). **Requires `Idempotency-Key`.** Returns `{ data: { group: {...} } }`.","x-mint":{"content":"## Use cases\n\n- Rename a group\n- Re-parent a group (set or clear `parent_id`)\n- Change a group emoji or description\n\n## Migration from /v1\n\n/v1 used `PUT /v1/groups/:groupId`. /v2 uses `PATCH` because the body is a partial update, not a full resource replacement."}},"delete":{"tags":["groups"],"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"groupId","required":true},{"in":"header","name":"Idempotency-Key","required":false,"schema":{"type":"string","minLength":8,"maxLength":255,"pattern":"^[\\w\\-:.]+$","example":"01HV8N6X7K3P9Q5R2T4Y6W8Z0A"},"description":"Optional. Accepted to dedupe retries on this endpoint. See `apps/rest-api/src/shared/idempotency.ts`."}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"affected":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"ids":{"type":"array","items":{"type":"string"}},"failed":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","error"],"additionalProperties":false}}},"required":["affected"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"deleteGroupV2","summary":"Delete a group (v2)","description":"Permanently delete a group. The contacts in the group are NOT deleted — only their `groups_contacts` membership rows and the group itself are removed. Returns the canonical bulk envelope: `{ data: { affected: 1, ids: [groupId] } }`. `Idempotency-Key` is optional.","x-mint":{"content":"## Use cases\n\n- Remove a group that is no longer needed\n- Clean up empty or unused groups\n\n## Single vs. bulk envelope\n\nResponse uses the same shape as the bulk delete endpoint so cache-invalidation logic can be uniform across single and bulk deletes.\n\nDeleting a group does not delete the contacts in it. The contacts remain in your account and can still be found in other groups or the main contact list."}}},"/v2/groups/":{"get":{"tags":["groups"],"parameters":[{"schema":{"type":"object","properties":{"name":{},"number_of_contacts":{}},"additionalProperties":false},"in":"query","name":"orderBy","required":false},{"schema":{"type":"object","properties":{"has_subgroups":{"type":"boolean"},"has_parent":{"type":"boolean"},"has_name":{"type":"string","minLength":1,"maxLength":100},"not_in":{"type":"array","items":{"type":"string"}}},"additionalProperties":false},"in":"query","name":"where","required":false},{"schema":{"type":"object","properties":{"parent_group":{"type":"boolean"},"sub_groups":{"type":"boolean"},"sub_groups_name_order":{},"contacts_count":{"type":"boolean"},"sub_groups_count":{"type":"boolean"},"is_favorite":{"type":"boolean"}},"additionalProperties":false},"in":"query","name":"include","required":false},{"schema":{"type":"object","properties":{"parent_group":{"type":"boolean"},"sub_groups":{"type":"boolean"},"sub_groups_name_order":{},"contacts_count":{"type":"boolean"},"sub_groups_count":{"type":"boolean"},"is_favorite":{"type":"boolean"}},"additionalProperties":{"type":"boolean"}},"in":"query","name":"select","required":false},{"schema":{"type":"integer","minimum":1,"maximum":9007199254740991},"in":"query","name":"take","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"cursor","required":false}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"groups":{"type":"array","items":{"$ref":"#/definitions/__schema0"}},"pagination":{"type":"object","properties":{"nextCursor":{"nullable":true,"type":"string"},"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"additionalProperties":false}},"required":["groups"],"additionalProperties":false}},"required":["data"],"additionalProperties":false,"definitions":{"__schema0":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"name":{"type":"string"},"emoji":{"type":"string"},"description":{"nullable":true,"type":"string"},"parent_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"ranking":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"created_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"is_favorite":{"type":"boolean"},"sub_groups":{"type":"array","items":{"$ref":"#/definitions/__schema0"}},"parent_groups":{"nullable":true,"allOf":[{"$ref":"#/definitions/__schema0"}]},"_count":{"type":"object","properties":{"groups_contacts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"sub_groups":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["groups_contacts"],"additionalProperties":false}},"required":["id"],"additionalProperties":false}}}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"listGroupsV2","summary":"List groups (v2)","description":"List all of the authenticated user's groups. Returns the canonical list envelope: `{ data: { groups: [...] } }`. Supports `?orderBy[name]=asc|desc` and `?orderBy[number_of_contacts]=asc|desc`, plus `?where[has_parent]=true` / `?where[has_subgroups]=true` for sidebar tree navigation.","x-mint":{"content":"## Use cases\n\n- Populate the sidebar list of groups\n- Hydrate a TanStack DB collection on initial load\n\n## Migration from /v1\n\n/v1 returned `{ error: false, data: { groups: [...] } }`. /v2 uses `{ data: { groups: [...] } }`. Pagination is not surfaced — the sidebar consumer fetches the full set; large group counts are uncommon for the personal-CRM use case."}},"post":{"tags":["groups"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"group":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"emoji":{"type":"string"},"description":{"type":"string"},"parent_id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}]},"parent":{},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"groups_contacts":{"type":"array","items":{"type":"object","properties":{"contact_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"contact":{}},"required":["contact_id"],"additionalProperties":false}}},"required":["name"],"additionalProperties":false}},"required":["group"],"additionalProperties":false}}}},"responses":{"201":{"description":"Created","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"group":{"$ref":"#/definitions/__schema0"}},"required":["group"],"additionalProperties":false}},"required":["data"],"additionalProperties":false,"definitions":{"__schema0":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"name":{"type":"string"},"emoji":{"type":"string"},"description":{"nullable":true,"type":"string"},"parent_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"ranking":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"created_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"is_favorite":{"type":"boolean"},"sub_groups":{"type":"array","items":{"$ref":"#/definitions/__schema0"}},"parent_groups":{"nullable":true,"allOf":[{"$ref":"#/definitions/__schema0"}]},"_count":{"type":"object","properties":{"groups_contacts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"sub_groups":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["groups_contacts"],"additionalProperties":false}},"required":["id"],"additionalProperties":false}}}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"createGroupV2","summary":"Create a group (v2)","description":"Create ONE group. Accepts `name`, `emoji`, `description`, `parent_id` (for nested groups), and an optional `groups_contacts` array to add starter members. **Requires `Idempotency-Key`.** Returns `{ data: { group: {...} } }` with status 201.","x-mint":{"content":"## Use cases\n\n- Let users create custom groups to organize their contacts\n- Programmatically create groups during data import\n- Set up default groups for new users during onboarding\n\n## Migration from /v1\n\n/v1 used `POST /v1/groups/` with the same `{ group }` body. /v2 adds required idempotency: retries (network blip, mobile-app suspend/resume) now dedupe server-side instead of creating duplicate groups when the unique-constraint race is lost.\n\n## Idempotency\n\nGenerate one UUID per logical create operation and reuse it on every retry. TanStack DB collections pass `mutationId` directly."},"parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","minLength":8,"maxLength":255,"pattern":"^[\\w\\-:.]+$","example":"01HV8N6X7K3P9Q5R2T4Y6W8Z0A"},"description":"Required. UUID per logical operation, reused on every retry. See `apps/rest-api/src/shared/idempotency.ts` for the full contract. Missing → 400 BadRequest; same key + different body → 409 Conflict."}]}},"/v2/groups/count":{"get":{"tags":["groups"],"parameters":[{"schema":{"type":"object","properties":{"has_subgroups":{"type":"boolean"},"has_parent":{"type":"boolean"},"has_name":{"type":"string","minLength":1,"maxLength":100},"not_in":{"type":"array","items":{"type":"string"}}},"additionalProperties":false},"in":"query","name":"where","required":false}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["count"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"countGroupsV2","summary":"Count groups (v2)","description":"Return the count of the authenticated user's groups. Cheap path for a sidebar badge / quota check without loading the full list.","x-mint":{"content":"## Use cases\n\n- Sidebar badge counts\n- Quota enforcement before showing a \"create group\" CTA"}}},"/v2/groups/contact-counts":{"get":{"tags":["groups"],"parameters":[{"schema":{"type":"string"},"in":"query","name":"groupIds","required":false}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"counts":{"type":"object","additionalProperties":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}}},"required":["counts"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getGroupContactCountsV2","summary":"Get contact counts per group (v2)","description":"Return the contact count for each group in one round-trip. Pass `?groupIds=a,b,c` to scope the query to specific groups; omit it to fetch counts for every group the user owns. Returns `{ data: { counts: { [groupId]: number } } }`.","x-mint":{"content":"## Use cases\n\n- Display contact counts next to group names in the sidebar\n- Detect empty groups for cleanup tooling\n\n## Why a domain-specific envelope\n\nThe payload is a `Record` map rather than an entity body, so it does not fit the canonical entity envelope. The shape is documented as a one-off — every group endpoint that returns groups uses `{ data: { group(s): ... } }`."}}},"/v2/groups/{groupId}/contacts":{"get":{"tags":["groups"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":9007199254740991},"in":"query","name":"take","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"cursor","required":false},{"schema":{"type":"object","properties":{"linkedin_data":{"type":"boolean"},"groups_count":{"type":"boolean"},"coordinates":{"type":"boolean"}},"additionalProperties":{"type":"boolean"}},"in":"query","name":"include","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"groupId","required":true}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"contacts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"first_name":{"nullable":true,"type":"string"},"last_name":{"nullable":true,"type":"string"},"full_name":{"nullable":true,"type":"string"},"description":{"nullable":true,"type":"string"},"job_title":{"nullable":true,"type":"string"},"company":{"nullable":true,"type":"string"},"education":{"nullable":true,"type":"string"},"legacy_location":{"nullable":true,"type":"string"},"image_url":{"nullable":true,"type":"string"},"business_card_url":{"nullable":true,"type":"string"},"website":{"nullable":true,"type":"string"},"image_source":{"nullable":true,"type":"string"},"birthday":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"birthday_year":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"linkedin":{"nullable":true,"type":"string"},"twitter":{"nullable":true,"type":"string"},"facebook":{"nullable":true,"type":"string"},"instagram":{"nullable":true,"type":"string"},"telegram":{"nullable":true,"type":"string"},"tiktok":{"nullable":true,"type":"string"},"youtube":{"nullable":true,"type":"string"},"starred":{"type":"boolean"},"is_archived":{"type":"boolean"},"ignore_merge":{"type":"boolean"},"never_keep_in_touch":{"type":"boolean"},"source":{"type":"string"},"priority_tier":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"frequency":{"nullable":true,"type":"string"},"frequency_text":{"nullable":true,"type":"string"},"last_seen_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"last_reminder_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"next_reminder_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"first_met_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"first_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_companies":{"nullable":true,"type":"string"},"linkedin_education":{"nullable":true,"type":"string"},"linkedin_enhance_date":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_last_message_snippet":{"nullable":true,"type":"string"},"linkedin_message_link":{"nullable":true,"type":"string"},"whatsapp_message_link":{"nullable":true,"type":"string"},"whatsapp_message_snippet":{"nullable":true,"type":"string"},"whatsapp_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"imessage_message_link":{"nullable":true,"type":"string"},"imessage_message_snippet":{"nullable":true,"type":"string"},"imessage_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"instagram_message_link":{"nullable":true,"type":"string"},"instagram_message_snippet":{"nullable":true,"type":"string"},"instagram_last_message_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"gmail_last_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"gmail_last_interaction_provider":{"nullable":true,"type":"string","enum":["GOOGLE","OFFICE365"]},"gmail_last_interaction_provider_id":{"nullable":true,"type":"string"},"gmail_last_interaction_subject":{"nullable":true,"type":"string"},"gcal_last_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"gcal_last_interaction_provider":{"nullable":true,"type":"string","enum":["GOOGLE","OFFICE365"]},"gcal_last_interaction_provider_id":{"nullable":true,"type":"string"},"gcal_last_interaction_title":{"nullable":true,"type":"string"},"phone_call_interaction_snippet":{"nullable":true,"type":"string"},"phone_call_last_interaction_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"web_search_summary":{"nullable":true},"created_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"updated_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"geocode_attempts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"geocode_failed_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"_count":{"type":"object","properties":{"groups_contacts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["groups_contacts"],"additionalProperties":false},"frequency_interval":{},"linkedin_data":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"latitude":{"nullable":true,"type":"number"},"longitude":{"nullable":true,"type":"number"},"contact_emails":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_phone_numbers":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_birthdays":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"contact_locations":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contacts_custom_fields":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"legacy_contact_addresses":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"groups_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"tags_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"timeline_items_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"reminders_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_relations_contact_relations_sourceTocontacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"contact_relations_contact_relations_destinationTocontacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"feed_items":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"keep_in_touch_reminders":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}}},"required":["id"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"nextCursor":{"nullable":true,"type":"string"},"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"additionalProperties":false}},"required":["contacts"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"listGroupContactsV2","summary":"List contacts in a group (v2)","description":"Retrieve contacts in a group. Email and phone relations are omitted by default; request them with `?include[contact_emails]=true` or `?include[contact_phone_numbers]=true`.","x-mint":{"content":"## Use cases\n\n- Display the contact list for a selected group\n- Export contacts from a specific group\n\n## Related data\n\nRelations are omitted unless requested. Add `?include[contact_emails]=true` for email addresses or `?include[contact_phone_numbers]=true` for phone numbers. Both can be requested together.\n\n## Envelope choice\n\nResponse uses `ContactEnvelopes.list` (NOT the group envelope) so callers reuse one TanStack DB collection schema for \"contacts in a group\" and \"all contacts\"."}},"post":{"tags":["groups"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contactIds":{"minItems":1,"maxItems":500,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"required":["contactIds"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"groupId","required":true},{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","minLength":8,"maxLength":255,"pattern":"^[\\w\\-:.]+$","example":"01HV8N6X7K3P9Q5R2T4Y6W8Z0A"},"description":"Required. UUID per logical operation, reused on every retry. See `apps/rest-api/src/shared/idempotency.ts` for the full contract. Missing → 400 BadRequest; same key + different body → 409 Conflict."}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"affected":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"ids":{"type":"array","items":{"type":"string"}},"failed":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","error"],"additionalProperties":false}}},"required":["affected"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"addContactsToGroupV2","summary":"Add contacts to a group (v2)","description":"Add one or more contacts to a group by providing an array of contact IDs. Contacts that are already members are silently skipped server-side. **Requires `Idempotency-Key`.** Returns `{ data: { affected, ids } }` where `affected` is the count of NEW memberships created and `ids` echoes the input contact IDs.","x-mint":{"content":"## Use cases\n\n- Let users drag-and-drop contacts into a group\n- Bulk-add contacts after filtering or searching\n- Automatically organize imported contacts into groups\n\n## Migration from /v1\n\n/v1 used `PUT /v1/groups/:groupId/contacts` for add (and `POST` on the same URL for remove — confusing). /v2 separates the two ops: `POST /:groupId/contacts` adds, `POST /:groupId/contacts/batch-remove` removes.\n\n## Idempotency\n\nRetries without an idempotency key would re-execute `createMany skipDuplicates: true` — safe semantically but wasteful. Required key dedupes the whole op."}}},"/v2/groups/{groupId}/merge":{"post":{"tags":["groups"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sourceGroupIds":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"finalName":{"type":"string","minLength":1,"maxLength":100},"finalEmoji":{"type":"string","minLength":1}},"required":["sourceGroupIds","finalName","finalEmoji"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"groupId","required":true},{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","minLength":8,"maxLength":255,"pattern":"^[\\w\\-:.]+$","example":"01HV8N6X7K3P9Q5R2T4Y6W8Z0A"},"description":"Required. UUID per logical operation, reused on every retry. See `apps/rest-api/src/shared/idempotency.ts` for the full contract. Missing → 400 BadRequest; same key + different body → 409 Conflict."}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"group":{"$ref":"#/definitions/__schema0"},"mergedGroupIds":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"reparentedGroupIds":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"contactIds":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"movedViewIds":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"deletedFavoriteIds":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"deletedShareLinkIds":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"required":["group","mergedGroupIds","reparentedGroupIds","contactIds","movedViewIds","deletedFavoriteIds","deletedShareLinkIds"],"additionalProperties":false}},"required":["data"],"additionalProperties":false,"definitions":{"__schema0":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"name":{"type":"string"},"emoji":{"type":"string"},"description":{"nullable":true,"type":"string"},"parent_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"ranking":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"created_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"is_favorite":{"type":"boolean"},"sub_groups":{"type":"array","items":{"$ref":"#/definitions/__schema0"}},"parent_groups":{"nullable":true,"allOf":[{"$ref":"#/definitions/__schema0"}]},"_count":{"type":"object","properties":{"groups_contacts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"sub_groups":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["groups_contacts"],"additionalProperties":false}},"required":["id"],"additionalProperties":false}}}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"mergeGroupsV2","summary":"Merge groups (v2)","description":"Merge one or more source groups into the group identified by `groupId`. The destination keeps its ID, receives the final name, emoji, and de-duplicated union of contact memberships, while selected source groups are deleted. Direct subgroups are reparented under the destination and source-linked saved views are retargeted. **Requires `Idempotency-Key`.**","x-mint":{"content":"## Use cases\n\n- Consolidate overlapping groups without duplicating contacts\n- Preserve stable group pointers while reorganizing hierarchy\n- Rename and re-emoji the surviving group in the same atomic operation\n\n## Transaction semantics\n\nThe entire merge is atomic: contact memberships are copied with duplicate skipping, hierarchy and saved-view pointers are updated, source groups are deleted, and the destination identity is updated. A failure rolls back every step. Contacts themselves are never deleted.\n\n## Response\n\nReturns the surviving `group` plus `mergedGroupIds`, `reparentedGroupIds`, `contactIds`, `movedViewIds`, `deletedFavoriteIds`, and `deletedShareLinkIds` so normalized clients can reconcile every affected collection without a full refetch."}}},"/v2/groups/batch-delete":{"post":{"tags":["groups"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"groupIds":{"minItems":1,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"required":["groupIds"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"affected":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"ids":{"type":"array","items":{"type":"string"}},"failed":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","error"],"additionalProperties":false}}},"required":["affected"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"batchDeleteGroupsV2","summary":"Bulk-delete groups (v2)","description":"Permanently delete multiple groups in a single request. Uses `Promise.allSettled` semantics: a 200 response can carry per-row failures in `data.failed[]` so cache writers can invalidate just the rows that succeeded. `Idempotency-Key` is optional. Returns `{ data: { affected, ids, failed? } }`.","x-mint":{"content":"## Use cases\n\n- Remove a multi-selection of groups\n- Cleanup tooling\n\n## Partial failure\n\nEach group delete is a batched cascade (`groups_contacts` rows → `favorites` rows → the group row). A failure on one group does not block the others — the response surfaces successes in `ids[]` and failures in `failed[]` with the offending groupId and a structured `{ code, message }`.\n\nThis is a destructive operation. Deleted groups cannot be recovered."},"parameters":[{"in":"header","name":"Idempotency-Key","required":false,"schema":{"type":"string","minLength":8,"maxLength":255,"pattern":"^[\\w\\-:.]+$","example":"01HV8N6X7K3P9Q5R2T4Y6W8Z0A"},"description":"Optional. Accepted to dedupe retries on this endpoint. See `apps/rest-api/src/shared/idempotency.ts`."}]}},"/v2/groups/{groupId}/contacts/batch-remove":{"post":{"tags":["groups"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contactIds":{"minItems":1,"maxItems":500,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"required":["contactIds"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"groupId","required":true},{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","minLength":8,"maxLength":255,"pattern":"^[\\w\\-:.]+$","example":"01HV8N6X7K3P9Q5R2T4Y6W8Z0A"},"description":"Required. UUID per logical operation, reused on every retry. See `apps/rest-api/src/shared/idempotency.ts` for the full contract. Missing → 400 BadRequest; same key + different body → 409 Conflict."}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"affected":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"ids":{"type":"array","items":{"type":"string"}},"failed":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","error"],"additionalProperties":false}}},"required":["affected"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"removeContactsFromGroupV2","summary":"Remove contacts from a group (v2)","description":"Remove one or more contacts from a group. The contacts themselves are NOT deleted — only their `groups_contacts` membership rows are removed. **Requires `Idempotency-Key`.** Returns `{ data: { affected, ids } }` where `affected` is the count of rows actually deleted and `ids` echoes the input contact IDs.","x-mint":{"content":"## Use cases\n\n- Let users remove contacts from a group via the UI\n- Clean up group membership after a reorganization\n\n## Migration from /v1\n\n/v1 overloaded `POST /v1/groups/:groupId/contacts` for remove (same URL as add, different verb). /v2 uses an explicit verb-suffix URL: `/contacts/batch-remove`. POST-with-body (not DELETE-with-body) because DELETE bodies are HTTP-spec-discouraged and some proxies strip them.\n\nRemoving a contact from a group does not delete the contact. It only removes the association between the contact and this group."}}},"/v2/timeline/notes":{"post":{"tags":["timeline"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"object","properties":{"note":{"type":"string","maxLength":50000},"custom_emoji":{"type":"string"},"event_time":{},"meeting_type":{"anyOf":[{"type":"string","enum":["call","coffee","email","meal","meeting","networking","note","other","party","text"]},{"type":"null"}]},"meeting_type_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"meeting_types":{},"attachments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"url":{"type":"string","format":"uri"},"file_name":{"type":"string"},"file_size":{"type":"number"}},"required":["url","file_name"],"additionalProperties":false}},"timeline_items_contacts":{"type":"array","items":{"type":"object","properties":{"contact_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"contacts":{}},"required":["contact_id"],"additionalProperties":false}},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"google_calendar_event_id_v3":{"type":"string"},"oauth_credential_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"reminder_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["event_time"],"additionalProperties":false}},"required":["note"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"object","properties":{"timeline_items_contacts":{"type":"boolean"},"attachments":{"type":"boolean"}},"additionalProperties":false},"in":"query","name":"include","required":false},{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","minLength":8,"maxLength":255,"pattern":"^[\\w\\-:.]+$","example":"01HV8N6X7K3P9Q5R2T4Y6W8Z0A"},"description":"Required. UUID per logical operation, reused on every retry. See `apps/rest-api/src/shared/idempotency.ts` for the full contract. Missing → 400 BadRequest; same key + different body → 409 Conflict."}],"responses":{"201":{"description":"Created","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"note":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"note":{"nullable":true,"type":"string"},"custom_emoji":{"nullable":true,"type":"string"},"meeting_type":{"nullable":true,"type":"string"},"meeting_type_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"event_time":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"created_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"google_calendar_event_id_v3":{"nullable":true,"type":"string"},"oauth_credential_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"calendar_account_email":{"nullable":true,"type":"string"},"calendar_account_provider":{"nullable":true,"type":"string","enum":["GOOGLE","OFFICE365"]},"reminder_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"channels":{"type":"array","items":{"type":"string","enum":["whatsapp","imessage","linkedin","instagram"]}},"next_cursor":{"type":"string"},"meeting_types":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"timeline_items_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"attachments":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["id","channels","meeting_types"],"additionalProperties":false}},"required":["note"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"createNoteV2","summary":"Create a note (v2)","description":"Create a note (a `timeline_items` row) optionally linked to contacts. Returns the created note in the canonical single-entity envelope.","x-mint":{"content":"## Use cases\n\n- Capture a note from the dex-webapp timeline composer\n- Log a meeting or interaction against one or more contacts\n\n## Migration from /v1\n\nThe /v1 surface was `POST /v1/timeline` with response `{ error: false, data: { note } }`. /v2 nests note CRUD under `/v2/timeline/notes` and uses the canonical envelope `{ data: { note } }` (no `error: false`).\n\n## Idempotency\n\n`idempotent: required` — pass an `Idempotency-Key` header (UUID per logical operation, reused on retry) so a retried create doesn't duplicate the note."}}},"/v2/timeline/notes/batch":{"post":{"tags":["timeline"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"notes":{"maxItems":500,"type":"array","items":{"type":"object","properties":{"note":{"type":"string","maxLength":50000},"custom_emoji":{"type":"string"},"event_time":{},"meeting_type":{"anyOf":[{"type":"string","enum":["call","coffee","email","meal","meeting","networking","note","other","party","text"]},{"type":"null"}]},"meeting_type_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"meeting_types":{},"attachments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"url":{"type":"string","format":"uri"},"file_name":{"type":"string"},"file_size":{"type":"number"}},"required":["url","file_name"],"additionalProperties":false}},"timeline_items_contacts":{"type":"array","items":{"type":"object","properties":{"contact_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"contacts":{}},"required":["contact_id"],"additionalProperties":false}},"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"google_calendar_event_id_v3":{"type":"string"},"oauth_credential_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"reminder_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["event_time"],"additionalProperties":false}}},"required":["notes"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"object","properties":{"timeline_items_contacts":{"type":"boolean"},"attachments":{"type":"boolean"}},"additionalProperties":false},"in":"query","name":"include","required":false},{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","minLength":8,"maxLength":255,"pattern":"^[\\w\\-:.]+$","example":"01HV8N6X7K3P9Q5R2T4Y6W8Z0A"},"description":"Required. UUID per logical operation, reused on every retry. See `apps/rest-api/src/shared/idempotency.ts` for the full contract. Missing → 400 BadRequest; same key + different body → 409 Conflict."}],"responses":{"201":{"description":"Created","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"notes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"note":{"nullable":true,"type":"string"},"custom_emoji":{"nullable":true,"type":"string"},"meeting_type":{"nullable":true,"type":"string"},"meeting_type_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"event_time":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"created_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"google_calendar_event_id_v3":{"nullable":true,"type":"string"},"oauth_credential_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"calendar_account_email":{"nullable":true,"type":"string"},"calendar_account_provider":{"nullable":true,"type":"string","enum":["GOOGLE","OFFICE365"]},"reminder_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"channels":{"type":"array","items":{"type":"string","enum":["whatsapp","imessage","linkedin","instagram"]}},"next_cursor":{"type":"string"},"meeting_types":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"timeline_items_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"attachments":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["id","channels","meeting_types"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"nextCursor":{"nullable":true,"type":"string"},"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"additionalProperties":false}},"required":["notes"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"batchCreateNotesV2","summary":"Create many notes (v2)","description":"Bulk-create up to 500 notes in one request. Returns the created notes in the canonical list envelope.","x-mint":{"content":"## Use cases\n\n- Import notes from a CSV file\n- Migrate notes from another system\n\n## Idempotency\n\n`idempotent: required` — pass an `Idempotency-Key` header (UUID per logical batch, reused on retry) so a retried import doesn't duplicate every note in the batch."}}},"/v2/timeline/notes/search":{"get":{"tags":["timeline"],"parameters":[{"schema":{"type":"string"},"in":"query","name":"searchQuery","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"contactId","required":false},{"schema":{"type":"string"},"in":"query","name":"startDate","required":false},{"schema":{"type":"string"},"in":"query","name":"endDate","required":false},{"schema":{"type":"integer","minimum":1,"maximum":9007199254740991},"in":"query","name":"take","required":false},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false},{"schema":{"type":"boolean"},"in":"query","name":"includeContactDetails","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"groupId","required":false}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"notes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"note":{"nullable":true,"type":"string"},"custom_emoji":{"nullable":true,"type":"string"},"meeting_type":{"nullable":true,"type":"string"},"meeting_type_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"event_time":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"created_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"google_calendar_event_id_v3":{"nullable":true,"type":"string"},"oauth_credential_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"calendar_account_email":{"nullable":true,"type":"string"},"calendar_account_provider":{"nullable":true,"type":"string","enum":["GOOGLE","OFFICE365"]},"reminder_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"channels":{"type":"array","items":{"type":"string","enum":["whatsapp","imessage","linkedin","instagram"]}},"next_cursor":{"type":"string"},"meeting_types":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"timeline_items_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"attachments":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["id","channels","meeting_types"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"nextCursor":{"nullable":true,"type":"string"},"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"additionalProperties":false}},"required":["notes"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"searchNotesV2","summary":"Search notes (v2)","description":"Full-text search over the notes you own. Matches on the note body and on the names of contacts each note is linked to. Returns the canonical notes list envelope, cursor-paginated.","x-mint":{"content":"## Use cases\n\n- Power a global search across your notes\n- Find every note mentioning a person or topic\n\n## Matching\n\nMatches case-insensitively on the note body (`note`) and on the first/last name of any contact the note is linked to. Results are ordered most-recent-first by event time.\n\n## Pagination\n\nCursor-based. Pass the returned `pagination.nextCursor` back verbatim as `cursor` to fetch the next page; it's opaque (server-emitted) — never parse or construct one client-side. `take` caps the page size.\n\n## Migration from /v1\n\nThe /v1 surface was `GET /v1/search/timeline` returning `{ data, nextCursor }`. /v2 uses the canonical envelope `{ data: { notes, pagination: { nextCursor, count } } }` (no `error: false`)."}}},"/v2/timeline/notes/{noteId}":{"get":{"tags":["timeline"],"parameters":[{"schema":{"type":"object","properties":{"timeline_items_contacts":{"type":"boolean"},"attachments":{"type":"boolean"}},"additionalProperties":false},"in":"query","name":"include","required":false},{"schema":{"type":"object","properties":{"timeline_items_contacts":{"type":"boolean"},"attachments":{"type":"boolean"}},"additionalProperties":{"type":"boolean"}},"in":"query","name":"select","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"noteId","required":true}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"note":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"note":{"nullable":true,"type":"string"},"custom_emoji":{"nullable":true,"type":"string"},"meeting_type":{"nullable":true,"type":"string"},"meeting_type_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"event_time":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"created_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"google_calendar_event_id_v3":{"nullable":true,"type":"string"},"oauth_credential_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"calendar_account_email":{"nullable":true,"type":"string"},"calendar_account_provider":{"nullable":true,"type":"string","enum":["GOOGLE","OFFICE365"]},"reminder_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"channels":{"type":"array","items":{"type":"string","enum":["whatsapp","imessage","linkedin","instagram"]}},"next_cursor":{"type":"string"},"meeting_types":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"timeline_items_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"attachments":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["id","channels","meeting_types"],"additionalProperties":false}},"required":["note"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getNoteV2","summary":"Get a note (v2)","description":"Retrieve a single note by id in the canonical single-entity envelope.","x-mint":{"content":"## Use cases\n\n- Load a note for editing\n- Fetch the latest server state before applying an update"}},"patch":{"tags":["timeline"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"object","properties":{"note":{"type":"string","maxLength":50000},"custom_emoji":{"type":"string"},"event_time":{},"meeting_type":{"anyOf":[{"type":"string","enum":["call","coffee","email","meal","meeting","networking","note","other","party","text"]},{"type":"null"}]},"meeting_type_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"meeting_types":{},"attachments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"url":{"type":"string","format":"uri"},"file_name":{"type":"string"},"file_size":{"type":"number"}},"required":["url","file_name"],"additionalProperties":false}},"timeline_items_contacts":{"type":"array","items":{"type":"object","properties":{"contact_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"contacts":{}},"required":["contact_id"],"additionalProperties":false}},"oauth_credential_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"reminder_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"additionalProperties":false}},"required":["note"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"object","properties":{"timeline_items_contacts":{"type":"boolean"},"attachments":{"type":"boolean"}},"additionalProperties":false},"in":"query","name":"include","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"noteId","required":true},{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","minLength":8,"maxLength":255,"pattern":"^[\\w\\-:.]+$","example":"01HV8N6X7K3P9Q5R2T4Y6W8Z0A"},"description":"Required. UUID per logical operation, reused on every retry. See `apps/rest-api/src/shared/idempotency.ts` for the full contract. Missing → 400 BadRequest; same key + different body → 409 Conflict."}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"note":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"note":{"nullable":true,"type":"string"},"custom_emoji":{"nullable":true,"type":"string"},"meeting_type":{"nullable":true,"type":"string"},"meeting_type_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"event_time":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"created_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"google_calendar_event_id_v3":{"nullable":true,"type":"string"},"oauth_credential_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"calendar_account_email":{"nullable":true,"type":"string"},"calendar_account_provider":{"nullable":true,"type":"string","enum":["GOOGLE","OFFICE365"]},"reminder_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"channels":{"type":"array","items":{"type":"string","enum":["whatsapp","imessage","linkedin","instagram"]}},"next_cursor":{"type":"string"},"meeting_types":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"timeline_items_contacts":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}},"attachments":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["id","channels","meeting_types"],"additionalProperties":false}},"required":["note"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"updateNoteV2","summary":"Update a note (v2)","description":"Partially update a note. PATCH semantics — only the supplied fields change. Returns the updated note.","x-mint":{"content":"## Use cases\n\n- Edit note text, emoji, meeting type, or event time\n\n## Migration from /v1\n\nThe /v1 surface was `PUT /v1/timeline/{noteId}`. /v2 uses `PATCH /v2/timeline/notes/{noteId}` (partial update) with the canonical envelope.\n\n## Idempotency\n\n`idempotent: required` — pass an `Idempotency-Key` header so a retried partial update is replayed rather than re-applied."}},"delete":{"tags":["timeline"],"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"noteId","required":true},{"in":"header","name":"Idempotency-Key","required":false,"schema":{"type":"string","minLength":8,"maxLength":255,"pattern":"^[\\w\\-:.]+$","example":"01HV8N6X7K3P9Q5R2T4Y6W8Z0A"},"description":"Optional. Accepted to dedupe retries on this endpoint. See `apps/rest-api/src/shared/idempotency.ts`."}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"affected":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"ids":{"type":"array","items":{"type":"string"}},"failed":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","error"],"additionalProperties":false}}},"required":["affected"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"deleteNoteV2","summary":"Delete a note (v2)","description":"Delete a note by id. Returns the bulk-ack envelope (`affected`, `ids`).","x-mint":{"content":"## Migration from /v1\n\nThe /v1 surface was `DELETE /v1/timeline/{noteId}` returning `{ error: false, message }`. /v2 returns the canonical bulk-ack `{ data: { affected, ids } }`.\n\n## Idempotency\n\n`idempotent: optional` — passing a key replays the same `affected: 1` on retry instead of `affected: 0`."}}},"/v2/users/me":{"get":{"tags":["users"],"parameters":[{"schema":{"type":"array","items":{"type":"string"}},"in":"query","name":"include","required":false,"description":"Related records to include (e.g. mobile_settings, workflow_settings)"},{"schema":{"type":"boolean"},"in":"query","name":"fresh","required":false,"description":"Skip the cache and fetch the latest data from the database"}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"},"email_key":{"type":"string"},"zapier_key":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"first_name":{"nullable":true,"type":"string"},"last_name":{"nullable":true,"type":"string"},"email_verified":{"type":"boolean"},"image_url":{"nullable":true,"type":"string"},"time_zone":{"type":"string"},"usecase":{"nullable":true,"type":"string"},"onboarded_web":{"type":"boolean"},"onboarded_mobile":{"type":"boolean"},"pricing_plan":{"type":"string"},"credits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"account_visible":{"type":"boolean"},"is_deleted":{"type":"boolean"},"neutered_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"utm_tags":{"nullable":true},"registration_data":{"nullable":true},"linkedin_profile_id":{"nullable":true,"type":"string"},"linkedin_session_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"linkedin_sync_status":{"nullable":true,"type":"string"},"linkedin_profile_data":{"nullable":true},"linkedin_last_sync":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_sync_disabled":{"type":"boolean"},"linkedin_collection_update_requested_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_sync_cookies":{"nullable":true},"linkedin_user_agent":{"nullable":true,"type":"string"},"linkedin_message_sync_enabled":{"nullable":true,"type":"boolean"},"linkedin_message_last_sync":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"linkedin_message_sync_status":{"nullable":true,"type":"string","enum":["needs_auth","initial_sync_in_progress","sync_in_progress","sync_complete","sync_failed"]},"whatsapp_session_id":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"whatsapp_last_sync":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"whatsapp_sync_enabled":{"nullable":true,"type":"boolean"},"whatsapp_sync_status":{"nullable":true,"type":"string","enum":["needs_auth","sync_in_progress","sync_complete","sync_failed","initial_sync_in_progress"]},"imessage_last_sync":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"imessage_sync_enabled":{"nullable":true,"type":"boolean"},"imessage_sync_status":{"nullable":true,"type":"string","enum":["needs_auth","sync_in_progress","sync_complete","sync_failed"]},"instagram_last_sync":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"instagram_sync_enabled":{"nullable":true,"type":"boolean"},"instagram_sync_status":{"nullable":true,"type":"string","enum":["needs_auth","sync_in_progress","sync_complete","sync_failed"]},"instagram_user_agent":{"nullable":true,"type":"string"},"instagram_sync_cookies":{"nullable":true},"instagram_sync_attempt_token":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"instagram_sync_attempt_started_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"facebook_last_sync":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"facebook_sync_enabled":{"nullable":true,"type":"boolean"},"facebook_sync_status":{"nullable":true,"type":"string","enum":["needs_auth","sync_in_progress","sync_complete","sync_failed"]},"facebook_user_agent":{"nullable":true,"type":"string"},"facebook_sync_cookies":{"nullable":true},"facebook_sync_attempt_token":{"nullable":true,"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"facebook_sync_attempt_started_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"phone_calls_last_sync":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"phone_calls_sync_enabled":{"nullable":true,"type":"boolean"},"phone_calls_sync_status":{"nullable":true,"type":"string","enum":["needs_auth","sync_in_progress","sync_complete","sync_failed"]},"sms_assistant_phone_number":{"nullable":true,"type":"string"},"sms_assistant_enabled":{"nullable":true,"type":"boolean"},"sms_assistant_verification_code":{"nullable":true,"type":"string"},"sms_assistant_verification_expires_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"sms_assistant_registered_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"priority_field_label":{"type":"string"},"plan_research_credits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"purchased_research_credits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"plan_research_credits_refreshed_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"research_settings":{"nullable":true},"last_auto_merge_and_fix_at":{"nullable":true,"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"created_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"updated_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"mobile_settings":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"notification_preferences":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"subscription_details":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"workflow_settings":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"sms_settings":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"gamification_achievements":{"nullable":true,"type":"object","properties":{},"additionalProperties":{}},"relationship_priority_tiers":{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}},"required":["id","email"],"additionalProperties":false}},"required":["user"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getCurrentUserV2","summary":"Get the current user (v2)","description":"Retrieve the authenticated user. Supports `include` (related records like `mobile_settings`, `workflow_settings`) and `fresh` (skip cache). Returns the canonical /v2 envelope `{ data: { user } }`.","x-mint":{"content":"## Use cases\n\n- Bootstrap the app shell with the current user profile\n- Fetch the latest profile state before editing\n\n## Migration from /v1\n\nThe /v1 endpoint returns `{ error: false, data: { ...user } }` (user spread directly into `data`). The /v2 endpoint returns `{ data: { user: {...} } }` — namespaced under `data.user`, and no `error` field on success (HTTP status is the source of truth). A missing user now returns 404 instead of `{ data: null }`."}}},"/v2/tags/":{"get":{"tags":["tags"],"parameters":[{"schema":{"type":"object","properties":{"contacts_count":{"type":"boolean"}},"additionalProperties":false},"in":"query","name":"include","required":false},{"schema":{"type":"object","properties":{"contacts_count":{"type":"boolean"}},"additionalProperties":{"type":"boolean"}},"in":"query","name":"select","required":false},{"schema":{"type":"object","properties":{"name":{"type":"string","enum":["asc","desc"]},"contacts_count":{"type":"string","enum":["asc","desc"]}},"additionalProperties":false},"in":"query","name":"orderBy","required":false},{"schema":{"type":"integer","minimum":1,"maximum":9007199254740991},"in":"query","name":"take","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"cursor","required":false}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"name":{"type":"string"},"_count":{"type":"object","properties":{"tags_contacts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["tags_contacts"],"additionalProperties":false}},"required":["id"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"nextCursor":{"nullable":true,"type":"string"},"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"additionalProperties":false}},"required":["tags"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"listTagsV2","summary":"List tags (v2)","description":"List the authenticated user's tags with cursor pagination (`?take=` / `?cursor=`). Pass `?include[contacts_count]=true` to attach `_count.tags_contacts` per tag; sort with `?orderBy[name]=asc|desc` or `?orderBy[contacts_count]=asc|desc`. Returns `{ data: { tags: [...], pagination: { nextCursor } } }`.","x-mint":{"content":"## Use cases\n\n- Populate the tags settings page (sorted by name or contact count, 100 per page)\n- Hydrate a TanStack DB tags collection\n\n## Migration from /v1\n\n/v1 returned `{ error: false, data: { items: [...], nextCursor } }`. /v2 returns `{ data: { tags: [...], pagination: { nextCursor } } }` — entity plural at the top level, pagination namespaced, no `error` field on success."}},"post":{"tags":["tags"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tag":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":99}},"required":["name"],"additionalProperties":false}},"required":["tag"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"object","properties":{"contacts_count":{"type":"boolean"}},"additionalProperties":false},"in":"query","name":"include","required":false},{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","minLength":8,"maxLength":255,"pattern":"^[\\w\\-:.]+$","example":"01HV8N6X7K3P9Q5R2T4Y6W8Z0A"},"description":"Required. UUID per logical operation, reused on every retry. See `apps/rest-api/src/shared/idempotency.ts` for the full contract. Missing → 400 BadRequest; same key + different body → 409 Conflict."}],"responses":{"201":{"description":"Created","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"tag":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"name":{"type":"string"},"_count":{"type":"object","properties":{"tags_contacts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["tags_contacts"],"additionalProperties":false}},"required":["id"],"additionalProperties":false}},"required":["tag"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"createTagV2","summary":"Create a tag (v2)","description":"Create ONE tag. Find-or-create semantics: if a tag with the same name already exists, the existing row is returned instead of a duplicate (tags are unique per user+name). **Requires `Idempotency-Key`.** Returns `{ data: { tag: {...} } }` with status 201.","x-mint":{"content":"## Use cases\n\n- Add a tag from the settings page\n- Create a tag inline from a contact editor\n\n## Migration from /v1\n\nSame `{ tag: { name } }` body as /v1. /v2 adds required idempotency — retries dedupe server-side instead of racing the user+name unique constraint.\n\n## Idempotency\n\nGenerate one UUID per logical create and reuse it on every retry. TanStack DB collections pass `mutationId` directly."}}},"/v2/tags/count":{"get":{"tags":["tags"],"parameters":[{"schema":{"type":"object","properties":{"name":{"type":"string","enum":["asc","desc"]},"contacts_count":{"type":"string","enum":["asc","desc"]}},"additionalProperties":false},"in":"query","name":"orderBy","required":false}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["count"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"countTagsV2","summary":"Count tags (v2)","description":"Return the total count of the authenticated user's tags. Cheap path for the settings header / pagination math without loading the list.","x-mint":{"content":"## Use cases\n\n- Show \"N tags\" in the settings header\n- Compute page counts for the paginated tag list"}}},"/v2/tags/{tagId}":{"get":{"tags":["tags"],"parameters":[{"schema":{"type":"object","properties":{"contacts_count":{"type":"boolean"}},"additionalProperties":false},"in":"query","name":"include","required":false},{"schema":{"type":"object","properties":{"contacts_count":{"type":"boolean"}},"additionalProperties":{"type":"boolean"}},"in":"query","name":"select","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"tagId","required":true}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"tag":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"name":{"type":"string"},"_count":{"type":"object","properties":{"tags_contacts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["tags_contacts"],"additionalProperties":false}},"required":["id"],"additionalProperties":false}},"required":["tag"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getTagV2","summary":"Get a tag (v2)","description":"Retrieve a single tag by its ID. Pass `?include[contacts_count]=true` to attach `_count.tags_contacts`. Returns `{ data: { tag: {...} } }`, or 404 if the tag doesn't exist or belongs to another user.","x-mint":{"content":"## Use cases\n\n- Resolve a tag by id before assigning it to contacts\n- Re-fetch a single tag after an update without reloading the list\n\n## Migration from /v1\n\n/v1 returned `{ error: false, data: {...} }` with the tag at the top of `data`. /v2 nests it under the entity key: `{ data: { tag: {...} } }`.\n\nLookups are scoped to the authenticated user, so another user's tag returns 404 rather than 403."}},"patch":{"tags":["tags"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tag":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":99}},"additionalProperties":false}},"required":["tag"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"tagId","required":true},{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","minLength":8,"maxLength":255,"pattern":"^[\\w\\-:.]+$","example":"01HV8N6X7K3P9Q5R2T4Y6W8Z0A"},"description":"Required. UUID per logical operation, reused on every retry. See `apps/rest-api/src/shared/idempotency.ts` for the full contract. Missing → 400 BadRequest; same key + different body → 409 Conflict."}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"tag":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"name":{"type":"string"},"_count":{"type":"object","properties":{"tags_contacts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["tags_contacts"],"additionalProperties":false}},"required":["id"],"additionalProperties":false}},"required":["tag"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"updateTagV2","summary":"Update a tag (v2)","description":"Partial update (rename) of a tag. **Requires `Idempotency-Key`.** Returns `{ data: { tag: {...} } }`. Renaming to an existing tag name returns 400 (tags are unique per user+name).","x-mint":{"content":"## Use cases\n\n- Rename a tag from the settings page\n\n## Migration from /v1\n\n/v1 used `PUT /v1/tags/:tagId`. /v2 uses `PATCH` because the body is a partial update (PUT semantically means \"replace the resource entirely\"). Same `{ tag: { name } }` body."}},"delete":{"tags":["tags"],"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"tagId","required":true},{"in":"header","name":"Idempotency-Key","required":false,"schema":{"type":"string","minLength":8,"maxLength":255,"pattern":"^[\\w\\-:.]+$","example":"01HV8N6X7K3P9Q5R2T4Y6W8Z0A"},"description":"Optional. Accepted to dedupe retries on this endpoint. See `apps/rest-api/src/shared/idempotency.ts`."}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"affected":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"ids":{"type":"array","items":{"type":"string"}},"failed":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","error"],"additionalProperties":false}}},"required":["affected"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"deleteTagV2","summary":"Delete a tag (v2)","description":"Permanently delete a tag (its contact assignments cascade). Returns the canonical bulk envelope: `{ data: { affected: 1, ids: [tagId] } }`. `Idempotency-Key` is optional.","x-mint":{"content":"## Use cases\n\n- Remove an unused tag from settings\n\nDeleting a tag removes it from every contact it was assigned to. This cannot be undone."}}},"/v2/tags/batch":{"post":{"tags":["tags"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"names":{"minItems":1,"type":"array","items":{"type":"string","minLength":1,"maxLength":99}}},"required":["names"],"additionalProperties":false}}}},"responses":{"201":{"description":"Created","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"name":{"type":"string"},"_count":{"type":"object","properties":{"tags_contacts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["tags_contacts"],"additionalProperties":false}},"required":["id"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"nextCursor":{"nullable":true,"type":"string"},"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"additionalProperties":false},"failed":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["name","error"],"additionalProperties":false}}},"required":["tags"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"batchCreateTagsV2","summary":"Bulk-create tags (v2)","description":"Create multiple tags from a `{ names: [...] }` array. Names are deduplicated; existing tags with the same name are returned rather than duplicated. Skipped names are reported in `data.failed`. **Requires `Idempotency-Key`.** Returns `{ data: { tags: [...], failed?: [...] } }` with status 201.","x-mint":{"content":"## Use cases\n\n- Import a tag list during onboarding or CSV import\n- \"Add several tags\" flows\n\n## Migration from /v1\n\n/v1 (`POST /v1/tags/bulk-create`) took a bare JSON array body. /v2 wraps it: `{ names: [\"vip\", \"investor\"] }` — the envelope leaves room for per-batch metadata without a breaking change."},"parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","minLength":8,"maxLength":255,"pattern":"^[\\w\\-:.]+$","example":"01HV8N6X7K3P9Q5R2T4Y6W8Z0A"},"description":"Required. UUID per logical operation, reused on every retry. See `apps/rest-api/src/shared/idempotency.ts` for the full contract. Missing → 400 BadRequest; same key + different body → 409 Conflict."}]}},"/v2/tags/batch-delete":{"post":{"tags":["tags"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tagIds":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"deleteAll":{"type":"boolean"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"affected":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"ids":{"type":"array","items":{"type":"string"}},"failed":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","error"],"additionalProperties":false}}},"required":["affected"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"batchDeleteTagsV2","summary":"Bulk-delete tags (v2)","description":"Delete multiple tags in one request: `{ tagIds: [...] }`, or `{ deleteAll: true }` to wipe every tag the user owns. **Requires `Idempotency-Key`** (the `deleteAll` arm is never safe to blindly re-execute). Returns `{ data: { affected, ids? } }` — `ids` is omitted on `deleteAll`.","x-mint":{"content":"## Use cases\n\n- Remove a multi-selection of tags from settings\n- \"Delete all tags\" cleanup tooling\n\nThis is a destructive operation. Contact assignments cascade and cannot be recovered."},"parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","minLength":8,"maxLength":255,"pattern":"^[\\w\\-:.]+$","example":"01HV8N6X7K3P9Q5R2T4Y6W8Z0A"},"description":"Required. UUID per logical operation, reused on every retry. See `apps/rest-api/src/shared/idempotency.ts` for the full contract. Missing → 400 BadRequest; same key + different body → 409 Conflict."}]}},"/v2/tags/contacts/add":{"post":{"tags":["tags"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contactIds":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"tagIds":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"required":["contactIds","tagIds"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"affected":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"ids":{"type":"array","items":{"type":"string"}},"failed":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","error"],"additionalProperties":false}}},"required":["affected"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"addTagsToContactsV2","summary":"Assign tags to contacts (v2)","description":"Assign a set of existing tags to a set of contacts (the cartesian product). Body: `{ contactIds: [...], tagIds: [...] }`. **Requires `Idempotency-Key`.** Returns the bulk envelope `{ data: { affected } }` where `affected` is the number of tag↔contact relations created.","x-mint":{"content":"## Use cases\n\n- Tag a multi-selection of contacts from the contacts table\n\n## Migration from /v1\n\nReplaces `POST /v1/tags/add-to-contacts`, which returned the relation rows under `{ error: false, data: { tags } }`. /v2 returns the canonical bulk envelope (relation count).\n\n## Idempotency\n\nRequired — the underlying per-pair upsert re-executes on a blind retry."},"parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","minLength":8,"maxLength":255,"pattern":"^[\\w\\-:.]+$","example":"01HV8N6X7K3P9Q5R2T4Y6W8Z0A"},"description":"Required. UUID per logical operation, reused on every retry. See `apps/rest-api/src/shared/idempotency.ts` for the full contract. Missing → 400 BadRequest; same key + different body → 409 Conflict."}]}},"/v2/tags/contacts/remove":{"post":{"tags":["tags"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contactIds":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"tagIds":{"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"required":["contactIds","tagIds"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"affected":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"ids":{"type":"array","items":{"type":"string"}},"failed":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","error"],"additionalProperties":false}}},"required":["affected"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"removeTagsFromContactsV2","summary":"Remove tags from contacts (v2)","description":"Remove a set of tags from a set of contacts. Body: `{ contactIds: [...], tagIds: [...] }`. **Requires `Idempotency-Key`.** Returns `{ data: { affected } }` where `affected` is the number of tag↔contact relations removed.","x-mint":{"content":"## Use cases\n\n- Untag a multi-selection of contacts from the contacts table\n\n## Migration from /v1\n\nReplaces `POST /v1/tags/remove-from-contacts`, which returned `{ error: false, data: { count } }`. /v2 returns the canonical bulk envelope (relation count under `affected`).\n\n## Idempotency\n\nRequired — the underlying deleteMany re-executes on a blind retry."},"parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","minLength":8,"maxLength":255,"pattern":"^[\\w\\-:.]+$","example":"01HV8N6X7K3P9Q5R2T4Y6W8Z0A"},"description":"Required. UUID per logical operation, reused on every retry. See `apps/rest-api/src/shared/idempotency.ts` for the full contract. Missing → 400 BadRequest; same key + different body → 409 Conflict."}]}},"/v2/tags/contacts/{contactId}/create-assign":{"post":{"tags":["tags"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"tagNames":{"type":"array","items":{"type":"string","minLength":1,"maxLength":99}}},"required":["tagNames"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"contactId","required":true},{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","minLength":8,"maxLength":255,"pattern":"^[\\w\\-:.]+$","example":"01HV8N6X7K3P9Q5R2T4Y6W8Z0A"},"description":"Required. UUID per logical operation, reused on every retry. See `apps/rest-api/src/shared/idempotency.ts` for the full contract. Missing → 400 BadRequest; same key + different body → 409 Conflict."}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"tags":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"name":{"type":"string"},"_count":{"type":"object","properties":{"tags_contacts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["tags_contacts"],"additionalProperties":false}},"required":["id"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"nextCursor":{"nullable":true,"type":"string"},"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"additionalProperties":false}},"required":["tags"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"createAndAssignTagsV2","summary":"Create + assign tags to a contact (v2)","description":"Find-or-create tags by name and assign them to one contact. Body: `{ tagNames: [...] }`. **Requires `Idempotency-Key`.** Returns the resulting tag list: `{ data: { tags: [...] } }` so the client can write the post-state in one pass. 404 if the contact does not belong to the user.","x-mint":{"content":"## Use cases\n\n- Add tags inline from a contact editor, creating any that don't exist yet\n\n## Migration from /v1\n\nReplaces `POST /v1/tags/create-and-assign/:contactId`, which returned `{ error: false, data: { tags } }`. /v2 returns the canonical list envelope.\n\n## Idempotency\n\nRequired — the find-or-create + assign re-executes on a blind retry."}}},"/v2/custom-fields/":{"get":{"tags":["custom-fields"],"parameters":[{"schema":{"type":"object","propertyNames":{},"additionalProperties":{"type":"boolean"}},"in":"query","name":"select","required":false}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"custom_fields":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"name":{"type":"string"},"field_type":{"type":"string"},"categories":{"type":"array","items":{"type":"string"}},"ranking":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"nextCursor":{"nullable":true,"type":"string"},"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"additionalProperties":false}},"required":["custom_fields"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"listCustomFieldsV2","summary":"List custom fields (v2)","description":"List all of the authenticated user's custom field definitions (name, field_type, categories, ranking), ordered by ranking then name. Returns `{ data: { custom_fields: [...] } }` — no pagination (users have a handful of fields).","x-mint":{"content":"## Use cases\n\n- Populate the custom-fields settings page\n- Build the contact-editor field list\n\n## Migration from /v1\n\n/v1 returned `{ error: false, data: { custom_fields: [...] } }`. /v2 drops the `error` field (HTTP status is the source of truth)."}},"post":{"tags":["custom-fields"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"custom_field":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"field_type":{"type":"string","enum":["input","autocomplete","datepicker"]},"categories":{"type":"array","items":{"type":"object","properties":{"category":{"type":"string","minLength":1,"maxLength":100}},"required":["category"],"additionalProperties":false}}},"required":["name","field_type"],"additionalProperties":false}},"required":["custom_field"],"additionalProperties":false}}}},"responses":{"201":{"description":"Created","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"custom_field":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"name":{"type":"string"},"field_type":{"type":"string"},"categories":{"type":"array","items":{"type":"string"}},"ranking":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id"],"additionalProperties":false}},"required":["custom_field"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"createCustomFieldV2","summary":"Create a custom field (v2)","description":"Create ONE custom field definition. Accepts `name`, `field_type` (`input` | `autocomplete` | `datepicker`), and `categories` (autocomplete only, as `[{ category }]`). Ranking is assigned automatically (appended last). **Requires `Idempotency-Key`.** Returns `{ data: { custom_field: {...} } }` with status 201.","x-mint":{"content":"## Use cases\n\n- Add a custom field from settings\n\n## Idempotency\n\nGenerate one UUID per logical create and reuse it on every retry — without it, a retried create would mint duplicate field definitions."},"parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","minLength":8,"maxLength":255,"pattern":"^[\\w\\-:.]+$","example":"01HV8N6X7K3P9Q5R2T4Y6W8Z0A"},"description":"Required. UUID per logical operation, reused on every retry. See `apps/rest-api/src/shared/idempotency.ts` for the full contract. Missing → 400 BadRequest; same key + different body → 409 Conflict."}]}},"/v2/custom-fields/{customFieldId}":{"patch":{"tags":["custom-fields"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"custom_field":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"field_type":{"type":"string","enum":["input","autocomplete","datepicker"]},"categories":{"type":"array","items":{"type":"object","properties":{"category":{"type":"string","minLength":1,"maxLength":100}},"required":["category"],"additionalProperties":false}}},"additionalProperties":false}},"required":["custom_field"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"customFieldId","required":true},{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","minLength":8,"maxLength":255,"pattern":"^[\\w\\-:.]+$","example":"01HV8N6X7K3P9Q5R2T4Y6W8Z0A"},"description":"Required. UUID per logical operation, reused on every retry. See `apps/rest-api/src/shared/idempotency.ts` for the full contract. Missing → 400 BadRequest; same key + different body → 409 Conflict."}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"custom_field":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"name":{"type":"string"},"field_type":{"type":"string"},"categories":{"type":"array","items":{"type":"string"}},"ranking":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id"],"additionalProperties":false}},"required":["custom_field"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"updateCustomFieldV2","summary":"Update a custom field (v2)","description":"Partial update of a custom field definition (`name`, `field_type`, `categories`). **Requires `Idempotency-Key`.** Returns `{ data: { custom_field: {...} } }`.","x-mint":{"content":"## Use cases\n\n- Rename a field or edit autocomplete categories from settings\n\n## Migration from /v1\n\n/v1 used `PUT /v1/custom-fields/:customFieldId`. /v2 uses `PATCH` because the body is a partial update. Same `{ custom_field: {...} }` body."}},"delete":{"tags":["custom-fields"],"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"customFieldId","required":true},{"in":"header","name":"Idempotency-Key","required":false,"schema":{"type":"string","minLength":8,"maxLength":255,"pattern":"^[\\w\\-:.]+$","example":"01HV8N6X7K3P9Q5R2T4Y6W8Z0A"},"description":"Optional. Accepted to dedupe retries on this endpoint. See `apps/rest-api/src/shared/idempotency.ts`."}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"affected":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"ids":{"type":"array","items":{"type":"string"}},"failed":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","error"],"additionalProperties":false}}},"required":["affected"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"deleteCustomFieldV2","summary":"Delete a custom field (v2)","description":"Permanently delete a custom field definition (per-contact values cascade). Returns `{ data: { affected: 1, ids: [customFieldId] } }`. `Idempotency-Key` is optional. Deleting a missing field returns 404 (v1 silently answered 200).","x-mint":{"content":"## Use cases\n\n- Remove an unused field from settings\n\nPer-contact values for this field cascade and cannot be recovered."}}},"/v2/custom-fields/reorder":{"post":{"tags":["custom-fields"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"updates":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"object","properties":{"customFieldId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"ranking":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["customFieldId","ranking"],"additionalProperties":false}}},"required":["updates"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"custom_fields":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"name":{"type":"string"},"field_type":{"type":"string"},"categories":{"type":"array","items":{"type":"string"}},"ranking":{"nullable":true,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"nextCursor":{"nullable":true,"type":"string"},"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"additionalProperties":false}},"required":["custom_fields"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"reorderCustomFieldsV2","summary":"Reorder custom fields (v2)","description":"Batch ranking update (`{ updates: [{ customFieldId, ranking }] }`, max 100). Stale IDs are silently skipped. **Requires `Idempotency-Key`.** Returns the full re-ranked list: `{ data: { custom_fields: [...] } }`.","x-mint":{"content":"## Use cases\n\n- Drag-and-drop reordering on the settings page\n\n## Migration from /v1\n\n/v1 used `PUT /v1/custom-fields/reorder`. /v2 uses `POST` per the verb-suffix batch convention. The response returns the full post-state list so collection caches can upsert in one pass."},"parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","minLength":8,"maxLength":255,"pattern":"^[\\w\\-:.]+$","example":"01HV8N6X7K3P9Q5R2T4Y6W8Z0A"},"description":"Required. UUID per logical operation, reused on every retry. See `apps/rest-api/src/shared/idempotency.ts` for the full contract. Missing → 400 BadRequest; same key + different body → 409 Conflict."}]}},"/v2/custom-fields/contacts/values":{"post":{"tags":["custom-fields"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"custom_fields":{"minItems":1,"type":"array","items":{"type":"object","properties":{"contact_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"custom_field_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"text_value":{"type":"string"},"date_value":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"array_value":{"type":"array","items":{"type":"string"}}},"required":["contact_id","custom_field_id"],"additionalProperties":false}}},"required":["custom_fields"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"affected":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"ids":{"type":"array","items":{"type":"string"}},"failed":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","error"],"additionalProperties":false}}},"required":["affected"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"setContactCustomFieldValuesV2","summary":"Set custom-field values on contacts (v2)","description":"Batch-set per-contact custom-field VALUES (the `contacts_custom_fields` rows, not the field definitions). Body: `{ custom_fields: [{ contact_id, custom_field_id, text_value?, array_value?, date_value? }] }`. **Requires `Idempotency-Key`.** Returns `{ data: { affected } }` (count of successful updates; per-row failures are skipped and logged).","x-mint":{"content":"## Use cases\n\n- Set custom-field values across a multi-selection of contacts\n- Inline-edit a custom-field value from the contacts table\n\n## Migration from /v1\n\nReplaces `POST /v1/custom-fields/batch-update-contacts`, which returned `{ error: false, data: { count } }`. /v2 returns the canonical bulk envelope (`affected`).\n\n## Idempotency\n\nRequired — the per-row upserts re-execute on a blind retry."},"parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","minLength":8,"maxLength":255,"pattern":"^[\\w\\-:.]+$","example":"01HV8N6X7K3P9Q5R2T4Y6W8Z0A"},"description":"Required. UUID per logical operation, reused on every retry. See `apps/rest-api/src/shared/idempotency.ts` for the full contract. Missing → 400 BadRequest; same key + different body → 409 Conflict."}]}},"/v2/meeting-types/":{"get":{"tags":["meeting-types"],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"meeting_types":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"name":{"type":"string"},"emoji":{"nullable":true,"type":"string"},"created_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]}},"required":["id","name","created_at"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"nextCursor":{"nullable":true,"type":"string"},"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"additionalProperties":false}},"required":["meeting_types"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"listMeetingTypesV2","summary":"List meeting types (v2)","description":"List all of the authenticated user's note/meeting types (`id`, `name`, `emoji`, `created_at`). Returns `{ data: { meeting_types: [...] } }` — no pagination.","x-mint":{"content":"## Use cases\n\n- Populate the note-type picker in the timeline editor\n- Populate the note-types settings page\n\n## Migration from /v1\n\nThe list lived at `GET /v1/timeline/note-types` and returned a bare `{ error, data: [...] }` array. /v2 moves it onto the domain URL with the canonical list envelope."}},"post":{"tags":["meeting-types"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"emoji":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["name"],"additionalProperties":false}}}},"responses":{"201":{"description":"Created","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"meeting_type":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"name":{"type":"string"},"emoji":{"nullable":true,"type":"string"},"created_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]}},"required":["id","name","created_at"],"additionalProperties":false}},"required":["meeting_type"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"createMeetingTypeV2","summary":"Create a meeting type (v2)","description":"Create ONE meeting type from `{ name, emoji? }`. Names are unique per user — a duplicate returns 400. **Requires `Idempotency-Key`.** Returns `{ data: { meeting_type: {...} } }` with status 201.","x-mint":{"content":"## Use cases\n\n- Add a custom note type (e.g., \"☕ Coffee chat\") from settings\n\n## Idempotency\n\nGenerate one UUID per logical create and reuse it on every retry — a blind retry would otherwise race the per-user name unique constraint."},"parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","minLength":8,"maxLength":255,"pattern":"^[\\w\\-:.]+$","example":"01HV8N6X7K3P9Q5R2T4Y6W8Z0A"},"description":"Required. UUID per logical operation, reused on every retry. See `apps/rest-api/src/shared/idempotency.ts` for the full contract. Missing → 400 BadRequest; same key + different body → 409 Conflict."}]}},"/v2/meeting-types/{meetingTypeId}":{"patch":{"tags":["meeting-types"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1},"emoji":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"meetingTypeId","required":true},{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","minLength":8,"maxLength":255,"pattern":"^[\\w\\-:.]+$","example":"01HV8N6X7K3P9Q5R2T4Y6W8Z0A"},"description":"Required. UUID per logical operation, reused on every retry. See `apps/rest-api/src/shared/idempotency.ts` for the full contract. Missing → 400 BadRequest; same key + different body → 409 Conflict."}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"meeting_type":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"name":{"type":"string"},"emoji":{"nullable":true,"type":"string"},"created_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]}},"required":["id","name","created_at"],"additionalProperties":false}},"required":["meeting_type"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"updateMeetingTypeV2","summary":"Update a meeting type (v2)","description":"Partial update (`name`, `emoji`). **Requires `Idempotency-Key`.** Returns the updated entity: `{ data: { meeting_type: {...} } }`.","x-mint":{"content":"## Use cases\n\n- Rename a note type or change its emoji from settings\n\n## Migration from /v1\n\n/v1 used `PUT /v1/meeting-types/:meetingTypeId` and returned `{ affected_rows }`, forcing a refetch. /v2 uses `PATCH` and returns the post-state entity."}},"delete":{"tags":["meeting-types"],"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"query","name":"reassign_to","required":false},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"meetingTypeId","required":true},{"in":"header","name":"Idempotency-Key","required":false,"schema":{"type":"string","minLength":8,"maxLength":255,"pattern":"^[\\w\\-:.]+$","example":"01HV8N6X7K3P9Q5R2T4Y6W8Z0A"},"description":"Optional. Accepted to dedupe retries on this endpoint. See `apps/rest-api/src/shared/idempotency.ts`."}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"affected":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"ids":{"type":"array","items":{"type":"string"}},"failed":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","error"],"additionalProperties":false}}},"required":["affected"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"deleteMeetingTypeV2","summary":"Delete a meeting type (v2)","description":"Permanently delete a meeting type. Pass `?reassign_to=` to move the type's existing notes onto another type; omit it and they fall back to the plain 'note' type. Both happen in one transaction. Returns `{ data: { affected: 1, ids: [meetingTypeId] } }`. `Idempotency-Key` is optional.","x-mint":{"content":"## Use cases\n\n- Remove an unused note type from settings, optionally migrating its notes\n\n## Migration from /v1\n\n/v1 took `reassignTo` in the DELETE body. /v2 moves it to the `?reassign_to=` query param — DELETE bodies are HTTP-spec-discouraged and some proxies strip them silently.\n\n`reassign_to` must differ from the meeting type being deleted (400 otherwise)."}}},"/v2/contact-emails/{contactId}":{"post":{"tags":["contact-emails"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","maxLength":320,"format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"label":{"type":"string"},"ranking":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["email"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"contactId","required":true}],"responses":{"201":{"description":"Created","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"email":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"contact_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"email":{"type":"string"},"label":{"nullable":true,"type":"string"},"ranking":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"created_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"updated_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]}},"required":["id","contact_id","email","ranking","created_at","updated_at"],"additionalProperties":false}},"required":["email"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"createContactEmailV2","summary":"Create a contact email (v2)","description":"Add an email address to a contact, optionally with a label (e.g. \"Work\"). **Requires `Idempotency-Key`.** Returns the created row: `{ data: { contact_email: {...} } }`, status 201.","x-mint":{"content":"## Use cases\n\n- Add a newly discovered email to an existing contact\n- Import additional addresses during a sync\n\n## Migration from /v1\n\n/v1 returned `{ error: false, data: {...} }`. /v2 drops `error` and namespaces the entity under `data.contact_email`."}}},"/v2/contact-emails/{contactId}/reorder":{"post":{"tags":["contact-emails"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"order":{"minItems":1,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"ranking":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id","ranking"],"additionalProperties":false}}},"required":["order"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"contactId","required":true}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"affected":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"ids":{"type":"array","items":{"type":"string"}},"failed":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","error"],"additionalProperties":false}}},"required":["affected"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"reorderContactEmailsV2","summary":"Reorder contact emails (v2)","description":"Set the display order of a contact's emails. Body is id-based: `{ order: [{ id, ranking }] }` (row ids survive, unlike v1's positional payload). **Requires `Idempotency-Key`.** Returns the bulk envelope `{ data: { affected } }`.","x-mint":{"content":"## Use cases\n\n- Promote a preferred/primary email to the top\n- Persist a drag-and-drop reorder\n\n## Migration from /v1\n\n/v1 used `PUT /:contactId/rankings` with a positional list. /v2 uses `POST /:contactId/reorder` with `{ order: [{ id, ranking }] }`."}}},"/v2/contact-emails/{contactId}/{emailId}":{"patch":{"tags":["contact-emails"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","maxLength":320,"format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"ranking":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"contactId","required":true},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"emailId","required":true}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"affected":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"ids":{"type":"array","items":{"type":"string"}},"failed":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","error"],"additionalProperties":false}}},"required":["affected"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"updateContactEmailV2","summary":"Update a contact email (v2)","description":"Partially update one email on a contact (value and/or label). **Requires `Idempotency-Key`.** Returns the bulk envelope `{ data: { affected } }`.","x-mint":{"content":"## Use cases\n\n- Fix a typo in an address\n- Relabel an email (e.g. \"Work\" → \"Personal\")\n\n## Migration from /v1\n\n/v1 used `PUT` (full replace); /v2 uses `PATCH` (partial update)."}},"delete":{"tags":["contact-emails"],"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"contactId","required":true},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"emailId","required":true}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"affected":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"ids":{"type":"array","items":{"type":"string"}},"failed":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","error"],"additionalProperties":false}}},"required":["affected"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"deleteContactEmailV2","summary":"Delete a contact email (v2)","description":"Remove an email from a contact. Idempotency-Key is optional (delete is idempotent; a key replays the same `affected` on retry). Returns `{ data: { affected } }`.","x-mint":{"content":"## Use cases\n\n- Remove an outdated or invalid address\n- Clean up duplicates\n\nThis permanently deletes the email association."}}},"/v2/contact-phone-numbers/{contactId}":{"post":{"tags":["contact-phone-numbers"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"phone_number":{"type":"string","minLength":1,"maxLength":50},"label":{"type":"string"},"ranking":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"country_code":{"type":"string","maxLength":4},"phone_number_sanitized":{"type":"string","maxLength":50}},"required":["phone_number"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"contactId","required":true}],"responses":{"201":{"description":"Created","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"phoneNumber":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"contact_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"phone_number":{"type":"string"},"label":{"nullable":true,"type":"string"},"ranking":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"country_code":{"nullable":true,"type":"string"},"phone_number_sanitized":{"nullable":true,"type":"string"},"created_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"updated_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]}},"required":["id","contact_id","phone_number","ranking","created_at","updated_at"],"additionalProperties":false}},"required":["phoneNumber"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"createContactPhoneNumberV2","summary":"Create a contact phone number (v2)","description":"Add a phone number to a contact, optionally with a label. **Requires `Idempotency-Key`.** Returns the created row: `{ data: { contact_phone_number: {...} } }`, status 201.","x-mint":{"content":"## Use cases\n\n- Add a newly discovered number to a contact\n- Import additional numbers during a sync\n\n## Migration from /v1\n\n/v1 returned `{ error: false, data: {...} }`. /v2 drops `error` and namespaces the entity under `data.contact_phone_number`."}}},"/v2/contact-phone-numbers/{contactId}/reorder":{"post":{"tags":["contact-phone-numbers"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"order":{"minItems":1,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"ranking":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["id","ranking"],"additionalProperties":false}}},"required":["order"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"contactId","required":true}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"affected":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"ids":{"type":"array","items":{"type":"string"}},"failed":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","error"],"additionalProperties":false}}},"required":["affected"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"reorderContactPhoneNumbersV2","summary":"Reorder contact phone numbers (v2)","description":"Set the display order of a contact's phone numbers. Body is id-based: `{ order: [{ id, ranking }] }`. **Requires `Idempotency-Key`.** Returns `{ data: { affected } }`.","x-mint":{"content":"## Use cases\n\n- Promote a primary number to the top\n- Persist a drag-and-drop reorder\n\n## Migration from /v1\n\n/v1 used `PUT /:contactId/rankings`; /v2 uses `POST /:contactId/reorder` with `{ order: [{ id, ranking }] }`."}}},"/v2/contact-phone-numbers/{contactId}/{phoneNumberId}":{"patch":{"tags":["contact-phone-numbers"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"phone_number":{"type":"string","minLength":1,"maxLength":50},"label":{"anyOf":[{"type":"string"},{"type":"null"}]},"ranking":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"country_code":{"anyOf":[{"type":"string","maxLength":4},{"type":"null"}]},"phone_number_sanitized":{"anyOf":[{"type":"string","maxLength":50},{"type":"null"}]}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"contactId","required":true},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"phoneNumberId","required":true}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"affected":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"ids":{"type":"array","items":{"type":"string"}},"failed":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","error"],"additionalProperties":false}}},"required":["affected"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"updateContactPhoneNumberV2","summary":"Update a contact phone number (v2)","description":"Partially update one phone number on a contact (value and/or label). **Requires `Idempotency-Key`.** Returns `{ data: { affected } }`.","x-mint":{"content":"## Use cases\n\n- Fix a typo in a number\n- Relabel a number (e.g. \"Mobile\" → \"Work\")\n\n## Migration from /v1\n\n/v1 used `PUT` (full replace); /v2 uses `PATCH` (partial update)."}},"delete":{"tags":["contact-phone-numbers"],"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"contactId","required":true},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"phoneNumberId","required":true}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"affected":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"ids":{"type":"array","items":{"type":"string"}},"failed":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","error"],"additionalProperties":false}}},"required":["affected"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"deleteContactPhoneNumberV2","summary":"Delete a contact phone number (v2)","description":"Remove a phone number from a contact. Idempotency-Key is optional. Returns `{ data: { affected } }`.","x-mint":{"content":"## Use cases\n\n- Remove an outdated number\n- Clean up duplicates\n\nThis permanently deletes the phone number."}}},"/v2/contact-legacy-addresses/{contactId}":{"post":{"tags":["contact-legacy-addresses"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"formatted":{"anyOf":[{"type":"string"},{"type":"null"}]},"street":{"anyOf":[{"type":"string"},{"type":"null"}]},"city":{"anyOf":[{"type":"string"},{"type":"null"}]},"region":{"anyOf":[{"type":"string"},{"type":"null"}]},"country":{"anyOf":[{"type":"string"},{"type":"null"}]},"postal_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"address_type":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"contactId","required":true}],"responses":{"201":{"description":"Created","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"address":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"contact_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"user_id":{"type":"string"},"formatted":{"nullable":true,"type":"string"},"street":{"nullable":true,"type":"string"},"city":{"nullable":true,"type":"string"},"region":{"nullable":true,"type":"string"},"country":{"nullable":true,"type":"string"},"postal_code":{"nullable":true,"type":"string"},"address_type":{"nullable":true,"type":"string"},"created_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]},"updated_at":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{}]}},"required":["id","contact_id","created_at","updated_at"],"additionalProperties":false}},"required":["address"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"createContactAddressV2","summary":"Create a contact address (v2)","description":"Add a postal address to a contact. **Requires `Idempotency-Key`.** Returns the created row: `{ data: { contact_legacy_address: {...} } }`, status 201. Addresses are not ranked (no reorder).","x-mint":{"content":"## Use cases\n\n- Store a mailing or office address on a contact\n- Import addresses during a data migration\n\n## Migration from /v1\n\n/v1 returned `{ error: false, data: {...} }`. /v2 drops `error` and namespaces the entity under `data.contact_legacy_address`."}}},"/v2/contact-legacy-addresses/{contactId}/{addressId}":{"patch":{"tags":["contact-legacy-addresses"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"formatted":{"anyOf":[{"type":"string"},{"type":"null"}]},"street":{"anyOf":[{"type":"string"},{"type":"null"}]},"city":{"anyOf":[{"type":"string"},{"type":"null"}]},"region":{"anyOf":[{"type":"string"},{"type":"null"}]},"country":{"anyOf":[{"type":"string"},{"type":"null"}]},"postal_code":{"anyOf":[{"type":"string"},{"type":"null"}]},"address_type":{"anyOf":[{"type":"string"},{"type":"null"}]}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"contactId","required":true},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"addressId","required":true}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"affected":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"ids":{"type":"array","items":{"type":"string"}},"failed":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","error"],"additionalProperties":false}}},"required":["affected"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"updateContactAddressV2","summary":"Update a contact address (v2)","description":"Partially update one address on a contact. **Requires `Idempotency-Key`.** Returns `{ data: { affected } }`.","x-mint":{"content":"## Use cases\n\n- Correct an address after a contact moves\n- Update an incomplete address\n\n## Migration from /v1\n\n/v1 used `PUT` (full replace); /v2 uses `PATCH` (partial update)."}},"delete":{"tags":["contact-legacy-addresses"],"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"contactId","required":true},{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"addressId","required":true}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"affected":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"ids":{"type":"array","items":{"type":"string"}},"failed":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","error"],"additionalProperties":false}}},"required":["affected"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"deleteContactAddressV2","summary":"Delete a contact address (v2)","description":"Remove an address from a contact. Idempotency-Key is optional. Returns `{ data: { affected } }`.","x-mint":{"content":"## Use cases\n\n- Remove an outdated address\n- Clean up duplicates\n\nThis permanently deletes the address."}}},"/v2/contact-relations/{contactId}":{"get":{"tags":["contact-relations"],"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"contactId","required":true}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"related_contacts":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"full_name":{"nullable":true,"type":"string"},"first_name":{"nullable":true,"type":"string"},"last_name":{"nullable":true,"type":"string"},"image_url":{"nullable":true,"type":"string"}},"required":["id"],"additionalProperties":false}},"pagination":{"type":"object","properties":{"nextCursor":{"nullable":true,"type":"string"},"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"additionalProperties":false}},"required":["related_contacts"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"listRelatedContactsV2","summary":"List related contacts (v2)","description":"Get the contacts related to a contact. Relations are an undirected, untyped graph — the server normalizes edge direction, so the same list comes back whichever side of a pair you ask from. Returns `{ data: { related_contacts: [...] } }` where each row is a narrow projection (id, names, image_url), not the full contact.","x-mint":{"content":"## Use cases\n\n- Show \"related contacts\" chips on a contact detail page\n- Traverse a personal network (who do I know through this person?)\n\n## Shape\n\nThe rows are a chip projection — `id`, `full_name`, `first_name`, `last_name`, `image_url`. Fetch the full record via `GET /v2/contacts/{id}`."}}},"/v2/contact-relations/{contactId}/add":{"post":{"tags":["contact-relations"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contactIds":{"minItems":1,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"required":["contactIds"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"contactId","required":true},{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","minLength":8,"maxLength":255,"pattern":"^[\\w\\-:.]+$","example":"01HV8N6X7K3P9Q5R2T4Y6W8Z0A"},"description":"Required. UUID per logical operation, reused on every retry. See `apps/rest-api/src/shared/idempotency.ts` for the full contract. Missing → 400 BadRequest; same key + different body → 409 Conflict."}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"affected":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"ids":{"type":"array","items":{"type":"string"}},"failed":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","error"],"additionalProperties":false}}},"required":["affected"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"addRelatedContactsV2","summary":"Add related contacts (v2)","description":"Link one or more contacts to `{contactId}` as related contacts. Relations are symmetric — linking A to B also links B to A — and carry no relationship label. Already-linked pairs and self-links are silently skipped. **Requires `Idempotency-Key`.** Returns `{ data: { affected, ids } }` where `affected` counts NEW links created.","x-mint":{"content":"## Use cases\n\n- Record family members, colleagues, or intro paths between contacts\n\n## Semantics\n\nThe graph is undirected and untyped: there is no \"spouse\"/\"colleague\" label — record the nature of a relationship in a note instead. Every id in the body must belong to the caller, or the whole request fails."}}},"/v2/contact-relations/{contactId}/remove":{"post":{"tags":["contact-relations"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contactIds":{"minItems":1,"type":"array","items":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}}},"required":["contactIds"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"in":"path","name":"contactId","required":true},{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","minLength":8,"maxLength":255,"pattern":"^[\\w\\-:.]+$","example":"01HV8N6X7K3P9Q5R2T4Y6W8Z0A"},"description":"Required. UUID per logical operation, reused on every retry. See `apps/rest-api/src/shared/idempotency.ts` for the full contract. Missing → 400 BadRequest; same key + different body → 409 Conflict."}],"responses":{"200":{"description":"Successful response","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Cache-Control":{"schema":{"type":"string","default":"private, no-store"},"description":"Personal-CRM data — never cached in shared proxies/CDNs. Browsers may keep it in the page session memory but should not persist it."}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"affected":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"ids":{"type":"array","items":{"type":"string"}},"failed":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"required":["id","error"],"additionalProperties":false}}},"required":["affected"],"additionalProperties":false}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"Request body failed validation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Valid key, insufficient permission.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Request conflicts with the current state of the resource.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"RateLimit":{"$ref":"#/components/headers/RateLimit"},"RateLimit-Policy":{"$ref":"#/components/headers/RateLimit-Policy"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected server error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"removeRelatedContactsV2","summary":"Remove related contacts (v2)","description":"Unlink one or more related contacts from `{contactId}`. The contacts themselves are NOT deleted — only the relation rows are removed (both stored directions, so legacy double-stored pairs are fully cleared). **Requires `Idempotency-Key`.** Returns `{ data: { affected, ids } }`.","x-mint":{"content":"## Use cases\n\n- Remove a stale or mistaken relationship\n\nRemoving a relation does not delete either contact — it only clears the link between them."}}}},"servers":[{"url":"https://api.prod.getdex.com","description":"Production"}],"security":[{"bearerAuth":[]}],"externalDocs":{"description":"Dex API Reference","url":"https://getdex.com/docs/api-reference/authentication"}}