{"openapi":"3.0.0","info":{"title":"Workspace API","version":"1.0.0"},"servers":[{"url":"http://api.ctd.ai"}],"security":[{"ApiKeyAuth":[]}],"paths":{"/enterprise/atc-paths-api/public/v1/people":{"get":{"operationId":"getPeople","summary":"Reachable company employees","description":"Returns a list of people working at the specified company who can be reached through at least one path from either your coworkers or external members.","tags":["People"],"parameters":[{"name":"ctd-api-key","in":"header","required":true,"schema":{"type":"string"},"description":"Enterprise CTD API key, used for authentication."},{"name":"ctd-client-id","in":"header","required":true,"schema":{"type":"string","format":"email"},"description":"The user's organization email address, used for audit logging and access control validation."},{"name":"company_linkedin_url","in":"query","required":false,"schema":{"type":"string","format":"uri"},"description":"The company LinkedIn URL (preferred identifier). The URL is normalized to `https://www.linkedin.com/company/<slug>`. Exactly one of company_linkedin_url or company_domain must be provided (not both).\n"},{"name":"company_domain","in":"query","required":false,"schema":{"type":"string"},"description":"The company primary domain (e.g., 'example.com'). The domain is normalized before processing. Exactly one of company_domain or company_linkedin_url must be provided (not both), otherwise the request will be rejected.\n"},{"name":"degree","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","enum":["first","second","third"]}},"example":["first","second"],"description":"Filter people by connection degree (first, second, or third degree)."},{"name":"relationship_strength","in":"query","required":false,"schema":{"type":"array","items":{"type":"integer","enum":[1,2,3]}},"example":[2,3],"description":"Filter people by the strength of the relationship between your organization and the individual, where 1 = weak, 2 = medium, and 3 = strong. A strong relationship means there is at least one strong path between your coworkers or external members and that person.\n"},{"name":"is_target_persona","in":"query","required":false,"schema":{"type":"boolean"},"example":true,"description":"Filter results to include only people marked as target personas. Target personas are defined by your organization admin in the CTD application and may not be configured."},{"name":"target_title","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"example":["managing director"],"description":"Filter people by job title. Returns all people whose job title contains the provided value as a case-insensitive substring."},{"name":"target_seniority","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","enum":["Owner","CEO","CXO","Partner","VP","Manager","Director","Principal","Senior","EA","Board","Investor","Advisor","Founder","Consultant","Entry","Unpaid","Training"]}},"example":["CEO","VP","Director"],"description":"Filter people by seniority level using the predefined seniority categories. Matching is case-insensitive."},{"name":"target_function","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","enum":["Travel","Media","Customer Success","Support","Education","Information Technology","Engineering","Finance","Health","Human Resources","Legal","Product","Operations","Design","Public Relations","Real Estate","Sales"]}},"example":["Engineering","Sales"],"description":"Filter people by functional area using the predefined function categories. Matching is case-insensitive."},{"name":"path_stage","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","enum":["Not started","To do","Approaching Connector","Approaching Target","Successful","Unsuccessful","Not relevant","Bad data"]}},"example":["To do","Approaching Connector"],"description":"Filter people by path stage. Returns only people for whom there is at least one path in the specified stage. Values are trimmed and matched case-insensitively.\n"},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":40},"example":20,"description":"Number of items to return per page. Maximum value is 40."},{"name":"start_item","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1},"example":1,"description":"Pagination starting index (1-based)."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicPeopleResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/enterprise/atc-paths-api/public/v1/company":{"get":{"operationId":"getCompany","summary":"Reachable company","description":"Returns company details, including CTD score and stage information when available. Available only for companies that are reachable through your organization's network, meaning there is at least one path from your organization to that company.\n","tags":["Company"],"parameters":[{"name":"ctd-api-key","in":"header","required":true,"schema":{"type":"string"},"description":"Enterprise CTD API key, used for authentication."},{"name":"ctd-client-id","in":"header","required":true,"schema":{"type":"string","format":"email"},"description":"The user's organization email address, used for audit logging and access control validation."},{"name":"company_linkedin_url","in":"query","required":false,"schema":{"type":"string","format":"uri"},"description":"The company LinkedIn URL (preferred identifier). The URL is normalized to `https://www.linkedin.com/company/<slug>`. Exactly one of company_linkedin_url or company_domain must be provided (not both), otherwise the request will be rejected.\n"},{"name":"company_domain","in":"query","required":false,"schema":{"type":"string"},"description":"The company primary domain (e.g., 'example.com'). The domain is normalized before processing. Exactly one of company_domain or company_linkedin_url must be provided (not both), otherwise the request will be rejected.\n"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCompanyResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/enterprise/atc-paths-api/public/v2/company/stage":{"patch":{"operationId":"updateCompanyStageV2","summary":"Update company stage by domain or LinkedIn URL","description":"Sets the manual stage and/or manual note for a single company reachable through your organization's network, identified by either company_domain or company_linkedin_url. Provide at least one of `company_stage` or `manual_note`. A manual stage takes precedence over the auto-calculated stage. Sending only `manual_note` leaves the current stage unchanged. Returns 200 OK when the update is applied synchronously; returns 202 Accepted with `deferred: true` when the update has to be queued and will be reflected within a few hours. Also available at the identical `PATCH /enterprise/atc-paths-api/public/v1/company/stage`.\n","tags":["Company"],"parameters":[{"name":"ctd-api-key","in":"header","required":true,"schema":{"type":"string"},"description":"Enterprise CTD API key, used for authentication."},{"name":"ctd-client-id","in":"header","required":true,"schema":{"type":"string","format":"email"},"description":"The user's organization email address, used for audit logging and access control validation."},{"name":"company_linkedin_url","in":"query","required":false,"schema":{"type":"string","format":"uri"},"description":"The company LinkedIn URL (preferred identifier). The URL is normalized to `https://www.linkedin.com/company/<slug>`. Exactly one of company_linkedin_url or company_domain must be provided (not both), otherwise the request will be rejected.\n"},{"name":"company_domain","in":"query","required":false,"schema":{"type":"string"},"description":"The company primary domain (e.g., 'example.com'). The domain is normalized before processing. Exactly one of company_domain or company_linkedin_url must be provided (not both), otherwise the request will be rejected.\n"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","description":"Provide at least one of company_stage or manual_note.","anyOf":[{"required":["company_stage"]},{"required":["manual_note"]}],"properties":{"company_stage":{"type":"string","enum":["ToDo","NotRelevant","Unsuccessful","NoGoodPaths","Approaching","Successful","Attempted","BadData"],"example":"Approaching","description":"New manual stage to set for the company. Values are matched case-insensitively. Provide at least one of company_stage or manual_note. Cannot be null or an empty string; omit the field to leave the current stage unchanged.\n"},"manual_note":{"type":"string","nullable":true,"example":"Champion changed roles; revisit next quarter.","description":"Manual note to attach to the company stage. Pass an empty string or null to clear an existing note. Provide at least one of company_stage or manual_note.\n"}}}}}},"responses":{"200":{"description":"Company stage updated successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"company":{"type":"object","properties":{"stage":{"type":"string","nullable":true,"enum":["ToDo","NotRelevant","Unsuccessful","NoGoodPaths","Approaching","Successful","Attempted","BadData"],"description":"Resulting company stage (null when the company is not started)."},"stage_updated_at":{"type":"string","format":"date-time","nullable":true,"description":"When the manual stage was last set."},"company_status_manual_note":{"type":"string","nullable":true,"description":"The manual note currently attached to the company stage."},"company_status_manual_note_updated_at":{"type":"string","format":"date-time","nullable":true,"description":"When the manual note was last updated."}}}}}}}},"202":{"description":"Update accepted and queued. The change will be reflected within a few hours.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"deferred":{"type":"boolean","example":true},"message":{"type":"string","example":"Company stage update is queued and will be visible within a few hours."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/enterprise/atc-paths-api/public/v2/companies/bulk-update-stage":{"post":{"operationId":"bulkUpdateCompanyStageV2","summary":"Bulk update company stages","description":"Updates the manual stage and/or manual note for up to 500 companies in a single request. Each item is identified by company_domain or company_linkedin_url and must contain at least one of company_stage or manual_note. Items are processed independently; the response reports per-item status. Returns 200 OK when every item is applied synchronously; returns 202 Accepted when one or more items are queued and will be reflected within a few hours.\n","tags":["Companies"],"parameters":[{"name":"ctd-api-key","in":"header","required":true,"schema":{"type":"string"},"description":"Enterprise CTD API key, used for authentication."},{"name":"ctd-client-id","in":"header","required":true,"schema":{"type":"string","format":"email"},"description":"The user's organization email address, used for audit logging and access control validation."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["updates"],"properties":{"updates":{"type":"array","minItems":1,"maxItems":500,"description":"List of company stage updates. At most 500 items per request.","items":{"type":"object","minProperties":2,"description":"A single company update. Provide exactly one of company_domain or company_linkedin_url, and at least one of company_stage or manual_note.\n","properties":{"company_domain":{"type":"string","description":"Company domain to update (mutually exclusive with company_linkedin_url)."},"company_linkedin_url":{"type":"string","format":"uri","description":"Company LinkedIn URL to update (mutually exclusive with company_domain)."},"company_stage":{"type":"string","nullable":true,"enum":["ToDo","NotRelevant","Unsuccessful","NoGoodPaths","Approaching","Successful","Attempted","BadData"],"example":"Approaching","description":"New manual stage. Values are matched case-insensitively."},"manual_note":{"type":"string","nullable":true,"example":"Champion changed roles; revisit next quarter.","description":"Manual note to attach to the company stage. Pass an empty string or null to clear an existing note."}}}}}}}}},"responses":{"200":{"description":"All items processed synchronously.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicBulkUpdateCompanyStageResult"}}}},"202":{"description":"One or more items queued; the change will be reflected within a few hours.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicBulkUpdateCompanyStageResult"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"description":"Invalid batch envelope (empty, too large, or malformed).","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","enum":["empty_batch","batch_too_large","malformed_batch"]}}}}}},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/enterprise/atc-paths-api/public/v1/paths/search":{"get":{"summary":"Search paths using natural language","description":"Accepts a natural language search query and returns matching paths with an explanation.","tags":["Paths"],"parameters":[{"name":"ctd-api-key","in":"header","required":true,"schema":{"type":"string"},"description":"API key for authentication."},{"name":"ctd-client-id","in":"header","required":true,"schema":{"type":"string","format":"email"},"description":"Caller email; required for audit and access checks."},{"name":"search_query","in":"query","required":true,"schema":{"type":"string"},"description":"Natural language search query","example":"Show me paths to CTOs in New York"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicSearchPathsResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/enterprise/atc-paths-api/public/v1/job-changes":{"get":{"operationId":"getJobChanges","summary":"Job changes","description":"Returns a paginated list of job changes for people reachable through your organization's network, including new hires, departures, company switches, and promotions.","tags":["Job Changes"],"parameters":[{"name":"ctd-api-key","in":"header","required":true,"schema":{"type":"string"},"description":"Enterprise CTD API key, used for authentication."},{"name":"ctd-client-id","in":"header","required":true,"schema":{"type":"string","format":"email"},"description":"The user's organization email address, used for audit logging and access control validation."},{"name":"days","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":365,"default":90},"description":"Number of days to look back for job changes. Default is 90 days."},{"name":"is_champion","in":"query","required":false,"schema":{"type":"boolean"},"description":"Filter to show only job changes for champions (key connectors in your network)."},{"name":"is_target_persona","in":"query","required":false,"schema":{"type":"boolean"},"description":"Filter to show only job changes for people marked as target personas."},{"name":"start_item","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1},"description":"Pagination starting index (1-based)."},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":40},"description":"Number of items to return per page. Maximum value is 100."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicJobChangesResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/enterprise/atc-paths-api/public/v1/reachable-companies":{"get":{"operationId":"getReachableCompanies","summary":"Reachable companies","description":"Returns a paginated list of companies reachable through the user's network, with CTD scores, stages, and filtering options.","tags":["Companies"],"parameters":[{"name":"ctd-api-key","in":"header","required":true,"schema":{"type":"string"},"description":"Enterprise CTD API key, used for authentication."},{"name":"ctd-client-id","in":"header","required":true,"schema":{"type":"string","format":"email"},"description":"The user's organization email address, used for audit logging and access control validation."},{"name":"stage","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","enum":["Not started","To do","Approaching","Successful","Unsuccessful","Not relevant","Bad data"]}},"example":["To do","Approaching"],"description":"Filter companies by stage. Values are matched case-insensitively."},{"name":"is_target_account","in":"query","required":false,"schema":{"type":"boolean"},"description":"Filter to show only companies marked as target accounts."},{"name":"start_item","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1},"description":"Pagination starting index (1-based)."},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":40,"default":40},"description":"Number of items to return per page. Maximum value is 40."},{"name":"format","in":"query","required":false,"schema":{"type":"string","nullable":true,"enum":["csv","json"]},"description":"Response format. If not provided or null, defaults to JSON."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReachableCompaniesResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/enterprise/atc-paths-api/public/v1/reachable-people":{"get":{"operationId":"getReachablePeople","summary":"Reachable people","description":"Returns a paginated list of people reachable through the user's network, with relationship scores and path statistics.","tags":["People"],"parameters":[{"name":"ctd-api-key","in":"header","required":true,"schema":{"type":"string"},"description":"Enterprise CTD API key, used for authentication."},{"name":"ctd-client-id","in":"header","required":true,"schema":{"type":"string","format":"email"},"description":"The user's organization email address, used for audit logging and access control validation."},{"name":"degree","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","enum":["first","second","third"]}},"example":["first","second"],"description":"Filter people by connection degree (first, second, or third degree)."},{"name":"relationship_strength","in":"query","required":false,"schema":{"type":"array","items":{"type":"integer","enum":[0,1,2,3]}},"example":[2,3],"description":"Filter people by the strength of the relationship between your organization and the individual, where 0 = very weak, 1 = weak, 2 = medium, and 3 = strong.\n"},{"name":"is_target_persona","in":"query","required":false,"schema":{"type":"boolean"},"example":true,"description":"Filter results to include only people marked as target personas."},{"name":"target_title","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"example":["managing director"],"description":"Filter people by job title. Returns all people whose job title contains the provided value as a case-insensitive substring."},{"name":"target_seniority","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","enum":["Owner","CEO","CXO","Partner","VP","Manager","Director","Principal","Senior","EA","Board","Investor","Advisor","Founder","Consultant","Entry","Unpaid","Training"]}},"example":["CEO","VP","Director"],"description":"Filter people by seniority level using the predefined seniority categories. Matching is case-insensitive."},{"name":"target_function","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","enum":["Travel","Media","Customer Success","Support","Education","Information Technology","Engineering","Finance","Health","Human Resources","Legal","Product","Operations","Design","Public Relations","Real Estate","Sales"]}},"example":["Engineering","Sales"],"description":"Filter people by functional area using the predefined function categories. Matching is case-insensitive."},{"name":"target_location","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"example":["New York"],"description":"Filter people by location. Returns people whose location contains the provided value as a case-insensitive substring."},{"name":"path_stage","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","enum":["Not started","To do","Approaching Connector","Approaching Target","Successful","Unsuccessful","Not relevant","Bad data"]}},"example":["To do","Approaching Connector"],"description":"Filter people by path stage. Returns only people for whom there is at least one path in the specified stage. Values are trimmed and matched case-insensitively.\n"},{"name":"path_relationship_strength","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","enum":["weak","medium","strong"]}},"example":["medium","strong"],"description":"Filter by path relationship strength."},{"name":"path_relationship_type","in":"query","required":false,"schema":{"type":"string","nullable":true,"enum":["deterministic","probabilistic"]},"example":"deterministic","description":"Filter by path relationship type. Deterministic means that all nodes in the path are connected to each other via email or LinkedIn connections, while probabilistic means that the connection between the connector and the target person is predicted based on publicly available career and education overlap signals.\n"},{"name":"start_item","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1},"description":"Pagination starting index (1-based)."},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":40},"example":20,"description":"Number of items to return per page. Maximum value is 40."},{"name":"format","in":"query","required":false,"schema":{"type":"string","nullable":true,"enum":["csv","json"]},"description":"Response format. If not provided or null, defaults to JSON."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReachablePeopleResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/enterprise/atc-paths-api/public/v1/reachable-person":{"get":{"operationId":"getReachablePerson","summary":"Reachable person","description":"Returns a single reachable person identified by LinkedIn URL, with relationship scores and path statistics from the authenticated user's perspective. The person includes `team_relationship`: your and your co-workers' combined email and meeting history with them, counted only from company email and calendar accounts, when your enterprise admin has enabled it; its values depend on the member whose email is sent in `ctd-client-id`.\n","tags":["People"],"parameters":[{"name":"ctd-api-key","in":"header","required":true,"schema":{"type":"string"},"description":"Enterprise CTD API key, used for authentication."},{"name":"ctd-client-id","in":"header","required":true,"schema":{"type":"string","format":"email"},"description":"The user's organization email address, used for audit logging and access control validation."},{"name":"person_linkedin_url","in":"query","required":true,"schema":{"type":"string","format":"uri"},"description":"The person LinkedIn URL. The URL is normalized to https://www.linkedin.com/in/{slug}.\n"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReachablePersonResponseWithTeamRelationship"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/enterprise/atc-paths-api/public/v1/global/reachable-person":{"get":{"operationId":"getGlobalReachablePerson","summary":"Reachable person (global view)","description":"Returns a single reachable person identified by LinkedIn URL, with enterprise-wide relationship scores and path statistics. Results are not personalized per user.","tags":["People"],"parameters":[{"name":"ctd-api-key","in":"header","required":true,"schema":{"type":"string"},"description":"Enterprise CTD API key, used for authentication."},{"name":"ctd-client-id","in":"header","required":true,"schema":{"type":"string","format":"email"},"description":"The user's organization email address, used for audit logging and access control validation."},{"name":"person_linkedin_url","in":"query","required":true,"schema":{"type":"string","format":"uri"},"description":"The person LinkedIn URL. The URL is normalized to https://www.linkedin.com/in/{slug}.\n"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReachablePersonResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/enterprise/atc-paths-api/public/v2/paths":{"get":{"operationId":"getPathsV2","summary":"Paths to a company or a person","description":"Returns paths from the user authenticated in the API to the specified company or person via coworkers or external members. Edges include `relationship_via_company_domain`: email and meeting details between you or a co-worker and their contacts, counted only from company email and calendar accounts, when your enterprise admin has enabled it.\n","tags":["Paths"],"parameters":[{"name":"ctd-api-key","in":"header","required":true,"schema":{"type":"string"},"description":"Enterprise CTD API key, used for authentication."},{"name":"ctd-client-id","in":"header","required":true,"schema":{"type":"string","format":"email"},"description":"The user's organization email address, used for audit logging and access control validation."},{"name":"company_linkedin_url","in":"query","required":false,"schema":{"type":"string","format":"uri"},"description":"The company LinkedIn URL (preferred identifier). The URL is normalized to `https://www.linkedin.com/company/<slug>`. Exactly one of company_linkedin_url or company_domain must be provided for company-based lookup (not both), otherwise the request will be rejected.\n"},{"name":"company_domain","in":"query","required":false,"schema":{"type":"string"},"description":"The company primary domain (e.g., 'example.com'). The domain is normalized before processing. Exactly one of company_domain or company_linkedin_url must be provided for company-based lookup (not both), otherwise the request will be rejected.\n"},{"name":"person_linkedin_url","in":"query","required":false,"schema":{"type":"string","format":"uri"},"description":"The person LinkedIn URL. The URL is normalized to https://www.linkedin.com/in/{slug}.\n"},{"name":"degree","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","enum":["first","second","third"]}},"example":["first","second"],"description":"Filter paths by connection degree (first, second, or third degree). Available for both people and company lookups."},{"name":"path_relationship_strength","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","enum":["weak","medium","strong"]}},"example":["medium","strong"],"description":"Filter paths by path relationship strength."},{"name":"path_relationship_type","in":"query","required":false,"schema":{"type":"string","nullable":true,"enum":["deterministic","probabilistic"]},"example":"deterministic","description":"Filter paths by path relationship type. Deterministic means that all nodes in the path are connected to each other via email or LinkedIn connections, while probabilistic means that the connection between the connector and the target person is predicted based on publicly available career and education overlap signals.\n"},{"name":"is_target_persona","in":"query","required":false,"schema":{"type":"boolean"},"example":true,"description":"Filter results to include only paths to people marked as target personas. Target personas are defined by your organization admin in the CTD application and may not be configured. Available for company lookup only."},{"name":"target_title","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"example":["CEO","CTO","VP of Engineering"],"description":"Filter by job title. Returns paths to people whose job title contains the provided value as a case-insensitive substring. Available for company lookup only."},{"name":"target_seniority","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","enum":["Owner","CEO","CXO","Partner","VP","Manager","Director","Principal","Senior","EA","Board","Investor","Advisor","Founder","Consultant","Entry","Unpaid","Training"]}},"example":["CEO"],"description":"Filter by seniority level using predefined seniority categories. Matching is case-insensitive. Available for company lookup only."},{"name":"target_function","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","enum":["Travel","Media","Customer Success","Support","Education","Information Technology","Engineering","Finance","Health","Human Resources","Legal","Product","Operations","Design","Public Relations","Real Estate","Sales"]}},"example":["Engineering","Sales"],"description":"Filter by functional area using predefined function categories. Matching is case-insensitive. Available for company lookup only."},{"name":"path_stage","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","enum":["Not started","To do","Approaching Connector","Approaching Target","Successful","Unsuccessful","Not relevant","Bad data"]}},"example":["To do","Approaching Connector"],"description":"Filter paths by stage. Stage values are trimmed and matched case-insensitively. Available for both people and company lookups.\n"},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":40},"example":20,"description":"Number of items to return per page. Maximum value is 40."},{"name":"start_item","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1},"example":1,"description":"Pagination starting index (1-based)."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicPathsResponseV2WithEdgeV2"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/enterprise/atc-paths-api/public/v2/paths/by-stage":{"get":{"operationId":"getPathsByStageV2","summary":"Paths filtered by stage","description":"Returns paths filtered by one or more path stages, across the user's network.","tags":["Paths"],"parameters":[{"name":"ctd-api-key","in":"header","required":true,"schema":{"type":"string"},"description":"Enterprise CTD API key, used for authentication."},{"name":"ctd-client-id","in":"header","required":true,"schema":{"type":"string","format":"email"},"description":"The user's organization email address, used for audit logging and access control validation."},{"name":"stage","in":"query","required":true,"schema":{"type":"array","items":{"type":"string","enum":["Not started","To do","Approaching Connector","Approaching Target","Successful","Unsuccessful","Not relevant","Bad data"]}},"example":["To do","Approaching Connector"],"description":"Filter paths by stage. At least one stage is required. Values are trimmed and matched case-insensitively.\n"},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":40,"default":40},"example":20,"description":"Number of items to return per page. Maximum value is 40."},{"name":"start_item","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1},"example":1,"description":"Pagination starting index (1-based)."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicGlobalPathsResponseV2"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/enterprise/atc-paths-api/public/v2/paths/{pathId}/stage":{"patch":{"operationId":"updatePathStageV2","summary":"Update path stage by path ID","description":"Updates the stage of a single path identified by its path ID for the authenticated enterprise. Pass back the `path_id` uuid returned by any path read. Returns 200 OK when the update is applied synchronously; returns 202 Accepted with `deferred: true` when the update has to be queued and will be reflected within a few hours. Also available at the identical `PATCH /enterprise/atc-paths-api/public/v1/paths/{pathId}/stage`.\n","tags":["Paths"],"parameters":[{"name":"ctd-api-key","in":"header","required":true,"schema":{"type":"string"},"description":"Enterprise CTD API key, used for authentication."},{"name":"ctd-client-id","in":"header","required":true,"schema":{"type":"string","format":"email"},"description":"The user's organization email address, used for audit logging and access control validation."},{"name":"pathId","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Uuid identifier of the path to update, as returned in `path_id` by any path read.\n"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["path_stage"],"properties":{"path_stage":{"type":"string","enum":["Not started","To do","Approaching Connector","Approaching Target","Successful","Unsuccessful","Not relevant","Bad data"],"example":"To do","description":"New stage to set for the path. Values are trimmed and matched case-insensitively."},"manual_note":{"type":"string","nullable":true,"example":"Waiting on a warm intro from the connector.","description":"Optional manual note to attach to the path stage. Pass an empty string or null to clear an existing note. Returned as `path_status_manual_note` on subsequent path reads.\n"}}}}}},"responses":{"200":{"description":"Path stage updated successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true}}}}}},"202":{"description":"Update accepted and queued. The change will be reflected within a few hours.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"deferred":{"type":"boolean","example":true},"message":{"type":"string","example":"Path stage update is queued and will be visible within a few hours."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/enterprise/atc-paths-api/public/v2/global/paths":{"get":{"operationId":"getGlobalPathsV2","summary":"Paths to a company or a person (global view)","description":"Returns enterprise-wide paths to the specified company or person through coworkers or external members. Results are not personalized per user. Edges include `relationship_via_company_domain`: email and meeting details between you or a co-worker and their contacts, counted only from company email and calendar accounts, when your enterprise admin has enabled it; its values depend on the member whose email is sent in `ctd-client-id`.\n","tags":["Paths"],"parameters":[{"name":"ctd-api-key","in":"header","required":true,"schema":{"type":"string"},"description":"Enterprise CTD API key, used for authentication."},{"name":"ctd-client-id","in":"header","required":true,"schema":{"type":"string","format":"email"},"description":"The user's organization email address, used for audit logging and access control validation."},{"name":"company_linkedin_url","in":"query","required":false,"schema":{"type":"string","format":"uri"},"description":"The company LinkedIn URL (preferred identifier). The URL is normalized to `https://www.linkedin.com/company/<slug>`. Exactly one of company_linkedin_url or company_domain must be provided for company-based lookup (not both), otherwise the request will be rejected.\n"},{"name":"company_domain","in":"query","required":false,"schema":{"type":"string"},"description":"The company primary domain (e.g., 'example.com'). The domain is normalized before processing. Exactly one of company_domain or company_linkedin_url must be provided for company-based lookup (not both), otherwise the request will be rejected.\n"},{"name":"person_linkedin_url","in":"query","required":false,"schema":{"type":"string","format":"uri"},"description":"The person LinkedIn URL. The URL is normalized to https://www.linkedin.com/in/{slug}.\n"},{"name":"degree","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","enum":["first","second","third"]}},"example":["first","second"],"description":"Filter paths by connection degree (first, second, or third degree). Available for both people and company lookups."},{"name":"path_relationship_strength","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","enum":["weak","medium","strong"]}},"example":["medium","strong"],"description":"Filter paths by path relationship strength."},{"name":"path_relationship_type","in":"query","required":false,"schema":{"type":"string","nullable":true,"enum":["deterministic","probabilistic"]},"example":"deterministic","description":"Filter paths by path relationship type. Deterministic means that all nodes in the path are connected to each other via email or LinkedIn connections, while probabilistic means that the connection between the connector and the target person is predicted based on publicly available career and education overlap signals.\n"},{"name":"is_target_persona","in":"query","required":false,"schema":{"type":"boolean"},"example":true,"description":"Filter results to include only paths to people marked as target personas. Target personas are defined by your organization admin in the CTD application and may not be configured. Available for company lookup only."},{"name":"target_title","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"example":["CEO","CTO","VP of Engineering"],"description":"Filter by job title. Returns paths to people whose job title contains the provided value as a case-insensitive substring. Available for company lookup only."},{"name":"target_seniority","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","enum":["Owner","CEO","CXO","Partner","VP","Manager","Director","Principal","Senior","EA","Board","Investor","Advisor","Founder","Consultant","Entry","Unpaid","Training"]}},"example":["CEO"],"description":"Filter by seniority level using predefined seniority categories. Matching is case-insensitive. Available for company lookup only."},{"name":"target_function","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","enum":["Travel","Media","Customer Success","Support","Education","Information Technology","Engineering","Finance","Health","Human Resources","Legal","Product","Operations","Design","Public Relations","Real Estate","Sales"]}},"example":["Engineering","Sales"],"description":"Filter by functional area using predefined function categories. Matching is case-insensitive. Available for company lookup only."},{"name":"path_stage","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","enum":["Not started","To do","Approaching Connector","Approaching Target","Successful","Unsuccessful","Not relevant","Bad data"]}},"example":["To do","Approaching Connector"],"description":"Filter paths by stage. Stage values are trimmed and matched case-insensitively. Available for both people and company lookups.\n"},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":40},"example":20,"description":"Number of items to return per page. Maximum value is 40."},{"name":"start_item","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1},"example":1,"description":"Pagination starting index (1-based)."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicGlobalPathsResponseV2WithEdgeV2"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/enterprise/atc-paths-api/public/v2/paths/connector":{"get":{"operationId":"getPathsByConnectorV2","summary":"Paths through a specific connector","description":"Paths that pass through the specified connector within your organization's network. Edges include `relationship_via_company_domain`: email and meeting details between you or a co-worker and their contacts, counted only from company email and calendar accounts, when your enterprise admin has enabled it.\n","tags":["Paths"],"parameters":[{"name":"ctd-api-key","in":"header","required":true,"schema":{"type":"string"},"description":"Enterprise CTD API key, used for authentication."},{"name":"ctd-client-id","in":"header","required":true,"schema":{"type":"string","format":"email"},"description":"The user's organization email address, used for audit logging and access control validation."},{"name":"connector_linkedin_url","in":"query","required":false,"schema":{"type":"string","format":"uri"},"description":"The connector LinkedIn URL (preferred identifier). LinkedIn URL is normalized to https://www.linkedin.com/in/{slug}. Exactly one of connector_linkedin_url or connector_email must be provided (not both), otherwise the request will be rejected.\n"},{"name":"connector_email","in":"query","required":false,"schema":{"type":"string","format":"email"},"description":"The connector email address. Exactly one of connector_email or connector_linkedin_url must be provided (not both), otherwise the request will be rejected.\n"},{"name":"degree","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","enum":["first","second","third"]}},"example":["first","second"],"description":"Filter paths by connection degree (first, second, or third degree)."},{"name":"path_relationship_strength","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","enum":["weak","medium","strong"]}},"example":["medium","strong"],"description":"Filter paths by path relationship strength."},{"name":"path_relationship_type","in":"query","required":false,"schema":{"type":"string","nullable":true,"enum":["deterministic","probabilistic"]},"example":"deterministic","description":"Filter paths by path relationship type. Deterministic means that all nodes in the path are connected to each other via email or LinkedIn connections, while probabilistic means that the connection between the connector and the target person is predicted based on publicly available career and education overlap signals.\n"},{"name":"is_target_persona","in":"query","required":false,"schema":{"type":"boolean"},"example":true,"description":"Filter results to include only paths to people marked as target personas. Target personas are defined by your organization admin in the CTD application and may not be configured.\n"},{"name":"target_title","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"example":["CEO","CTO","VP of Engineering"],"description":"Filter by job title. Returns paths to people whose job title contains the provided value as a case-insensitive substring."},{"name":"target_seniority","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","enum":["Owner","CEO","CXO","Partner","VP","Manager","Director","Principal","Senior","EA","Board","Investor","Advisor","Founder","Consultant","Entry","Unpaid","Training"]}},"example":["CEO"],"description":"Filter by seniority level using predefined seniority categories; matching is case-insensitive."},{"name":"target_function","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","enum":["Travel","Media","Customer Success","Support","Education","Information Technology","Engineering","Finance","Health","Human Resources","Legal","Product","Operations","Design","Public Relations","Real Estate","Sales"]}},"example":["Engineering","Sales"],"description":"Filter by functional area using predefined function categories. Matching is case-insensitive."},{"name":"path_stage","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","enum":["Not started","To do","Approaching Connector","Approaching Target","Successful","Unsuccessful","Not relevant","Bad data"]}},"example":["To do","Approaching Connector"],"description":"Filter paths by stage. Returns only paths in the specified stage. Values are trimmed and matched case-insensitively.\n"},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":40},"example":20,"description":"Number of items to return per page. Maximum value is 40."},{"name":"start_item","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1},"example":1,"description":"Pagination starting index (1-based)."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicPathsResponseV2WithEdgeV2"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/enterprise/atc-paths-api/public/v2/global/paths/connector":{"get":{"operationId":"getGlobalPathsByConnectorV2","summary":"Paths through a specific connector (global view)","description":"Returns a paginated list of paths that pass through the specified connector within your organization's network. Edges include `relationship_via_company_domain`: email and meeting details between you or a co-worker and their contacts, counted only from company email and calendar accounts, when your enterprise admin has enabled it; its values depend on the member whose email is sent in `ctd-client-id`.\n","tags":["Paths"],"parameters":[{"name":"ctd-api-key","in":"header","required":true,"schema":{"type":"string"},"description":"Enterprise CTD API key, used for authentication."},{"name":"ctd-client-id","in":"header","required":true,"schema":{"type":"string","format":"email"},"description":"The user's organization email address, used for audit logging and access control validation."},{"name":"connector_linkedin_url","in":"query","required":false,"schema":{"type":"string","format":"uri"},"description":"The connector LinkedIn URL (preferred identifier). LinkedIn URL is normalized to https://www.linkedin.com/in/{slug}. Exactly one of connector_linkedin_url or connector_email must be provided (not both), otherwise the request will be rejected.\n"},{"name":"connector_email","in":"query","required":false,"schema":{"type":"string","format":"email"},"description":"The connector email address. Exactly one of connector_email or connector_linkedin_url must be provided (not both), otherwise the request will be rejected.\n"},{"name":"degree","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","enum":["first","second","third"]}},"example":["first","second"],"description":"Filter paths by connection degree (first, second, or third degree)."},{"name":"path_relationship_strength","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","enum":["weak","medium","strong"]}},"example":["medium","strong"],"description":"Filter paths by path relationship strength."},{"name":"path_relationship_type","in":"query","required":false,"schema":{"type":"string","nullable":true,"enum":["deterministic","probabilistic"]},"example":"deterministic","description":"Filter paths by path relationship type. Deterministic means that all nodes in the path are connected to each other via email or LinkedIn connections, while probabilistic means that the connection between the connector and the target person is predicted based on publicly available career and education overlap signals.\n"},{"name":"is_target_persona","in":"query","required":false,"schema":{"type":"boolean"},"example":true,"description":"Filter results to include only paths to people marked as target personas. Target personas are defined by your organization admin in the CTD application and may not be configured.\n"},{"name":"target_title","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"example":["CEO","CTO","VP of Engineering"],"description":"Filter by job title. Returns paths to people whose job title contains the provided value as a case-insensitive substring."},{"name":"target_seniority","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","enum":["Owner","CEO","CXO","Partner","VP","Manager","Director","Principal","Senior","EA","Board","Investor","Advisor","Founder","Consultant","Entry","Unpaid","Training"]}},"example":["CEO"],"description":"Filter by seniority level using predefined seniority categories; matching is case-insensitive."},{"name":"target_function","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","enum":["Travel","Media","Customer Success","Support","Education","Information Technology","Engineering","Finance","Health","Human Resources","Legal","Product","Operations","Design","Public Relations","Real Estate","Sales"]}},"example":["Engineering","Sales"],"description":"Filter by functional area using predefined function categories. Matching is case-insensitive."},{"name":"path_stage","in":"query","required":false,"schema":{"type":"array","items":{"type":"string","enum":["Not started","To do","Approaching Connector","Approaching Target","Successful","Unsuccessful","Not relevant","Bad data"]}},"example":["To do","Approaching Connector"],"description":"Filter paths by stage. Returns only paths in the specified stage. Values are trimmed and matched case-insensitively.\n"},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":40},"example":20,"description":"Number of items to return per page. Maximum value is 40."},{"name":"start_item","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1},"example":1,"description":"Pagination starting index (1-based)."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicGlobalPathsResponseV2WithEdgeV2"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/enterprise/asks-api/public/v1/activities":{"get":{"operationId":"getActivities","summary":"Asks and ghost emails activity","description":"Returns a paginated list of asks and ghost emails activity for the authenticated enterprise, with optional filters on initiator, connector, status and type. Results are ordered by most recent update.\n","tags":["Activities"],"parameters":[{"name":"ctd-api-key","in":"header","required":true,"schema":{"type":"string"},"description":"Your CTD API key, used for authentication."},{"name":"ctd-client-id","in":"header","required":true,"schema":{"type":"string","format":"email"},"description":"Your organization email address, used for audit logging and access control validation."},{"name":"initiator_email_address","in":"query","required":false,"schema":{"oneOf":[{"type":"string","format":"email"},{"type":"array","items":{"type":"string","format":"email"},"minItems":1}]},"description":"Filter activities by initiator email address. Accepts a single value or an array of values."},{"name":"connector_email_address","in":"query","required":false,"schema":{"oneOf":[{"type":"string","format":"email"},{"type":"array","items":{"type":"string","format":"email"},"minItems":1}]},"description":"Filter activities by connector email address. Accepts a single value or an array of values."},{"name":"connector_linkedin_url","in":"query","required":false,"schema":{"oneOf":[{"type":"string","format":"uri"},{"type":"array","items":{"type":"string","format":"uri"},"minItems":1}]},"description":"Filter activities by connector LinkedIn URL. The URL is normalized to `https://www.linkedin.com/in/<slug>`. Accepts a single value or an array of values.\n"},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["pending","sent","declined","unresponsive","replied","introduced","not_shared","meeting_scheduled"]},"example":"sent","description":"Filter activities by status."},{"name":"type","in":"query","required":false,"schema":{"type":"string","enum":["ask","ghost"]},"example":"ask","description":"Filter activities by type. `ask` returns regular asks, `ghost` returns ghost emails."},{"name":"start_item","in":"query","required":false,"schema":{"type":"integer","minimum":1,"default":1},"example":1,"description":"Pagination starting index (1-based)."},{"name":"page_size","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":40,"default":40},"example":20,"description":"Number of items to return per page. Maximum value is 40."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicActivitiesResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/enterprise/atc-paths-api/public/v1/target-accounts/imports":{"post":{"operationId":"createTargetAccountImport","summary":"Create a target accounts import","description":"Starts a new target accounts import for the authenticated enterprise and returns an import identifier. The created import is opened in the `ACCEPTING_BATCHES` state, after which rows are uploaded in one or more calls to `POST /target-accounts` referencing the returned `import_id`. Sending the final batch with `last_batch: true` closes the import and queues it for processing.\n","tags":["Target Accounts"],"parameters":[{"name":"ctd-api-key","in":"header","required":true,"schema":{"type":"string"},"description":"Enterprise CTD API key, used for authentication."},{"name":"ctd-client-id","in":"header","required":true,"schema":{"type":"string","format":"email"},"description":"The user's organization email address, used for audit logging and access control validation."}],"responses":{"200":{"description":"Import created and ready to accept batches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TargetAccountImportCreatedResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/enterprise/atc-paths-api/public/v1/target-accounts/imports/{import_id}":{"get":{"operationId":"getTargetAccountImportStatus","summary":"Get target accounts import status","description":"Returns the current status and progress counters of a previously created target accounts import, identified by its `import_id`. Use this to poll an import until it reaches a terminal state (`COMPLETED`, `STALE_PROMOTED_COMPLETED`, or `FAILED`).\n","tags":["Target Accounts"],"parameters":[{"name":"ctd-api-key","in":"header","required":true,"schema":{"type":"string"},"description":"Enterprise CTD API key, used for authentication."},{"name":"ctd-client-id","in":"header","required":true,"schema":{"type":"string","format":"email"},"description":"The user's organization email address, used for audit logging and access control validation."},{"name":"import_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Identifier of the import to retrieve, as returned when the import was created."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TargetAccountImportStatusResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/enterprise/atc-paths-api/public/v1/target-accounts":{"post":{"operationId":"addTargetAccountsBatch","summary":"Add a batch of target accounts to an import","description":"Uploads a batch of target account rows to an existing import that is in the `ACCEPTING_BATCHES` state. Each row must provide at least one of `website` or `linkedin_url`; rows that provide neither are rejected and reported in `failed_reasons` without failing the rest of the batch.\nSet `last_batch` to `true` on the final batch to close the import and queue it for processing; the import then transitions out of `ACCEPTING_BATCHES` and will no longer accept further batches.\n","tags":["Target Accounts"],"parameters":[{"name":"ctd-api-key","in":"header","required":true,"schema":{"type":"string"},"description":"Enterprise CTD API key, used for authentication."},{"name":"ctd-client-id","in":"header","required":true,"schema":{"type":"string","format":"email"},"description":"The user's organization email address, used for audit logging and access control validation."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddTargetAccountsBatchRequest"}}}},"responses":{"200":{"description":"Batch processed. Returns counts of inserted and failed rows.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddTargetAccountsBatchResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}},"delete":{"operationId":"deleteAllTargetAccounts","summary":"Delete all target accounts","description":"Queues deletion of all target accounts for the authenticated enterprise. The deletion is performed asynchronously: the endpoint responds with `202 Accepted` and an `import_id` of type `DELETE_ALL` that can be polled via `GET /target-accounts/imports/{import_id}` to track completion.\n","tags":["Target Accounts"],"parameters":[{"name":"ctd-api-key","in":"header","required":true,"schema":{"type":"string"},"description":"Enterprise CTD API key, used for authentication."},{"name":"ctd-client-id","in":"header","required":true,"schema":{"type":"string","format":"email"},"description":"The user's organization email address, used for audit logging and access control validation."}],"responses":{"202":{"description":"Deletion accepted and queued. Poll the returned import to track completion.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TargetAccountImportCreatedResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/enterprise/atc-paths-api/public/v1/custom-columns-names":{"get":{"operationId":"getCustomColumnNames","summary":"Custom column display names","description":"Returns the mapping between the public custom column names and the display names configured by your organization. The display names are the labels shown for the renameable custom columns (`custom_1`–`custom_4` and `custom_account_owner`) used across the public API responses.\n","tags":["Custom Columns"],"parameters":[{"name":"ctd-api-key","in":"header","required":true,"schema":{"type":"string"},"description":"Enterprise CTD API key, used for authentication."},{"name":"ctd-client-id","in":"header","required":true,"schema":{"type":"string","format":"email"},"description":"The user's organization email address, used for audit logging and access control validation."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCustomColumnNamesResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/enterprise/atc-paths-api/public/v1/rename-custom-columns":{"patch":{"operationId":"renameCustomColumnNames","summary":"Rename custom column display names","description":"Updates the display names for one or more renameable custom columns for the authenticated enterprise. Only the columns `custom_1`, `custom_2`, `custom_3`, `custom_4`, and `custom_account_owner` can be renamed. Each `column_name` may appear at most once in the request. Returns the updated mapping.\n","tags":["Custom Columns"],"parameters":[{"name":"ctd-api-key","in":"header","required":true,"schema":{"type":"string"},"description":"Enterprise CTD API key, used for authentication."},{"name":"ctd-client-id","in":"header","required":true,"schema":{"type":"string","format":"email"},"description":"The user's organization email address, used for audit logging and access control validation."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RenameCustomColumnsRequest"}}}},"responses":{"200":{"description":"Custom column display names updated successfully. Returns the updated mapping.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicCustomColumnNamesResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/enterprise/enterprise-api/public/v1/external-members":{"get":{"operationId":"getExternalMembers","summary":"External members (reporting view)","deprecated":true,"description":"Superseded by `GET /v2/external-members`, which is paginated, returns ids and slugs, and has the full member API next to it. This endpoint keeps working.\nReturns the full list of external members for the authenticated enterprise, including their status, type, onboarding progress and invitation history. The onboarding flags (`email_account_added`, `linkedin_account_added`) and `num_contacts` are only populated for accepted members; for every other status they fall back to `false`/`false`/`0`.\n","tags":["External Members"],"parameters":[{"name":"ctd-api-key","in":"header","required":true,"schema":{"type":"string"},"description":"Enterprise CTD API key, used for authentication."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicExternalMembersResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/v2/external-members":{"get":{"operationId":"listExternalMembersV2","summary":"List external members","description":"Paginated roster of the enterprise's external members. Deactivated and archived members are left out unless `status` or `include_archived` asks for them. Only an enterprise admin can call the external members endpoints; `ctd-client-id` must be an admin of the key's enterprise.\n","tags":["External Members"],"parameters":[{"$ref":"#/components/parameters/CtdApiKey"},{"$ref":"#/components/parameters/CtdClientId"},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"status","in":"query","description":"Repeat for several statuses.","schema":{"type":"array","items":{"$ref":"#/components/schemas/ExternalMemberStatus"}}},{"name":"type","in":"query","description":"Member type slugs (see `GET /v2/external-member-types`). Repeat for several.","schema":{"type":"array","items":{"type":"string"}}},{"name":"relationship_owner","in":"query","description":"Email of the enterprise user who owns the relationship. Repeat for several.","schema":{"type":"array","items":{"type":"string","format":"email"}}},{"name":"email","in":"query","description":"Email contains this text.","schema":{"type":"string"}},{"name":"name","in":"query","description":"Name contains this text.","schema":{"type":"string"}},{"name":"linkedin_url","in":"query","description":"LinkedIn profile URL or slug. Repeat for several.","schema":{"type":"array","items":{"type":"string"}}},{"name":"company_id","in":"query","schema":{"type":"array","items":{"type":"string","format":"uuid"}}},{"name":"tier","in":"query","description":"1 to 4, or `unassigned`. Repeat for several.","schema":{"type":"array","items":{"type":"string","enum":["1","2","3","4","unassigned"]}}},{"name":"include_archived","in":"query","schema":{"type":"boolean","default":false}},{"name":"created_from","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"created_to","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"order_by","in":"query","schema":{"type":"string","enum":["created_at","name","status","type","sent_at","accepted_at","email"],"default":"created_at"}},{"name":"order_dir","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"desc"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ExternalMemberV2"}},"total_count":{"type":"integer"},"status_counts":{"type":"object","additionalProperties":{"type":"integer"},"example":{"to_be_invited":40,"pending":10,"accepted":25}},"max_external_members":{"type":"integer","nullable":true,"description":"The plan's member cap, or null for none."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalServerError"}}},"post":{"operationId":"addExternalMembersV2","summary":"Add external members (not invited)","description":"Adds people to the roster with status `to_be_invited`, or updates the members they match. Name each person by `linkedin_url` (preferred), `email` or `external_member_id`. A row that matches a stored member updates it and leaves the fields it omits alone. A person added by LinkedIn only gets an email filled in when the enterprise has one. `type` defaults to `other` for a new member. Every row gets its own result, in request order.\nA coworker is never an external member: a row whose address belongs to a member of the workspace, to its company directory or to one of its email domains fails with `reason_code` `coworker`. A workspace admin adds coworkers from Members.\n","tags":["External Members"],"parameters":[{"$ref":"#/components/parameters/CtdApiKey"},{"$ref":"#/components/parameters/CtdClientId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["members"],"properties":{"members":{"type":"array","minItems":1,"maxItems":2000,"items":{"$ref":"#/components/schemas/ExternalMemberUpsertV2"}}}}}}},"responses":{"200":{"description":"One result per row, in request order.","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/ExternalMemberUpsertResultV2"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"500":{"$ref":"#/components/responses/InternalServerError"}}},"patch":{"operationId":"bulkUpdateExternalMembersV2","summary":"Update several external members","description":"Applies the same values to up to 100 members.","tags":["External Members"],"parameters":[{"$ref":"#/components/parameters/CtdApiKey"},{"$ref":"#/components/parameters/CtdClientId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ids","values"],"properties":{"ids":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","format":"uuid"}},"values":{"type":"object","minProperties":1,"properties":{"type":{"type":"string"},"relationship_owner":{"type":"string","format":"email","nullable":true},"tier":{"type":"integer","minimum":1,"maximum":4,"nullable":true},"visible_in_paths":{"type":"boolean"},"is_archived":{"type":"boolean"},"ask_budget":{"$ref":"#/components/schemas/AskBudget"}}}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"updated_count":{"type":"integer"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/v2/external-members/lookup":{"get":{"operationId":"lookupExternalMemberV2","summary":"Find one external member by email or LinkedIn","description":"Pass exactly one of `email` or `linkedin_url`. Archived and deactivated members are found too. 404 when nobody matches; 409, with the matching ids in `details`, when a LinkedIn profile matches more than one member.\n","tags":["External Members"],"parameters":[{"$ref":"#/components/parameters/CtdApiKey"},{"$ref":"#/components/parameters/CtdClientId"},{"name":"email","in":"query","schema":{"type":"string","format":"email"}},{"name":"linkedin_url","in":"query","description":"LinkedIn profile URL or slug.","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalMemberDetailV2"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/v2/external-members/invite-link":{"get":{"operationId":"getWorkspaceInviteLinkV2","summary":"Workspace invite link","description":"The one link external members join through, for outreach sent outside CTD. Someone already on the roster who signs up through it is accepted; anyone else waits for an admin to approve. The link is for people outside the company: a coworker who signs up through it is refused.\n","tags":["External Members"],"parameters":[{"$ref":"#/components/parameters/CtdApiKey"},{"$ref":"#/components/parameters/CtdClientId"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"invite_link":{"type":"string","example":"https://app.ctd.ai/supergraph-invitation?enterprise_invite_code=0b6f2c1e-4a7d-4e2b-9c3f-1d2e3f4a5b6c"},"audience":{"type":"string","enum":["external"],"description":"Who the link is for."},"note":{"type":"string","example":"For people outside the workspace. Coworkers are added by a workspace admin from Members."}}}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/v2/external-members/coworker-check":{"post":{"operationId":"checkCoworkersV2","summary":"Find the coworkers among addresses","description":"Which of these addresses belong to coworkers of the workspace, so nobody sends them an external-member invite. `member`: the CTD user behind the address is licensed in the workspace (on any of their addresses), or holds or was invited to a Team Edition seat. `directory`: the address belongs to someone in the company directory. `domain`: the address is on one of the workspace's email domains. Addresses not listed are not coworkers'.\n","tags":["External Members"],"parameters":[{"$ref":"#/components/parameters/CtdApiKey"},{"$ref":"#/components/parameters/CtdClientId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["emails"],"properties":{"emails":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","format":"email"}}}}}}},"responses":{"200":{"description":"The coworkers among the addresses, lowercased.","content":{"application/json":{"schema":{"type":"object","properties":{"coworkers":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string","format":"email"},"reason":{"type":"string","enum":["member","directory","domain"]}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/v2/external-members/validate":{"post":{"operationId":"validateExternalMembersV2","summary":"Dry run of adding external members","description":"Same body as `POST /v2/external-members`; writes nothing and says what would be added, what conflicts and what would be skipped. A skipped row carries its `reason`, and `reason_code` `coworker` when the address is a coworker's.\n","tags":["External Members"],"parameters":[{"$ref":"#/components/parameters/CtdApiKey"},{"$ref":"#/components/parameters/CtdClientId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["members"],"properties":{"members":{"type":"array","minItems":1,"maxItems":2000,"items":{"$ref":"#/components/schemas/ExternalMemberUpsertV2"}}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"added":{"type":"object","properties":{"count":{"type":"integer"},"members":{"type":"array","items":{"type":"object"}}}},"conflicts":{"type":"object","properties":{"count":{"type":"integer"},"members":{"type":"array","items":{"type":"object"}}}},"skipped":{"type":"object","properties":{"count":{"type":"integer"},"members":{"type":"array","items":{"type":"object"}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/v2/external-members/invite":{"post":{"operationId":"inviteExternalMembersV2","summary":"Invite external members","description":"Invites members through a ghost message carrying the workspace invite link.\n**Who acts.** Without `from`, or with the calling admin's own address, CTD sends it from the calling admin's mailbox. With `from` set to another user of the enterprise, CTD never sends as them: the ghost message is shared with them to review and send themselves, and the members wait (`waiting_to_be_sent`) until they do.\n**Channel.** `email` (default) sends one email per member, cc cs@ctd.ai. `linkedin` or `phone` prepares one plain-text message per member that the holder pastes into LinkedIn or a text and then marks sent; CTD never sends those. Members with no email can only be invited on `linkedin` or `phone`.\n**Message.** Leave `subject` and `body` out for the standard invite. The variables are `{{first_name}}`, `{{last_name}}`, `{{company_name}}`, `{{inviter_name}}`, `{{inviter_first_name}}` and `{{invite_link}}`; any other variable is a 400.\n**Coworkers.** A member whose address is a coworker's is skipped with reason `coworker` and is never sent an invite; a workspace admin adds coworkers from Members.\n","tags":["External Members"],"parameters":[{"$ref":"#/components/parameters/CtdApiKey"},{"$ref":"#/components/parameters/CtdClientId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","format":"uuid"}},"channel":{"type":"string","enum":["email","linkedin","phone"],"default":"email"},"from":{"type":"string","format":"email","description":"Who the message is from. Another user's address shares it with them instead of sending."},"should_notify":{"type":"boolean","default":true,"description":"Only with `from` set to another user. `false` skips the \"shared with you\" email, for bulk sharing."},"note":{"type":"string","maxLength":1000,"description":"Only with `from` set to another user. Shown to them next to the ghost message."},"subject":{"type":"string","maxLength":500,"description":"Email only."},"body":{"type":"string","maxLength":20000},"cc":{"type":"array","maxItems":10,"items":{"type":"string","format":"email"},"description":"Email only. Default [\"cs@ctd.ai\"]; [] for none."},"metadata":{"type":"object","maxProperties":20,"additionalProperties":{"type":"string","maxLength":500},"description":"Key/values stored on the ghost message. Keys may not start with `ctd_`."}}}}}},"responses":{"200":{"description":"What happened to each member.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalMemberInviteResultV2"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/v2/external-members/{external_member_id}":{"get":{"operationId":"getExternalMemberV2","summary":"Get an external member","tags":["External Members"],"parameters":[{"$ref":"#/components/parameters/CtdApiKey"},{"$ref":"#/components/parameters/CtdClientId"},{"$ref":"#/components/parameters/ExternalMemberId"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalMemberDetailV2"}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}},"patch":{"operationId":"updateExternalMemberV2","summary":"Update an external member","description":"Send only the fields to change. `null` clears `relationship_owner`, `email`, `linkedin_url`, `tier`, `about`, `ask_budget` and `signature`. `email` can change only while the invite is unanswered, and never to a coworker's address (409, code 10.4.36). Returns the member as `GET` does.\n","tags":["External Members"],"parameters":[{"$ref":"#/components/parameters/CtdApiKey"},{"$ref":"#/components/parameters/CtdClientId"},{"$ref":"#/components/parameters/ExternalMemberId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","minProperties":1,"properties":{"type":{"type":"string"},"relationship_owner":{"type":"string","format":"email","nullable":true},"email":{"type":"string","format":"email","nullable":true},"linkedin_url":{"type":"string","nullable":true},"tier":{"type":"integer","minimum":1,"maximum":4,"nullable":true},"visible_in_paths":{"type":"boolean"},"is_archived":{"type":"boolean"},"about":{"type":"string","maxLength":5000,"nullable":true},"ask_budget":{"$ref":"#/components/schemas/AskBudget"},"signature":{"type":"string","maxLength":10000,"nullable":true,"description":"HTML."}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalMemberDetailV2"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"500":{"$ref":"#/components/responses/InternalServerError"}}},"delete":{"operationId":"deleteExternalMemberV2","summary":"Delete an external member","description":"Deletes the member in any status. An accepted member leaves the enterprise first, so their network stops feeding its paths; their own CTD account is untouched. Uploaded LinkedIn connections are deleted with them.\n","tags":["External Members"],"parameters":[{"$ref":"#/components/parameters/CtdApiKey"},{"$ref":"#/components/parameters/CtdClientId"},{"$ref":"#/components/parameters/ExternalMemberId"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"external_member_id":{"type":"string","format":"uuid"},"email":{"type":"string","nullable":true},"status_before":{"$ref":"#/components/schemas/ExternalMemberStatus"}}}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/v2/external-members/{external_member_id}/linkedin-connections":{"post":{"operationId":"uploadExternalMemberLinkedinConnectionsV2","summary":"Upload a member's LinkedIn connections","description":"LinkedIn's Connections.csv export, sent as `multipart/form-data` in the `file` field, at most 20 MB. Replaces whatever was uploaded for this member before; an unreadable file keeps the previous set. Answers 202: the contacts are stored, enrichment and path generation continue.\n","tags":["External Members"],"parameters":[{"$ref":"#/components/parameters/CtdApiKey"},{"$ref":"#/components/parameters/CtdClientId"},{"$ref":"#/components/parameters/ExternalMemberId"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary"}}}}}},"responses":{"202":{"description":"Stored; enrichment continues.","content":{"application/json":{"schema":{"type":"object","properties":{"external_member_id":{"type":"string","format":"uuid"},"csv_data_row_count":{"type":"integer"},"stored_contact_count":{"type":"integer"},"enrichment_status":{"type":"string","enum":["resolving","enriching","completed","failed"]}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"500":{"$ref":"#/components/responses/InternalServerError"}}},"get":{"operationId":"getExternalMemberLinkedinConnectionsV2","summary":"A member's uploaded LinkedIn connections","tags":["External Members"],"parameters":[{"$ref":"#/components/parameters/CtdApiKey"},{"$ref":"#/components/parameters/CtdClientId"},{"$ref":"#/components/parameters/ExternalMemberId"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"stored_contact_count":{"type":"integer"},"file_name":{"type":"string","nullable":true},"uploaded_at":{"type":"string","format":"date-time","nullable":true},"enrichment_status":{"type":"string","enum":["resolving","enriching","completed","failed"],"nullable":true}}}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}},"delete":{"operationId":"deleteExternalMemberLinkedinConnectionsV2","summary":"Delete a member's uploaded LinkedIn connections","tags":["External Members"],"parameters":[{"$ref":"#/components/parameters/CtdApiKey"},{"$ref":"#/components/parameters/CtdClientId"},{"$ref":"#/components/parameters/ExternalMemberId"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"external_member_id":{"type":"string","format":"uuid"},"deleted":{"type":"boolean"}}}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/v2/external-member-types":{"get":{"operationId":"listExternalMemberTypesV2","summary":"List external member types","description":"Members refer to a type by its slug. Default types (`is_default`) cannot be renamed or deleted.","tags":["External Member Types"],"parameters":[{"$ref":"#/components/parameters/CtdApiKey"},{"$ref":"#/components/parameters/CtdClientId"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ExternalMemberTypeV2"}}}}},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalServerError"}}},"post":{"operationId":"createExternalMemberTypeV2","summary":"Create an external member type","description":"The slug is derived from the name (\"Limited Partner\" becomes `limited_partner`) and never changes; a name that repeats an existing slug is a 409.","tags":["External Member Types"],"parameters":[{"$ref":"#/components/parameters/CtdApiKey"},{"$ref":"#/components/parameters/CtdClientId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":1,"maxLength":100},"description":{"type":"string","maxLength":1000,"nullable":true}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalMemberTypeV2"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"409":{"$ref":"#/components/responses/Conflict"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/v2/external-member-types/{type_id}":{"patch":{"operationId":"updateExternalMemberTypeV2","summary":"Update an external member type","tags":["External Member Types"],"parameters":[{"$ref":"#/components/parameters/CtdApiKey"},{"$ref":"#/components/parameters/CtdClientId"},{"$ref":"#/components/parameters/TypeId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","minProperties":1,"properties":{"name":{"type":"string","minLength":1,"maxLength":100},"description":{"type":"string","maxLength":1000,"nullable":true}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalMemberTypeV2"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"500":{"$ref":"#/components/responses/InternalServerError"}}},"delete":{"operationId":"deleteExternalMemberTypeV2","summary":"Delete an external member type","description":"Members of the deleted type move to `other`. Default types cannot be deleted (409).","tags":["External Member Types"],"parameters":[{"$ref":"#/components/parameters/CtdApiKey"},{"$ref":"#/components/parameters/CtdClientId"},{"$ref":"#/components/parameters/TypeId"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"deleted":{"type":"boolean"}}}}}},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/v2/users":{"get":{"operationId":"listWorkspaceUsersV2","summary":"List workspace users","description":"Paginated list of the people with a seat in the workspace, as the admin console's User Management page shows them. One `status` per call, default `active`, newest first. Only a workspace admin can call the users endpoints; `ctd-client-id` must be an admin of the key's workspace. Team Edition workspaces answer 403 on every users endpoint. People are identified by email, never by an id.\n","tags":["Users"],"parameters":[{"$ref":"#/components/parameters/CtdApiKey"},{"$ref":"#/components/parameters/CtdClientId"},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"status","in":"query","description":"One status per call. Default `active`.","schema":{"$ref":"#/components/schemas/WorkspaceUserStatus"}},{"name":"name","in":"query","description":"Name contains this text.","schema":{"type":"string"}},{"name":"is_admin","in":"query","schema":{"type":"boolean"}},{"name":"tier","in":"query","description":"1 to 4, or `unassigned`.","schema":{"type":"string","enum":["1","2","3","4","unassigned"]}},{"name":"visible_in_paths","in":"query","schema":{"type":"boolean"}},{"name":"linkedin_synced","in":"query","schema":{"type":"boolean"}},{"name":"last_active_before","in":"query","description":"Users last active on or before this date. The way to find dormant seats.","schema":{"type":"string","format":"date-time"}},{"name":"last_active_after","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"created_from","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"created_to","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"order_by","in":"query","schema":{"type":"string","enum":["created_at","name","network_score","last_active_at","contacts_count"],"default":"created_at"}},{"name":"order_dir","in":"query","description":"Default `desc` (newest or highest first), `asc` for `name`.","schema":{"type":"string","enum":["asc","desc"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WorkspaceUserV2"}},"total_count":{"type":"integer","description":"For the requested status and filters."},"offset":{"type":"integer"},"limit":{"type":"integer"},"next_offset":{"type":"integer","nullable":true,"description":"Pass as `offset` for the next page. Null on the last page."},"counts":{"type":"object","description":"The whole workspace, whatever the filters. Refreshed at most once a minute.","properties":{"active":{"type":"integer"},"not_activated":{"type":"integer"},"deactivated":{"type":"integer"},"legacy":{"type":"integer"}},"example":{"active":1130,"not_activated":92,"deactivated":41,"legacy":21}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalServerError"}}},"post":{"operationId":"addWorkspaceUsersV2","summary":"Add workspace users","description":"Gives a seat to each address, which must be on a workspace domain. A new account is provisioned in the background (`added`) and is listed as `active` within seconds; an existing account on the domain, including a deactivated one, gets the seat back (`activated`). There is no separate activate endpoint. One result per address, in order. A seat is billable.\n","tags":["Users"],"parameters":[{"$ref":"#/components/parameters/CtdApiKey"},{"$ref":"#/components/parameters/CtdClientId"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["emails"],"properties":{"emails":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","format":"email"}},"mailbox_sync":{"type":"boolean","default":true,"description":"False adds the person without CTD ever reading their mailbox."}}}}}},"responses":{"200":{"description":"OK, with one result per address.","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/WorkspaceUserAddResultV2"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/v2/users/{email}":{"get":{"operationId":"getWorkspaceUserV2","summary":"Get a workspace user","description":"One person by email, with their workspace mailboxes and last activity per surface. Any of the person's workspace addresses resolves to them; the returned `email` is always the primary one. 404 means no CTD account with that address in the workspace.\n","tags":["Users"],"parameters":[{"$ref":"#/components/parameters/CtdApiKey"},{"$ref":"#/components/parameters/CtdClientId"},{"$ref":"#/components/parameters/UserEmail"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceUserDetailV2"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/v2/users/{email}/deactivate":{"post":{"operationId":"deactivateWorkspaceUserV2","summary":"Deactivate a workspace user","description":"Removes the seat and stops reading the person's mailboxes; their data is kept. Only an `active` user can be deactivated (409 otherwise), the calling admin cannot deactivate themselves (400), and repeating the call changes nothing. To give the seat back, add the address again with `POST /v2/users`.\n","tags":["Users"],"parameters":[{"$ref":"#/components/parameters/CtdApiKey"},{"$ref":"#/components/parameters/CtdClientId"},{"$ref":"#/components/parameters/UserEmail"}],"responses":{"200":{"description":"The user, now deactivated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceUserDetailV2"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/v2/users/{email}/make-admin":{"post":{"operationId":"makeWorkspaceAdminV2","summary":"Make a user a workspace admin","description":"Grants the workspace admin role to an `active` user (409 otherwise). Repeating the call on an admin changes nothing.\n","tags":["Users"],"parameters":[{"$ref":"#/components/parameters/CtdApiKey"},{"$ref":"#/components/parameters/CtdClientId"},{"$ref":"#/components/parameters/UserEmail"}],"responses":{"200":{"description":"The user, with `is_admin` true.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceUserDetailV2"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/v2/users/{email}/remove-admin":{"post":{"operationId":"removeWorkspaceAdminV2","summary":"Remove a user's workspace admin role","description":"Takes the admin role away; the person keeps their seat. The workspace's last admin cannot be removed (409) and the calling admin cannot remove themselves (400). Repeating the call on a non-admin changes nothing.\n","tags":["Users"],"parameters":[{"$ref":"#/components/parameters/CtdApiKey"},{"$ref":"#/components/parameters/CtdClientId"},{"$ref":"#/components/parameters/UserEmail"}],"responses":{"200":{"description":"The user, with `is_admin` false.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceUserDetailV2"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/Conflict"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/v2/api-usage":{"get":{"operationId":"getWorkspaceApiUsageV2","summary":"Get API and MCP usage","description":"Calls to the CTD API and to CTD MCP tools, and the credits they used, per UTC month, for the whole workspace or for one person. Every logged call counts, whatever its status or outcome. API calls made with a personal key and with the workspace key are added together; a workspace-key call counts under the admin whose `ctd-client-id` made it. History starts in late October 2026: earlier months are zero. Workspace totals include calls with no known caller, so they can be a little above the sum of `GET /v2/api-usage/users`. Only a workspace admin can call the usage endpoints.\n","tags":["Usage"],"parameters":[{"$ref":"#/components/parameters/CtdApiKey"},{"$ref":"#/components/parameters/CtdClientId"},{"$ref":"#/components/parameters/UsageFrom"},{"$ref":"#/components/parameters/UsageTo"},{"$ref":"#/components/parameters/UsageEmail"}],"responses":{"200":{"description":"Totals, and one row per month in the period, oldest first, zeros included.\n","content":{"application/json":{"schema":{"type":"object","properties":{"from":{"type":"string","example":"2026-09"},"to":{"type":"string","example":"2026-11"},"email":{"type":"string","nullable":true,"description":"The person's primary address when `email` was given, otherwise null."},"totals":{"$ref":"#/components/schemas/ApiUsageCountsV2"},"months":{"type":"array","items":{"allOf":[{"type":"object","properties":{"month":{"type":"string","example":"2026-10"}}},{"$ref":"#/components/schemas/ApiUsageCountsV2"}]}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/UsageTooSlow"}}}},"/v2/api-usage/users":{"get":{"operationId":"listWorkspaceApiUsageByUserV2","summary":"List API and MCP usage by person","description":"The people who made at least one API or MCP call in the period, with their totals, a page at a time. Calls with no known caller are left out. With `email`, `data` holds that one person, or is empty when they made no calls in the period. Only a workspace admin can call the usage endpoints.\n","tags":["Usage"],"parameters":[{"$ref":"#/components/parameters/CtdApiKey"},{"$ref":"#/components/parameters/CtdClientId"},{"$ref":"#/components/parameters/UsageFrom"},{"$ref":"#/components/parameters/UsageTo"},{"$ref":"#/components/parameters/UsageEmail"},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"sort","in":"query","schema":{"type":"string","enum":["total_calls","api_calls","mcp_calls","credits_used","last_used_at"],"default":"total_calls"}},{"name":"order","in":"query","description":"Ties keep a stable order, so pages do not overlap.","schema":{"type":"string","enum":["asc","desc"],"default":"desc"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"from":{"type":"string","example":"2026-09"},"to":{"type":"string","example":"2026-11"},"data":{"type":"array","items":{"allOf":[{"type":"object","properties":{"email":{"type":"string","nullable":true,"description":"Null, with `full_name` and `status`, when the CTD user no longer exists."},"full_name":{"type":"string","nullable":true},"status":{"allOf":[{"$ref":"#/components/schemas/WorkspaceUserStatus"}],"nullable":true},"last_used_at":{"type":"string","format":"date-time","description":"The person's latest call in the period."}}},{"$ref":"#/components/schemas/ApiUsageCountsV2"}]}},"total_count":{"type":"integer","description":"People with at least one call in the period."},"offset":{"type":"integer"},"limit":{"type":"integer"},"next_offset":{"type":"integer","nullable":true,"description":"Pass as `offset` for the next page. Null on the last page."}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"},"503":{"$ref":"#/components/responses/UsageTooSlow"}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"ctd-api-key","description":"Enterprise CTD API key, used for authentication."}},"parameters":{"CtdApiKey":{"name":"ctd-api-key","in":"header","required":true,"schema":{"type":"string"},"description":"Enterprise CTD API key (eak_...)."},"CtdClientId":{"name":"ctd-client-id","in":"header","required":true,"schema":{"type":"string","format":"email"},"description":"Email of an admin of the key's enterprise. Recorded as the author of changes."},"ExternalMemberId":{"name":"external_member_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"TypeId":{"name":"type_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"UserEmail":{"name":"email","in":"path","required":true,"schema":{"type":"string","format":"email"},"description":"The user's email. Case-insensitive; an alias resolves to the primary mailbox."},"UsageFrom":{"name":"from","in":"query","description":"First month, `YYYY-MM`, inclusive. Default two months before `to`, so three months in all.","schema":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$","example":"2026-09"}},"UsageTo":{"name":"to","in":"query","description":"Last month, `YYYY-MM`, inclusive. Default the current UTC month. `from` after `to`, a period over 24 months or a malformed month is a 400.\n","schema":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$","example":"2026-11"}},"UsageEmail":{"name":"email","in":"query","description":"Only this person, by primary address or alias. Anyone the workspace knows is found, whatever their status (licensed, deactivated, not activated or unlicensed), and so is anyone who made calls here. Someone with no calls gets zeros. Any other address is a 404.\n","schema":{"type":"string","format":"email"}}},"schemas":{"ExternalMemberStatus":{"type":"string","enum":["to_be_invited","waiting_to_be_sent","pending","accepted","to_be_approved","declined","deactivated"],"description":"to_be_invited = on the roster, not invited; waiting_to_be_sent = an invite ghost message waits on someone to send or mark it sent; pending = invited; to_be_approved = asked to join through the workspace link and waits for an admin.\n"},"AskBudget":{"type":"object","nullable":true,"description":"How often this person may be asked, over a rolling window (week = 7 days, month = 30, quarter = 90, year = 365). null for no limit. Informational; nothing refuses an ask over budget.\n","required":["limit","per"],"properties":{"limit":{"type":"integer","minimum":1,"maximum":1000,"example":5},"per":{"type":"string","enum":["week","month","quarter","year"],"example":"month"}}},"ExternalMemberV2":{"type":"object","properties":{"external_member_id":{"type":"string","format":"uuid"},"email":{"type":"string","nullable":true,"description":"Null for a member the enterprise has no address for."},"name":{"type":"string","nullable":true},"status":{"$ref":"#/components/schemas/ExternalMemberStatus"},"type":{"type":"string","nullable":true,"example":"investor","description":"Member type slug."},"relationship_owner":{"type":"string","format":"email","nullable":true},"relationship_owner_name":{"type":"string","nullable":true},"linkedin_url":{"type":"string","nullable":true,"description":"The URL the enterprise gave, else the profile CTD resolved for the person.","example":"https://www.linkedin.com/in/janedoe"},"company":{"type":"object","properties":{"company_id":{"type":"string","format":"uuid","nullable":true},"name":{"type":"string","nullable":true},"role_title":{"type":"string","nullable":true}}},"tier":{"type":"integer","minimum":1,"maximum":4,"nullable":true,"description":"null is unassigned."},"visible_in_paths":{"type":"boolean","nullable":true},"is_ctd_user":{"type":"boolean"},"email_account_added":{"type":"boolean","description":"The member connected an email account. Accepted members only."},"linkedin_account_added":{"type":"boolean","description":"The member synced their own LinkedIn connections. Accepted members only."},"contacts_count":{"type":"integer","description":"Their own contacts plus admin-uploaded LinkedIn connections."},"invited_by":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time","nullable":true},"sent_at":{"type":"string","format":"date-time","nullable":true},"accepted_at":{"type":"string","format":"date-time","nullable":true},"declined_at":{"type":"string","format":"date-time","nullable":true},"deactivated_at":{"type":"string","format":"date-time","nullable":true},"archived_at":{"type":"string","format":"date-time","nullable":true}}},"ExternalMemberDetailV2":{"allOf":[{"$ref":"#/components/schemas/ExternalMemberV2"},{"type":"object","properties":{"about":{"type":"string","nullable":true,"description":"Who they are to us. Visible to the whole enterprise."},"about_updated_at":{"type":"string","format":"date-time","nullable":true},"about_updated_by":{"type":"string","nullable":true},"ask_budget":{"$ref":"#/components/schemas/AskBudget"},"ask_activity":{"type":"object","nullable":true,"description":"Null when the counts could not be read.","properties":{"open_now":{"type":"integer"},"handed":{"type":"object","properties":{"last_30_days":{"type":"integer"},"last_90_days":{"type":"integer"},"last_180_days":{"type":"integer"},"all_time":{"type":"integer"}}},"sent_all_time":{"type":"integer"},"declined_all_time":{"type":"integer"},"last_asked_at":{"type":"string","format":"date-time","nullable":true},"remaining_in_period":{"type":"integer","nullable":true,"description":"Null without a budget."}}},"signature":{"type":"string","nullable":true,"description":"HTML email signature."},"signature_updated_at":{"type":"string","format":"date-time","nullable":true}}}]},"ExternalMemberUpsertV2":{"type":"object","description":"Needs at least one of linkedin_url, email or external_member_id.","properties":{"linkedin_url":{"type":"string","nullable":true,"example":"https://www.linkedin.com/in/janedoe"},"email":{"type":"string","format":"email","nullable":true},"external_member_id":{"type":"string","format":"uuid","nullable":true},"name":{"type":"string","description":"Used when CTD has no name for the person."},"type":{"type":"string","description":"Member type slug. Default other for a new member."},"relationship_owner":{"type":"string","format":"email","nullable":true},"tier":{"type":"integer","minimum":1,"maximum":4,"nullable":true}}},"ExternalMemberUpsertResultV2":{"type":"object","properties":{"status":{"type":"string","enum":["succeeded","failed"]},"external_member_id":{"type":"string","format":"uuid","nullable":true},"email":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"created":{"type":"boolean","description":"True when this row added a new member."},"member":{"$ref":"#/components/schemas/ExternalMemberV2"},"message":{"type":"string","description":"Why a failed row was not written."},"reason_code":{"type":"string","enum":["coworker"],"description":"Set on a failed row the caller can act on. `coworker`, the address is a coworker's; a workspace admin adds them from Members."}}},"ExternalMemberInviteResultV2":{"type":"object","properties":{"sent":{"type":"array","description":"Email invites CTD sent from the calling admin's mailbox.","items":{"type":"object","properties":{"external_member_id":{"type":"string","format":"uuid"},"email":{"type":"string","nullable":true},"ghost_email_id":{"type":"string","format":"uuid"}}}},"waiting":{"type":"array","description":"Ghost messages that wait on a person.","items":{"type":"object","properties":{"external_member_id":{"type":"string","format":"uuid"},"email":{"type":"string","nullable":true},"ghost_email_id":{"type":"string","format":"uuid"},"channel":{"type":"string","enum":["email","linkedin","phone"]},"holder":{"type":"string","format":"email","description":"Who must act."},"action":{"type":"string","enum":["send","mark_sent","share"]},"address_known":{"type":"boolean","description":"The LinkedIn profile or phone number is already on the message."},"web_url":{"type":"string","example":"https://app.ctd.ai/ghost-emails/email/e55a0000-0000-4000-8000-000000000000"},"error":{"type":"string","enum":["daily_ask_limit_reached","sender_mailbox_not_valid","send_failed","share_failed"],"description":"Set when CTD could not send or share it itself."}}}},"skipped":{"type":"array","items":{"type":"object","properties":{"external_member_id":{"type":"string","format":"uuid"},"email":{"type":"string","nullable":true},"reason":{"type":"string","enum":["not_found","no_email","no_channel_address","already_accepted","awaiting_approval","archived","coworker","send_failed"]}}}}}},"ExternalMemberTypeV2":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string","example":"investor"},"name":{"type":"string","example":"Investor"},"description":{"type":"string","nullable":true},"is_default":{"type":"boolean"},"members_count":{"type":"integer","description":"List only. Archived members excluded."},"archived_members_count":{"type":"integer","description":"List only."},"created_at":{"type":"string","format":"date-time"}}},"ApiUsageCountsV2":{"type":"object","properties":{"api_calls":{"type":"integer","description":"CTD API calls, personal and workspace keys together.","example":830},"mcp_calls":{"type":"integer","description":"CTD MCP tool calls.","example":2330},"total_calls":{"type":"integer","example":3160},"credits_used":{"type":"integer","example":2110}}},"WorkspaceUserStatus":{"type":"string","enum":["active","not_activated","deactivated","legacy"],"description":"active = has a seat; not_activated = signed up on a workspace domain, never given a seat; deactivated = seat removed, data kept; legacy = still in CTD, removed from the company directory.\n"},"EmailSyncStatus":{"type":"string","enum":["synced","syncing","error","off"],"nullable":true,"description":"error = the mailbox grant stopped working; off = CTD does not read the mailbox. Null when the counters could not be read.\n"},"WorkspaceUserV2":{"type":"object","properties":{"email":{"type":"string","format":"email","description":"The primary address","whatever":"address was asked for."},"name":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"linkedin_url":{"type":"string","nullable":true,"example":"https://www.linkedin.com/in/janedoe"},"status":{"$ref":"#/components/schemas/WorkspaceUserStatus"},"is_admin":{"type":"boolean"},"tier":{"type":"integer","minimum":1,"maximum":4,"nullable":true,"description":"Null is unassigned. Always null for not_activated and legacy users."},"visible_in_paths":{"type":"boolean","nullable":true},"mailbox_sync":{"type":"boolean","nullable":true,"description":"False when CTD does not read the mailbox."},"network_score":{"type":"number","nullable":true},"contacts_count":{"type":"integer"},"emails_synced_count":{"type":"integer","nullable":true,"description":"Emails CTD has processed from the user's workspace mailboxes."},"email_sync_status":{"$ref":"#/components/schemas/EmailSyncStatus"},"linkedin_synced":{"type":"boolean","description":"A finished LinkedIn import whose contacts are usable."},"linkedin_last_synced_at":{"type":"string","format":"date-time","nullable":true,"description":"When the latest finished import ran. Can be set while linkedin_synced is still false, for an import still being processed."},"linkedin_connections_count":{"type":"integer","nullable":true,"description":"Contacts of that import."},"personal_email_connected":{"type":"boolean","description":"The personal address itself is never returned."},"last_active_at":{"type":"string","format":"date-time","nullable":true,"description":"Last request from web","extension,":"mobile or desktop."},"created_at":{"type":"string","format":"date-time","nullable":true},"deactivated_at":{"type":"string","format":"date-time","nullable":true}}},"WorkspaceUserDetailV2":{"allOf":[{"$ref":"#/components/schemas/WorkspaceUserV2"},{"type":"object","properties":{"mailboxes":{"type":"array","description":"The user's workspace mailboxes.","items":{"type":"object","properties":{"email":{"type":"string","format":"email"},"provider":{"type":"string","enum":["google","microsoft"],"nullable":true},"mailbox_sync":{"type":"boolean"},"email_sync_status":{"$ref":"#/components/schemas/EmailSyncStatus"},"emails_synced_count":{"type":"integer","nullable":true}}}},"last_active":{"type":"object","properties":{"web":{"type":"string","format":"date-time","nullable":true},"extension":{"type":"string","format":"date-time","nullable":true},"mobile":{"type":"string","format":"date-time","nullable":true},"desktop":{"type":"string","format":"date-time","nullable":true}}}}}]},"WorkspaceUserAddResultV2":{"type":"object","properties":{"email":{"type":"string","description":"The address as given."},"primary_email":{"type":"string","nullable":true,"description":"The mailbox the seat went to. Differs from email when an alias was given."},"status":{"type":"string","enum":["added","activated","already_active","failed"]},"code":{"type":"string","description":"Set on failed rows."},"message":{"type":"string","nullable":true}}},"PublicPathNode":{"type":"object","properties":{"id":{"type":"string","enum":["user","conn1","conn2","target"],"description":"Node position in the path (user = user authenticated in the API, conn1 = first connector, conn2 = second connector, target = target person)."},"name":{"type":"string","nullable":true,"description":"Full name of the person."},"linkedin_id":{"type":"string","nullable":true,"description":"LinkedIn profile identifier."},"title":{"type":"string","nullable":true,"description":"Default current job title."},"company_name":{"type":"string","nullable":true,"description":"Default company the person works at."},"connector_type":{"type":"string","nullable":true,"description":"Type of connector (e.g., coworker, investor, advisor, personal connector)."},"tier":{"type":"integer","nullable":true,"description":"Connector tier level."},"location":{"type":"string","nullable":true,"description":"Geographic location of the person."},"is_target_person":{"type":"boolean","nullable":true,"description":"Whether the person is marked as a target persona."},"company_ctd_url":{"type":"string","nullable":true,"description":"CTD URL for the person's company."},"person_ctd_url":{"type":"string","nullable":true,"description":"CTD URL for the person's profile."}}},"PublicPathEdge":{"type":"object","properties":{"from":{"type":"string","enum":["user","conn1","conn2"]},"to":{"type":"string","enum":["conn1","conn2","target"]},"relationship_type":{"type":"array","items":{"type":"string","enum":["overlapped","email connected","linkedin connected","invited","enterprise external member","coworker"]}},"overlapping_score":{"type":"integer","example":92115,"description":"Raw overlap score representing shared work history and mutual network signals. Primarily intended for sorting."},"overlapping_score_scaled":{"type":"integer","minimum":0,"maximum":3,"example":2,"description":"Scaled overlap score from 0 to 3 where 0 = no overlap, 1 = weak overlap, 2 = medium overlap, and 3 = strong overlap."},"overlapping_score_label":{"type":"string","nullable":true,"enum":[null,"weak","medium","strong"],"example":"medium","description":"Human-readable label for overlapping_score_scaled."},"overlapping_message":{"type":"string","nullable":true,"description":"Detailed explanation of shared work history and mutual connection signals contributing to the overlap score."},"relationship_strength":{"type":"integer","minimum":0,"maximum":3,"example":2,"description":"Relationship strength score from 0 to 3 where 0 = no detected email or LinkedIn connections, 1 = weak, 2 = medium, and 3 = strong."},"relationship_strength_label":{"type":"string","nullable":true,"enum":["weak","medium","strong"],"example":"medium"},"final_relationship_strength":{"type":"integer","minimum":1,"maximum":3,"example":2,"description":"Final relationship strength score taking into account both relationship strength and overlap score."},"final_relationship_strength_label":{"type":"string","nullable":true,"enum":["weak","medium","strong","weak overlap","medium overlap","strong overlap"],"example":"medium","description":"Human-readable label for final relationship strength that takes into account both relationship strength and the overlap score. A relationship strength of 0 indicates that no email or LinkedIn connections were detected, most likely because the connector is not a CTD user and their accounts were not ingested. However, based on publicly available overlap signals, we may still predict a relationship, labeled as \"weak overlap\", \"medium overlap\", or \"strong overlap\". In the CTD app, the green overlap icon represents the label \"strong overlap\", while the green three dots represent the label \"strong\".\n"}}},"PublicPathPayload":{"type":"object","properties":{"path_id":{"type":"string","format":"uuid","description":"Unique identifier of the path, to be passed back to the path stage write endpoints. Treat it as an opaque uuid.\n"},"path_key":{"type":"string","format":"uuid","description":"Stable identifier of the path, derived from its target person, company, owning user and connector identities. Carries the same value as path_id.\n"},"stage":{"type":"string","enum":["Not started","To do","Approaching Connector","Approaching Target","Successful","Unsuccessful","Not relevant","Bad data"]},"path_status_manual_note":{"type":"string","nullable":true,"description":"Optional manual note attached to the path stage. Set it via the update-path-stage endpoint.","example":"Waiting on a warm intro from the connector."},"path_status_manual_note_updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Timestamp when the path stage manual note was last updated.","example":"2021-06-23T10:34:00.000Z"},"degree":{"type":"integer","example":2},"path_score":{"type":"number","example":9994,"description":"Ranking score CTD uses to order paths. A higher score ranks the path higher. Use it to compare paths within one response only; the scale is not fixed and can change.\n"},"path_relationship_strength":{"type":"integer","nullable":true,"minimum":1,"maximum":3,"description":"Path relationship strength score from 1 to 3 where 1 = weak, 2 = medium, and 3 = strong."},"path_relationship_strength_label":{"type":"string","nullable":true,"enum":["weak","medium","strong"],"description":"Human-readable label for path_relationship_strength."},"path_relationship_type":{"type":"string","nullable":true,"enum":["deterministic","probabilistic"],"description":"Path relationship type. Deterministic means that all nodes in the path are connected to each other via email or LinkedIn connections,\nwhile probabilistic means that the connection between the connector and the target person is predicted based on publicly available career and education overlap signals."},"nodes":{"type":"array","items":{"$ref":"#/components/schemas/PublicPathNode"}},"edges":{"type":"array","items":{"$ref":"#/components/schemas/PublicPathEdge"}}}},"PublicPath":{"type":"object","properties":{"path":{"$ref":"#/components/schemas/PublicPathPayload"}}},"PublicPathsResponse":{"type":"object","properties":{"paths":{"type":"array","items":{"$ref":"#/components/schemas/PublicPath"}}},"example":{"paths":[{"path":{"path_id":"1f0c9c4e-6f3a-4a2b-9d5e-7c8b0a1d2e3f","path_key":"1f0c9c4e-6f3a-4a2b-9d5e-7c8b0a1d2e3f","stage":"Not started","degree":1,"path_score":9994,"path_relationship_strength":2,"path_relationship_strength_label":"medium","path_relationship_type":"deterministic","nodes":[{"id":"user","name":"John Smith","linkedin_id":"john-smith","title":"Director of Engineering","company_name":"Example Corp","person_ctd_url":"https://ctd.ai/person/john-smith"},{"id":"conn1","name":"John Doe","linkedin_id":"john-doe","title":"Manager","company_name":"Example Corp","connector_type":"first","tier":1,"person_ctd_url":"https://ctd.ai/person/john-doe"},{"id":"target","name":"Jane Smith","linkedin_id":"jane-smith","title":"CEO","company_name":"Target Inc","location":"San Francisco","is_target_person":true,"company_ctd_url":"https://ctd.ai/company/target-inc","person_ctd_url":"https://ctd.ai/person/jane-smith"}],"edges":[{"from":"user","to":"conn1","relationship_type":["email connected"],"overlapping_score":0,"overlapping_score_scaled":0,"overlapping_score_label":null,"overlapping_message":"","relationship_strength":2,"relationship_strength_label":"medium","final_relationship_strength":2,"final_relationship_strength_label":"medium"},{"from":"conn1","to":"target","relationship_type":["linkedin connected","overlapped"],"overlapping_score":92115,"overlapping_score_scaled":2,"overlapping_score_label":"medium","overlapping_message":"You worked together at Example Corp for 3 years","relationship_strength":3,"relationship_strength_label":"strong","final_relationship_strength":3,"final_relationship_strength_label":"strong"}]}}]}},"PublicGlobalPathsResponse":{"type":"object","properties":{"paths":{"type":"array","items":{"$ref":"#/components/schemas/PublicPath"}}},"example":{"paths":[{"path":{"path_id":"1f0c9c4e-6f3a-4a2b-9d5e-7c8b0a1d2e3f","path_key":"1f0c9c4e-6f3a-4a2b-9d5e-7c8b0a1d2e3f","stage":"Not started","degree":1,"path_score":9994,"path_relationship_strength":2,"path_relationship_strength_label":"medium","path_relationship_type":"deterministic","nodes":[{"id":"conn1","name":"John Doe","linkedin_id":"john-doe","title":"Manager","company_name":"Example Corp","connector_type":"first","tier":1,"person_ctd_url":"https://ctd.ai/person/john-doe"},{"id":"target","name":"Jane Smith","linkedin_id":"jane-smith","title":"CEO","company_name":"Target Inc","location":"San Francisco","is_target_person":true,"company_ctd_url":"https://ctd.ai/company/target-inc","person_ctd_url":"https://ctd.ai/person/jane-smith"}],"edges":[{"from":"conn1","to":"target","relationship_type":["linkedin connected","overlapped"],"overlapping_score":92115,"overlapping_score_scaled":2,"overlapping_score_label":"medium","overlapping_message":"You worked together at Example Corp for 3 years","relationship_strength":3,"relationship_strength_label":"strong","final_relationship_strength":3,"final_relationship_strength_label":"strong"}]}}]}},"PublicPathCurrentRole":{"type":"object","properties":{"title":{"type":"string","nullable":true,"description":"Role title."},"company_name":{"type":"string","nullable":true,"description":"Company name for the role."},"company_ctd_url":{"type":"string","nullable":true,"description":"CTD URL for the company."},"company_linkedin":{"type":"string","nullable":true,"description":"LinkedIn URL for the company."},"path_stage":{"type":"string","enum":["Not started","To do","Approaching Connector","Approaching Target","Successful","Unsuccessful","Not relevant","Bad data"],"description":"Path stage for this role."},"is_target_account":{"type":"boolean","description":"Whether the company of this role is marked as a target account for your organization."}}},"PublicPathNodeV2":{"allOf":[{"$ref":"#/components/schemas/PublicPathNode"},{"type":"object","properties":{"current_roles":{"type":"array","items":{"$ref":"#/components/schemas/PublicPathCurrentRole"},"description":"List of current roles. Only populated on the target node."}}}]},"PublicPathPayloadV2":{"type":"object","properties":{"path_id":{"type":"string","format":"uuid","description":"Unique identifier of the path, to be passed back to the path stage write endpoints. Treat it as an opaque uuid.\n"},"path_key":{"type":"string","format":"uuid","description":"Stable identifier of the path, derived from its target person, company, owning user and connector identities. Carries the same value as path_id.\n"},"stage":{"type":"string","enum":["Not started","To do","Approaching Connector","Approaching Target","Successful","Unsuccessful","Not relevant","Bad data"]},"path_status_manual_note":{"type":"string","nullable":true,"description":"Optional manual note attached to the path stage. Set it via the update-path-stage endpoint.","example":"Waiting on a warm intro from the connector."},"path_status_manual_note_updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Timestamp when the path stage manual note was last updated.","example":"2021-06-23T10:34:00.000Z"},"degree":{"type":"integer","example":2},"path_score":{"type":"number","example":9994,"description":"Ranking score CTD uses to order paths. A higher score ranks the path higher. Use it to compare paths within one response only; the scale is not fixed and can change.\n"},"path_relationship_strength":{"type":"integer","nullable":true,"minimum":1,"maximum":3,"description":"Path relationship strength score from 1 to 3 where 1 = weak, 2 = medium, and 3 = strong."},"path_relationship_strength_label":{"type":"string","nullable":true,"enum":["weak","medium","strong"],"description":"Human-readable label for path_relationship_strength."},"path_relationship_type":{"type":"string","nullable":true,"enum":["deterministic","probabilistic"],"description":"Path relationship type. Deterministic means that all nodes in the path are connected to each other via email or LinkedIn connections,\nwhile probabilistic means that the connection between the connector and the target person is predicted based on publicly available career and education overlap signals."},"nodes":{"type":"array","items":{"$ref":"#/components/schemas/PublicPathNodeV2"}},"edges":{"type":"array","items":{"$ref":"#/components/schemas/PublicPathEdge"}}}},"PublicPathV2":{"type":"object","properties":{"path":{"$ref":"#/components/schemas/PublicPathPayloadV2"}}},"PublicPathsResponseV2":{"type":"object","properties":{"paths":{"type":"array","items":{"$ref":"#/components/schemas/PublicPathV2"}}},"example":{"paths":[{"path":{"path_id":"1f0c9c4e-6f3a-4a2b-9d5e-7c8b0a1d2e3f","path_key":"1f0c9c4e-6f3a-4a2b-9d5e-7c8b0a1d2e3f","stage":"Not started","degree":1,"path_score":9994,"path_relationship_strength":2,"path_relationship_strength_label":"medium","path_relationship_type":"deterministic","nodes":[{"id":"user","name":"John Smith","linkedin_id":"john-smith","title":"Director of Engineering","company_name":"Example Corp","person_ctd_url":"https://ctd.ai/person/john-smith"},{"id":"conn1","name":"John Doe","linkedin_id":"john-doe","title":"Manager","company_name":"Example Corp","connector_type":"first","tier":1,"person_ctd_url":"https://ctd.ai/person/john-doe"},{"id":"target","name":"Jane Smith","linkedin_id":"jane-smith","title":"CEO","company_name":"Target Inc","location":"San Francisco","is_target_person":true,"company_ctd_url":"https://ctd.ai/company/target-inc","person_ctd_url":"https://ctd.ai/person/jane-smith","current_roles":[{"title":"CEO","company_name":"Target Inc","company_ctd_url":"https://ctd.ai/company/target-inc","company_linkedin":"https://www.linkedin.com/company/target-inc","path_stage":"Not started","is_target_account":true}]}],"edges":[{"from":"user","to":"conn1","relationship_type":["email connected"],"overlapping_score":0,"overlapping_score_scaled":0,"overlapping_score_label":null,"overlapping_message":"","relationship_strength":2,"relationship_strength_label":"medium","final_relationship_strength":2,"final_relationship_strength_label":"medium"},{"from":"conn1","to":"target","relationship_type":["linkedin connected","overlapped"],"overlapping_score":92115,"overlapping_score_scaled":2,"overlapping_score_label":"medium","overlapping_message":"You worked together at Example Corp for 3 years","relationship_strength":3,"relationship_strength_label":"strong","final_relationship_strength":3,"final_relationship_strength_label":"strong"}]}}]}},"PublicGlobalPathsResponseV2":{"type":"object","properties":{"paths":{"type":"array","items":{"$ref":"#/components/schemas/PublicPathV2"}}},"example":{"paths":[{"path":{"path_id":"1f0c9c4e-6f3a-4a2b-9d5e-7c8b0a1d2e3f","path_key":"1f0c9c4e-6f3a-4a2b-9d5e-7c8b0a1d2e3f","stage":"Not started","degree":1,"path_score":9994,"path_relationship_strength":2,"path_relationship_strength_label":"medium","path_relationship_type":"deterministic","nodes":[{"id":"conn1","name":"John Doe","linkedin_id":"john-doe","title":"Manager","company_name":"Example Corp","connector_type":"first","tier":1,"person_ctd_url":"https://ctd.ai/person/john-doe"},{"id":"target","name":"Jane Smith","linkedin_id":"jane-smith","title":"CEO","company_name":"Target Inc","location":"San Francisco","is_target_person":true,"company_ctd_url":"https://ctd.ai/company/target-inc","person_ctd_url":"https://ctd.ai/person/jane-smith","current_roles":[{"title":"CEO","company_name":"Target Inc","company_ctd_url":"https://ctd.ai/company/target-inc","company_linkedin":"https://www.linkedin.com/company/target-inc","path_stage":"Not started","is_target_account":true}]}],"edges":[{"from":"conn1","to":"target","relationship_type":["linkedin connected","overlapped"],"overlapping_score":92115,"overlapping_score_scaled":2,"overlapping_score_label":"medium","overlapping_message":"You worked together at Example Corp for 3 years","relationship_strength":3,"relationship_strength_label":"strong","final_relationship_strength":3,"final_relationship_strength_label":"strong"}]}}]}},"PublicPathEdgeV2":{"type":"object","properties":{"from":{"type":"string","enum":["user","conn1","conn2"]},"to":{"type":"string","enum":["conn1","conn2","target"]},"relationship_type":{"type":"array","items":{"type":"string","enum":["overlapped","email connected","linkedin connected","invited","enterprise external member","coworker"]}},"overlapping_score":{"type":"integer","example":92115,"description":"Raw overlap score representing shared work history and mutual network signals. Primarily intended for sorting."},"overlapping_score_scaled":{"type":"integer","minimum":0,"maximum":3,"example":2,"description":"Scaled overlap score from 0 to 3 where 0 = no overlap, 1 = weak overlap, 2 = medium overlap, and 3 = strong overlap."},"overlapping_score_label":{"type":"string","nullable":true,"enum":[null,"weak","medium","strong"],"example":"medium","description":"Human-readable label for overlapping_score_scaled."},"overlapping_message":{"type":"string","nullable":true,"description":"Detailed explanation of shared work history and mutual connection signals contributing to the overlap score."},"relationship_strength":{"type":"integer","minimum":0,"maximum":3,"example":2,"description":"Relationship strength score from 0 to 3 where 0 = no detected email or LinkedIn connections, 1 = weak, 2 = medium, and 3 = strong."},"relationship_strength_label":{"type":"string","nullable":true,"enum":["weak","medium","strong"],"example":"medium"},"relationship_via_company_domain":{"type":"object","nullable":true,"description":"More detailed relationship context between you or a co-worker (the edge's \"from\" person) and\none of their contacts (the \"to\" person): how much they email and meet. It is counted only from\nthe \"from\" person's company email address and company calendar account. Data from any other\naccount they connected (for example a personal Gmail) is never included and stays private to them.\n\nAvailable only when your enterprise admin has enabled Enterprise Relationship Insights for the\nenterprise, and only on edges whose \"from\" is you (`from: user`) or a co-worker (the \"from\" node's\n`connector_type` is `co-worker`).\n- `null`: not available (the admin has not enabled it, or \"from\" is neither you nor a co-worker).\n- `{\"email\": null, \"calendar_summary\": null}`: available, but no email and no meetings between the\n  two through company accounts. The same value is returned when privacy settings hide the details.\n- Otherwise one or both parts are filled.\n\nThe key is left out of an edge only when the data could not be read at that moment; the rest of\nthe response is unaffected. With an enterprise API key, \"you\" is the member whose email is sent\nin `ctd-client-id`.\n","allOf":[{"$ref":"#/components/schemas/RelationshipViaCompanyDomain"}]},"final_relationship_strength":{"type":"integer","minimum":1,"maximum":3,"example":2,"description":"Final relationship strength score taking into account both relationship strength and overlap score."},"final_relationship_strength_label":{"type":"string","nullable":true,"enum":["weak","medium","strong","weak overlap","medium overlap","strong overlap"],"example":"medium","description":"Human-readable label for final relationship strength that takes into account both relationship strength and the overlap score. A relationship strength of 0 indicates that no email or LinkedIn connections were detected, most likely because the connector is not a CTD user and their accounts were not ingested. However, based on publicly available overlap signals, we may still predict a relationship, labeled as \"weak overlap\", \"medium overlap\", or \"strong overlap\". In the CTD app, the green overlap icon represents the label \"strong overlap\", while the green three dots represent the label \"strong\".\n"}}},"RelationshipViaCompanyDomain":{"type":"object","nullable":true,"description":"More detailed relationship context between you or a co-worker (the \"from\" person of a path edge) and one of their contacts (the \"to\" person), counted only from the \"from\" person's company email and calendar accounts. Personal accounts (for example Gmail) are never included. Both keys are always present.\n","required":["email","calendar_summary"],"properties":{"email":{"type":"object","nullable":true,"description":"Emails between the two, from the \"from\" person's company email accounts only. null when nothing was sent or received.","allOf":[{"$ref":"#/components/schemas/RelationshipViaCompanyDomainEmail"}]},"calendar_summary":{"type":"object","nullable":true,"description":"Meetings between the two, from the \"from\" person's company calendar accounts only. null when there is no past and no upcoming meeting.","allOf":[{"$ref":"#/components/schemas/RelationshipViaCompanyDomainCalendarSummary"}]}}},"RelationshipViaCompanyDomainEmail":{"type":"object","nullable":true,"description":"Emails between the \"from\" and the \"to\" person of a path edge, from the \"from\" person's company email accounts only. Every key is always present.","required":["count","sent","received","messages_by_group_size","first_date","last_date"],"properties":{"count":{"type":"integer","minimum":0,"example":1720,"description":"Email messages both people were on, the sum of messages_by_group_size. It can be higher than sent + received, because it also counts messages they both received from others.\n"},"sent":{"type":"integer","minimum":0,"example":774,"description":"Messages the \"from\" person sent to the \"to\" person."},"received":{"type":"integer","minimum":0,"example":825,"description":"Messages the \"from\" person received from the \"to\" person."},"messages_by_group_size":{"type":"object","description":"count split by the number of participants on a message, sender included: one_on_one = up to 2, small_group_3_to_5 = 3 to 5, large_group = 6 or more.\n","allOf":[{"$ref":"#/components/schemas/RelationshipViaCompanyDomainGroupSize"}]},"first_date":{"type":"string","format":"date","nullable":true,"example":"2021-10-04","description":"UTC day (YYYY-MM-DD) of the first email between the two people."},"last_date":{"type":"string","format":"date","nullable":true,"example":"2026-10-12","description":"UTC day (YYYY-MM-DD) of the last email between the two people."}}},"RelationshipViaCompanyDomainCalendarSummary":{"type":"object","nullable":true,"description":"Meetings between the \"from\" and the \"to\" person of a path edge, from the \"from\" person's company calendar accounts only. Every key is always present.","required":["meeting_count","meeting_count_last_12_months","meeting_count_by_group_size","first_meeting_date","last_meeting_date","next_meeting_date"],"properties":{"meeting_count":{"type":"integer","minimum":0,"example":24,"description":"Concluded meetings of the two people that neither of them declined. All-day meetings and unanswered invitations are included.\n"},"meeting_count_last_12_months":{"type":"integer","minimum":0,"example":9,"description":"The meetings of meeting_count held in the last 12 months."},"meeting_count_by_group_size":{"type":"object","description":"meeting_count split by meeting size; the three values sum to meeting_count. one_on_one = exactly 2 participants, both accepted, not all-day. small_group_3_to_5 = other meetings of up to 5 participants that both accepted. large_group = all other meetings (more participants, not accepted by both, or all-day).\n","allOf":[{"$ref":"#/components/schemas/RelationshipViaCompanyDomainGroupSize"}]},"first_meeting_date":{"type":"string","format":"date","nullable":true,"example":"2021-02-03","description":"UTC day (YYYY-MM-DD) of the first concluded meeting. null when there is none."},"last_meeting_date":{"type":"string","format":"date","nullable":true,"example":"2026-09-18","description":"UTC day (YYYY-MM-DD) of the last concluded meeting. null when there is none."},"next_meeting_date":{"type":"string","format":"date","nullable":true,"example":"2026-10-21","description":"UTC day (YYYY-MM-DD) of the next scheduled meeting. null when none is scheduled."}}},"RelationshipViaCompanyDomainGroupSize":{"type":"object","description":"Counts split by group size. The rule for each group is described on the property that uses this object. Every key is always present.\n","required":["one_on_one","small_group_3_to_5","large_group"],"properties":{"one_on_one":{"type":"integer","minimum":0,"description":"One-on-one."},"small_group_3_to_5":{"type":"integer","minimum":0,"description":"Small group, 3 to 5 participants."},"large_group":{"type":"integer","minimum":0,"description":"Large group."}}},"PublicPathPayloadV2WithEdgeV2":{"type":"object","properties":{"path_id":{"type":"string","format":"uuid","description":"Unique identifier of the path, to be passed back to the path stage write endpoints. Treat it as an opaque uuid.\n"},"path_key":{"type":"string","format":"uuid","description":"Stable identifier of the path, derived from its target person, company, owning user and connector identities. Carries the same value as path_id.\n"},"stage":{"type":"string","enum":["Not started","To do","Approaching Connector","Approaching Target","Successful","Unsuccessful","Not relevant","Bad data"]},"path_status_manual_note":{"type":"string","nullable":true,"description":"Optional manual note attached to the path stage. Set it via the update-path-stage endpoint.","example":"Waiting on a warm intro from the connector."},"path_status_manual_note_updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Timestamp when the path stage manual note was last updated.","example":"2021-06-23T10:34:00.000Z"},"degree":{"type":"integer","example":2},"path_score":{"type":"number","example":9994,"description":"Ranking score CTD uses to order paths. A higher score ranks the path higher. Use it to compare paths within one response only; the scale is not fixed and can change.\n"},"path_relationship_strength":{"type":"integer","nullable":true,"minimum":1,"maximum":3,"description":"Path relationship strength score from 1 to 3 where 1 = weak, 2 = medium, and 3 = strong."},"path_relationship_strength_label":{"type":"string","nullable":true,"enum":["weak","medium","strong"],"description":"Human-readable label for path_relationship_strength."},"path_relationship_type":{"type":"string","nullable":true,"enum":["deterministic","probabilistic"],"description":"Path relationship type. Deterministic means that all nodes in the path are connected to each other via email or LinkedIn connections,\nwhile probabilistic means that the connection between the connector and the target person is predicted based on publicly available career and education overlap signals."},"nodes":{"type":"array","items":{"$ref":"#/components/schemas/PublicPathNodeV2"}},"edges":{"type":"array","items":{"$ref":"#/components/schemas/PublicPathEdgeV2"}}}},"PublicPathV2WithEdgeV2":{"type":"object","properties":{"path":{"$ref":"#/components/schemas/PublicPathPayloadV2WithEdgeV2"}}},"PublicPathsResponseV2WithEdgeV2":{"type":"object","properties":{"paths":{"type":"array","items":{"$ref":"#/components/schemas/PublicPathV2WithEdgeV2"}}},"example":{"paths":[{"path":{"path_id":"1f0c9c4e-6f3a-4a2b-9d5e-7c8b0a1d2e3f","path_key":"1f0c9c4e-6f3a-4a2b-9d5e-7c8b0a1d2e3f","stage":"Not started","degree":1,"path_score":9994,"path_relationship_strength":2,"path_relationship_strength_label":"medium","path_relationship_type":"deterministic","nodes":[{"id":"user","name":"John Smith","linkedin_id":"john-smith","title":"Director of Engineering","company_name":"Example Corp","person_ctd_url":"https://ctd.ai/person/john-smith"},{"id":"conn1","name":"John Doe","linkedin_id":"john-doe","title":"Manager","company_name":"Example Corp","connector_type":"co-worker","tier":1,"person_ctd_url":"https://ctd.ai/person/john-doe"},{"id":"target","name":"Jane Smith","linkedin_id":"jane-smith","title":"CEO","company_name":"Target Inc","location":"San Francisco","is_target_person":true,"company_ctd_url":"https://ctd.ai/company/target-inc","person_ctd_url":"https://ctd.ai/person/jane-smith","current_roles":[{"title":"CEO","company_name":"Target Inc","company_ctd_url":"https://ctd.ai/company/target-inc","company_linkedin":"https://www.linkedin.com/company/target-inc","path_stage":"Not started","is_target_account":true}]}],"edges":[{"from":"user","to":"conn1","relationship_type":["email connected"],"overlapping_score":0,"overlapping_score_scaled":0,"overlapping_score_label":null,"overlapping_message":"","relationship_strength":2,"relationship_strength_label":"medium","relationship_via_company_domain":{"email":null,"calendar_summary":null},"final_relationship_strength":2,"final_relationship_strength_label":"medium"},{"from":"conn1","to":"target","relationship_type":["linkedin connected","overlapped"],"overlapping_score":92115,"overlapping_score_scaled":2,"overlapping_score_label":"medium","overlapping_message":"You worked together at Example Corp for 3 years","relationship_strength":3,"relationship_strength_label":"strong","relationship_via_company_domain":{"email":{"count":1720,"sent":774,"received":825,"messages_by_group_size":{"one_on_one":195,"small_group_3_to_5":431,"large_group":1094},"first_date":"2021-10-04","last_date":"2026-10-12"},"calendar_summary":{"meeting_count":24,"meeting_count_last_12_months":9,"meeting_count_by_group_size":{"one_on_one":5,"small_group_3_to_5":6,"large_group":13},"first_meeting_date":"2021-02-03","last_meeting_date":"2026-09-18","next_meeting_date":"2026-10-21"}},"final_relationship_strength":3,"final_relationship_strength_label":"strong"}]}}]}},"PublicGlobalPathsResponseV2WithEdgeV2":{"type":"object","properties":{"paths":{"type":"array","items":{"$ref":"#/components/schemas/PublicPathV2WithEdgeV2"}}},"example":{"paths":[{"path":{"path_id":"1f0c9c4e-6f3a-4a2b-9d5e-7c8b0a1d2e3f","path_key":"1f0c9c4e-6f3a-4a2b-9d5e-7c8b0a1d2e3f","stage":"Not started","degree":1,"path_score":9994,"path_relationship_strength":2,"path_relationship_strength_label":"medium","path_relationship_type":"deterministic","nodes":[{"id":"conn1","name":"John Doe","linkedin_id":"john-doe","title":"Manager","company_name":"Example Corp","connector_type":"co-worker","tier":1,"person_ctd_url":"https://ctd.ai/person/john-doe"},{"id":"target","name":"Jane Smith","linkedin_id":"jane-smith","title":"CEO","company_name":"Target Inc","location":"San Francisco","is_target_person":true,"company_ctd_url":"https://ctd.ai/company/target-inc","person_ctd_url":"https://ctd.ai/person/jane-smith","current_roles":[{"title":"CEO","company_name":"Target Inc","company_ctd_url":"https://ctd.ai/company/target-inc","company_linkedin":"https://www.linkedin.com/company/target-inc","path_stage":"Not started","is_target_account":true}]}],"edges":[{"from":"conn1","to":"target","relationship_type":["linkedin connected","overlapped"],"overlapping_score":92115,"overlapping_score_scaled":2,"overlapping_score_label":"medium","overlapping_message":"You worked together at Example Corp for 3 years","relationship_strength":3,"relationship_strength_label":"strong","relationship_via_company_domain":{"email":{"count":1720,"sent":774,"received":825,"messages_by_group_size":{"one_on_one":195,"small_group_3_to_5":431,"large_group":1094},"first_date":"2021-10-04","last_date":"2026-10-12"},"calendar_summary":{"meeting_count":24,"meeting_count_last_12_months":9,"meeting_count_by_group_size":{"one_on_one":5,"small_group_3_to_5":6,"large_group":13},"first_meeting_date":"2021-02-03","last_meeting_date":"2026-09-18","next_meeting_date":"2026-10-21"}},"final_relationship_strength":3,"final_relationship_strength_label":"strong"}]}}]}},"PublicPerson":{"type":"object","properties":{"name":{"type":"string","nullable":true,"description":"Full name of the person."},"linkedin_id":{"type":"string","nullable":true,"description":"LinkedIn profile identifier of the person."},"title":{"type":"string","nullable":true,"description":"Default current job title of the person."},"company_name":{"type":"string","nullable":true,"description":"Default company the person works at."},"location":{"type":"string","nullable":true,"description":"Geographic location of the person."},"is_target_person":{"type":"boolean","nullable":true,"description":"Whether the person is marked as a target persona."},"company_ctd_url":{"type":"string","nullable":true,"description":"CTD URL for the person's company."},"person_ctd_url":{"type":"string","nullable":true,"description":"CTD URL for the person's profile."},"ctd_score":{"type":"string","nullable":true,"description":"Relationship strength score between your organization and the person. It's good to use for sorting (the higher the score, the stronger the relationship)."},"ctd_score_scaled":{"type":"integer","nullable":true,"minimum":0,"maximum":3,"description":"Scaled CTD score from 0 to 3."},"ctd_score_label":{"type":"string","nullable":true,"enum":["weak","medium","strong"],"description":"Human-readable label for ctd_score_scaled."},"company_linkedin_url":{"type":"string","nullable":true,"description":"LinkedIn company page URL."}}},"PublicPeopleResponse":{"type":"object","properties":{"people":{"type":"array","items":{"$ref":"#/components/schemas/PublicPerson"}}},"example":{"people":[{"name":"Jane Smith","linkedin_id":"jane-smith","title":"CEO","company_name":"Target Inc","location":"San Francisco","is_target_person":false,"ctd_score":"10003.45960000","ctd_score_scaled":3,"ctd_score_label":"strong","company_linkedin_url":"https://www.linkedin.com/company/target-inc","company_ctd_url":"https://ctd.ai/company/target-inc","person_ctd_url":"https://ctd.ai/person/jane-smith"}]}},"PublicCompanyResponse":{"type":"object","properties":{"name":{"type":"string","nullable":true,"description":"Company name."},"domains":{"type":"array","items":{"type":"string"},"nullable":true,"description":"List of company domains."},"ctd_url":{"type":"string","nullable":true,"description":"CTD URL for the company."},"linkedin_url":{"type":"string","nullable":true,"description":"LinkedIn company page URL."},"num_employees":{"type":"integer","nullable":true,"description":"Number of employees at the company."},"num_employees_range":{"type":"string","nullable":true,"description":"Employee count range (e.g., \"101-200\")."},"industry":{"type":"string","nullable":true,"description":"Company industry classification."},"ctd_score":{"type":"number","nullable":true,"description":"Raw CTD score for the company. It's good to use for sorting by relationship strength between your organization and the company (the higher the score, the stronger the relationship)."},"ctd_score_scaled":{"type":"integer","nullable":true,"minimum":0,"maximum":3,"description":"Scaled CTD score from 0 to 3."},"ctd_score_label":{"type":"string","nullable":true,"enum":["very weak","weak","medium","strong"],"description":"Human-readable label for ctd_score_scaled."},"stage":{"type":"string","nullable":true,"description":"The company stage information."},"company_status_manual_note":{"type":"string","nullable":true,"description":"Optional manual note attached to the company stage. Set it via the update-company-stage endpoint.","example":"Champion changed roles; revisit next quarter."},"company_status_manual_note_updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Timestamp when the company stage manual note was last updated.","example":"2021-06-23T10:34:00.000Z"}},"example":{"name":"Example Corp","domains":["example.com","example.net"],"ctd_url":"https://app.ctd.ai/companies/example-corp","linkedin_url":"https://www.linkedin.com/company/example-corp","num_employees":101,"num_employees_range":"101-200","industry":"Technology, Information & Internet","ctd_score":7500.7725404,"ctd_score_scaled":2,"ctd_score_label":"medium","stage":"Approaching","company_status_manual_note":"Champion changed roles; revisit next quarter.","company_status_manual_note_updated_at":"2021-06-23T10:34:00.000Z"}},"PublicBulkUpdateCompanyStageResult":{"type":"object","description":"Outcome of a bulk company stage update. `succeeded`/`deferred` and `failed` summarize the batch; `results` reports the status of each item in request order.\n","properties":{"succeeded":{"type":"integer","description":"Number of items applied synchronously. Present when the batch was processed synchronously (HTTP 200).","example":2},"deferred":{"type":"integer","description":"Number of items queued for asynchronous processing. Present when the batch was queued (HTTP 202).","example":1},"failed":{"type":"integer","description":"Number of items that could not be applied.","example":0},"results":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer","description":"Zero-based index of the item in the request `updates` array.","example":0},"status":{"type":"string","enum":["ok","deferred","error"],"example":"ok"},"company":{"type":"object","properties":{"company_domain":{"type":"string","nullable":true},"company_linkedin_url":{"type":"string","nullable":true},"stage":{"type":"string","nullable":true,"enum":["ToDo","NotRelevant","Unsuccessful","NoGoodPaths","Approaching","Successful","Attempted","BadData"]}}},"error":{"type":"string","description":"Present only when status is `error`.","example":"Company not found for the provided locator."}}}}}},"PublicSearchPathsResponse":{"type":"object","properties":{"explanation":{"type":"string","description":"Natural language explanation of the search results"},"paths":{"type":"array","items":{"$ref":"#/components/schemas/PublicPath"}}}},"PublicJobChangesResponse":{"type":"object","properties":{"job_changes":{"type":"array","items":{"$ref":"#/components/schemas/PublicJobChange"}}},"example":{"job_changes":[{"type":"switched_company","job_change_date":"2025-12-15T00:00:00Z","job_change_type":"switched_company","job_change_details":{"who":{"name":"Sarah Johnson","linkedin_id":"sarah-johnson-42","title":"VP of Sales","company_name":"Acme Corp","company_ctd_url":"https://app.ctd.ai/companies/acme-corp","person_ctd_url":"https://app.ctd.ai/people/sarah-johnson","is_champion":false,"is_target_person":true},"new_roles":[{"title":"VP of Sales","date_from":"2025-12-01T00:00:00Z","company_ctd_url":"https://app.ctd.ai/companies/acme-corp","company_name":"Acme Corp"}],"old_roles":[{"title":"Director of Sales","date_from":"2022-03-01T00:00:00Z","date_to":"2025-11-30T00:00:00Z","company_ctd_url":"https://app.ctd.ai/companies/globex-industries","company_name":"Globex Industries"}]}},{"type":"promoted","job_change_date":"2025-11-01T00:00:00Z","job_change_type":"promoted","job_change_details":{"who":{"name":"Michael Chen","linkedin_id":"michael-chen-88","title":"Engineering Manager","company_name":"Initech Solutions","company_ctd_url":"https://app.ctd.ai/companies/initech-solutions","person_ctd_url":"https://app.ctd.ai/people/michael-chen","is_champion":true,"is_target_person":false},"new_roles":[{"title":"Engineering Manager","date_from":"2025-11-01T00:00:00Z","company_ctd_url":"https://app.ctd.ai/companies/initech-solutions","company_name":"Initech Solutions"}],"old_roles":[{"title":"Senior Engineer","date_from":"2023-01-15T00:00:00Z","date_to":"2025-10-31T00:00:00Z","company_ctd_url":"https://app.ctd.ai/companies/initech-solutions","company_name":"Initech Solutions"}]}}]}},"PublicJobChange":{"type":"object","properties":{"type":{"type":"string"},"job_change_date":{"type":"string","format":"date-time","nullable":true,"description":"Date when the job change was detected."},"job_change_type":{"$ref":"#/components/schemas/PublicJobChangeType"},"job_change_details":{"$ref":"#/components/schemas/PublicJobChangeDetails"}}},"PublicJobChangeType":{"type":"string","enum":["joined_company","left_company","switched_company","promoted"]},"PublicJobChangeDetails":{"type":"object","required":["who"],"properties":{"who":{"$ref":"#/components/schemas/PublicJobChangeWho"},"new_roles":{"type":"array","items":{"$ref":"#/components/schemas/PublicJobChangeRole"}},"old_roles":{"type":"array","items":{"$ref":"#/components/schemas/PublicJobChangeRole"}}}},"PublicJobChangeWho":{"type":"object","properties":{"name":{"type":"string","nullable":true,"description":"Name of the person."},"linkedin_id":{"type":"string","nullable":true,"description":"LinkedIn profile identifier."},"title":{"type":"string","nullable":true,"description":"Current job title."},"company_name":{"type":"string","nullable":true,"description":"Current company name."},"company_ctd_url":{"type":"string","description":"CTD URL for the company."},"person_ctd_url":{"type":"string","description":"CTD URL for the person."},"is_champion":{"type":"boolean","description":"Whether this person is a champion (key connector) in your network."},"is_target_person":{"type":"boolean","description":"Whether this person is marked as a target persona."}}},"PublicJobChangeRole":{"type":"object","properties":{"title":{"type":"string","nullable":true,"description":"Job title for this role."},"date_from":{"type":"string","format":"date-time","nullable":true,"description":"Start date of the role."},"date_to":{"type":"string","format":"date-time","nullable":true,"description":"End date of the role."},"company_ctd_url":{"type":"string","description":"CTD URL for the company."},"company_name":{"type":"string","nullable":true,"description":"Company name for this role."}}},"ReachableCompaniesResponse":{"type":"object","properties":{"companies":{"type":"array","items":{"$ref":"#/components/schemas/ReachableCompany"}}},"example":{"companies":[{"name":"Acme Corp","ctd_url":"https://app.ctd.ai/companies/acme-corp","domains":["acme.com"],"linkedin_url":"https://www.linkedin.com/company/acme-corp","num_employees":150,"num_employees_range":"101-200","industry":"Technology, Information & Internet","ctd_company_score":8500.25,"ctd_company_score_scaled":3,"ctd_company_score_label":"strong","stage":"Approaching","is_target_account":true,"account_owner_name":"Sarah Johnson"},{"name":"Globex Industries","ctd_url":"https://app.ctd.ai/companies/globex-industries","domains":["globex.com"],"linkedin_url":"https://www.linkedin.com/company/globex-industries","num_employees":500,"num_employees_range":"201-500","industry":"Manufacturing","ctd_company_score":4200.1,"ctd_company_score_scaled":2,"ctd_company_score_label":"medium","stage":"Not started","is_target_account":false,"account_owner_name":null}]}},"ReachableCompany":{"type":"object","properties":{"name":{"type":"string","nullable":true,"description":"Company name."},"ctd_url":{"type":"string","description":"CTD URL for the company."},"domains":{"type":"array","items":{"type":"string"},"description":"List of company domains."},"linkedin_url":{"type":"string","nullable":true,"description":"LinkedIn company page URL."},"num_employees":{"type":"integer","nullable":true,"description":"Number of employees at the company."},"num_employees_range":{"type":"string","nullable":true,"description":"Employee count range (e.g., \"101-200\")."},"industry":{"type":"string","nullable":true,"description":"Company industry classification."},"ctd_company_score":{"type":"number","nullable":true,"description":"Raw CTD company score. Higher values indicate stronger relationships between your organization and the company."},"ctd_company_score_scaled":{"type":"integer","nullable":true,"minimum":0,"maximum":3,"description":"Scaled CTD company score from 0 to 3."},"ctd_company_score_label":{"type":"string","nullable":true,"enum":["very weak","weak","medium","strong"],"description":"Human-readable label for ctd_company_score_scaled."},"stage":{"type":"string","nullable":true,"description":"The company stage information."},"company_status_manual_note":{"type":"string","nullable":true,"description":"Optional manual note attached to the company stage. Set it via the update-company-stage endpoint.","example":"Champion changed roles; revisit next quarter."},"company_status_manual_note_updated_at":{"type":"string","format":"date-time","nullable":true,"description":"Timestamp when the company stage manual note was last updated.","example":"2021-06-23T10:34:00.000Z"},"is_target_account":{"type":"boolean","nullable":true,"description":"Whether the company is marked as a target account."},"account_owner_name":{"type":"string","nullable":true,"description":"Name of the account owner assigned to this company."}}},"ReachablePeopleResponse":{"type":"object","properties":{"people":{"type":"array","items":{"$ref":"#/components/schemas/ReachablePerson"}}},"example":{"people":[{"name":"Sarah Johnson","linkedin_id":"sarah-johnson-42","title":"VP of Sales","company_name":"Acme Corp","company_linkedin_url":"https://www.linkedin.com/company/acme-corp","location":"New York, NY","is_target_person":true,"ctd_score":8500.25,"ctd_score_scaled":3,"ctd_score_label":"strong","person_ctd_url":"https://app.ctd.ai/people/sarah-johnson","company_ctd_url":"https://app.ctd.ai/companies/acme-corp","total_paths":5,"total_2nd_degree_paths":3,"total_strong_paths":2},{"name":"Michael Chen","linkedin_id":"michael-chen-88","title":"Engineering Manager","company_name":"Globex Industries","company_linkedin_url":"https://www.linkedin.com/company/globex-industries","location":"San Francisco, CA","is_target_person":false,"ctd_score":4200.1,"ctd_score_scaled":2,"ctd_score_label":"medium","person_ctd_url":"https://app.ctd.ai/people/michael-chen","company_ctd_url":"https://app.ctd.ai/companies/globex-industries","total_paths":2,"total_2nd_degree_paths":1,"total_strong_paths":1}]}},"ReachablePersonResponse":{"type":"object","properties":{"person":{"$ref":"#/components/schemas/ReachablePerson"}},"example":{"person":{"name":"Sarah Johnson","linkedin_id":"sarah-johnson-42","title":"VP of Sales","company_name":"Acme Corp","company_linkedin_url":"https://www.linkedin.com/company/acme-corp","location":"New York, NY","is_target_person":true,"ctd_score":8500.25,"ctd_score_scaled":3,"ctd_score_label":"strong","person_ctd_url":"https://app.ctd.ai/people/sarah-johnson","company_ctd_url":"https://app.ctd.ai/companies/acme-corp","total_paths":5,"total_2nd_degree_paths":3,"total_strong_paths":2,"current_roles":[{"title":"VP of Sales","company_name":"Acme Corp","domain_names":["acme-corp.com"],"ctd_url":"https://app.ctd.ai/companies/acme-corp","is_current":true,"is_primary":true,"when_started":"2024-09-30T22:00:00.000Z","when_ended":null,"company_industry":"Technology, Information & Internet"}],"former_roles":[{"title":"Sales Director","company_name":"Initech Solutions","domain_names":["initech.com"],"ctd_url":"https://app.ctd.ai/companies/initech","is_current":false,"is_primary":false,"when_started":"2021-04-30T22:00:00.000Z","when_ended":"2024-08-30T22:00:00.000Z","company_industry":"Software Development"}]}}},"ReachablePerson":{"type":"object","properties":{"name":{"type":"string","nullable":true,"description":"Full name of the person."},"linkedin_id":{"type":"string","nullable":true,"description":"LinkedIn profile identifier."},"title":{"type":"string","nullable":true,"description":"Current job title."},"company_name":{"type":"string","nullable":true,"description":"Current company name."},"company_linkedin_url":{"type":"string","nullable":true,"description":"LinkedIn company page URL."},"location":{"type":"string","nullable":true,"description":"Geographic location of the person."},"is_target_person":{"type":"boolean","nullable":true,"description":"Whether the person is marked as a target persona."},"ctd_score":{"type":"number","nullable":true,"description":"Relationship strength score. Higher values indicate stronger relationships."},"ctd_score_scaled":{"type":"integer","nullable":true,"minimum":0,"maximum":3,"description":"Scaled CTD score from 0 to 3."},"ctd_score_label":{"type":"string","nullable":true,"enum":["weak","medium","strong"],"description":"Human-readable label for ctd_score_scaled."},"person_ctd_url":{"type":"string","description":"CTD URL for the person's profile."},"company_ctd_url":{"type":"string","description":"CTD URL for the person's company."},"total_paths":{"type":"integer","description":"Total number of paths to this person."},"total_2nd_degree_paths":{"type":"integer","description":"Number of 2nd-degree paths to this person."},"total_strong_paths":{"type":"integer","description":"Number of strong paths to this person."},"current_roles":{"type":"array","description":"Roles this person currently holds.","items":{"$ref":"#/components/schemas/ReachablePersonRole"}},"former_roles":{"type":"array","description":"Roles this person previously held.","items":{"$ref":"#/components/schemas/ReachablePersonRole"}}}},"ReachablePersonRole":{"type":"object","properties":{"title":{"type":"string","nullable":true,"description":"Role title."},"company_name":{"type":"string","nullable":true,"description":"Company name for the role."},"domain_names":{"type":"array","items":{"type":"string"},"description":"Known domain names for the company."},"ctd_url":{"type":"string","nullable":true,"description":"CTD URL for the company."},"is_current":{"type":"boolean","nullable":true,"description":"Whether this role is currently held."},"is_primary":{"type":"boolean","description":"Whether this role is the person's primary role at the company."},"when_started":{"type":"string","format":"date-time","nullable":true,"description":"When the role started."},"when_ended":{"type":"string","format":"date-time","nullable":true,"description":"When the role ended, if applicable."},"company_industry":{"type":"string","nullable":true,"description":"Industry of the company."}}},"ReachablePersonResponseWithTeamRelationship":{"type":"object","properties":{"person":{"$ref":"#/components/schemas/ReachablePersonWithTeamRelationship"}},"example":{"person":{"name":"Sarah Johnson","linkedin_id":"sarah-johnson-42","title":"VP of Sales","company_name":"Acme Corp","company_linkedin_url":"https://www.linkedin.com/company/acme-corp","location":"New York, NY","is_target_person":true,"ctd_score":8500.25,"ctd_score_scaled":3,"ctd_score_label":"strong","team_relationship":{"message_count":1842,"first_message_date":"2020-09-14","last_message_date":"2026-10-20","meeting_count":127,"first_meeting_date":"2021-05-11","last_meeting_date":"2026-10-16","next_meeting_date":"2026-11-12","top_connectors":[{"name":"John Smith","ctd_url":"https://app.ctd.ai/people/3b9e2c1a-7d4f-4e8a-9c2b-5f6a7d8e9f01"},{"name":"Jane Doe","ctd_url":"https://app.ctd.ai/people/8c1d4e5f-2a3b-4c6d-8e9f-0a1b2c3d4e5f"},{"name":"Michael Brown","ctd_url":"https://app.ctd.ai/people/5e7f9a1b-3c5d-4e6f-8a9b-1c2d3e4f5a6b"}]},"person_ctd_url":"https://app.ctd.ai/people/sarah-johnson","company_ctd_url":"https://app.ctd.ai/companies/acme-corp","total_paths":5,"total_2nd_degree_paths":3,"total_strong_paths":2,"current_roles":[{"title":"VP of Sales","company_name":"Acme Corp","domain_names":["acme-corp.com"],"ctd_url":"https://app.ctd.ai/companies/acme-corp","is_current":true,"is_primary":true,"when_started":"2024-09-30T22:00:00.000Z","when_ended":null,"company_industry":"Technology, Information & Internet"}],"former_roles":[{"title":"Sales Director","company_name":"Initech Solutions","domain_names":["initech.com"],"ctd_url":"https://app.ctd.ai/companies/initech","is_current":false,"is_primary":false,"when_started":"2021-04-30T22:00:00.000Z","when_ended":"2024-08-30T22:00:00.000Z","company_industry":"Software Development"}]}}},"ReachablePersonWithTeamRelationship":{"type":"object","properties":{"name":{"type":"string","nullable":true,"description":"Full name of the person."},"linkedin_id":{"type":"string","nullable":true,"description":"LinkedIn profile identifier."},"title":{"type":"string","nullable":true,"description":"Current job title."},"company_name":{"type":"string","nullable":true,"description":"Current company name."},"company_linkedin_url":{"type":"string","nullable":true,"description":"LinkedIn company page URL."},"location":{"type":"string","nullable":true,"description":"Geographic location of the person."},"is_target_person":{"type":"boolean","nullable":true,"description":"Whether the person is marked as a target persona."},"ctd_score":{"type":"number","nullable":true,"description":"Relationship strength score. Higher values indicate stronger relationships."},"ctd_score_scaled":{"type":"integer","nullable":true,"minimum":0,"maximum":3,"description":"Scaled CTD score from 0 to 3."},"ctd_score_label":{"type":"string","nullable":true,"enum":["weak","medium","strong"],"description":"Human-readable label for ctd_score_scaled."},"team_relationship":{"type":"object","nullable":true,"description":"How your team knows this person: your and your co-workers' combined email and meeting history\nwith them. Only company email and company calendar accounts count; personal accounts (Gmail and\nsimilar) stay private.\n- `null` when your enterprise admin has not enabled Enterprise Relationship Insights, or you are\n  not part of an enterprise.\n- When it is enabled but nobody has interacted with the person, the counts are 0, the dates are\n  null and `top_connectors` is empty.\n\nThe field is omitted when this information is temporarily unavailable.\n\nWith an enterprise API key, \"you\" is the member whose email is sent in `ctd-client-id`.\n","allOf":[{"$ref":"#/components/schemas/TeamRelationship"}]},"person_ctd_url":{"type":"string","description":"CTD URL for the person's profile."},"company_ctd_url":{"type":"string","description":"CTD URL for the person's company."},"total_paths":{"type":"integer","description":"Total number of paths to this person."},"total_2nd_degree_paths":{"type":"integer","description":"Number of 2nd-degree paths to this person."},"total_strong_paths":{"type":"integer","description":"Number of strong paths to this person."},"current_roles":{"type":"array","description":"Roles this person currently holds.","items":{"$ref":"#/components/schemas/ReachablePersonRole"}},"former_roles":{"type":"array","description":"Roles this person previously held.","items":{"$ref":"#/components/schemas/ReachablePersonRole"}}}},"TeamRelationship":{"type":"object","nullable":true,"description":"How your team knows a person: your and your co-workers' combined email and meeting history with them, counted only from company email and company calendar accounts. Personal accounts (for example Gmail) are never included. Every key is always present.\n","required":["message_count","first_message_date","last_message_date","meeting_count","first_meeting_date","last_meeting_date","next_meeting_date","top_connectors"],"properties":{"message_count":{"type":"integer","minimum":0,"example":1842,"description":"Total emails exchanged with this person (sent and received) by you and your co-workers. An email several co-workers were on counts once per co-worker.\n"},"first_message_date":{"type":"string","format":"date","nullable":true,"example":"2020-09-14","description":"Date of the earliest of those emails (YYYY-MM-DD, UTC)."},"last_message_date":{"type":"string","format":"date","nullable":true,"example":"2026-10-20","description":"Date of the most recent of those emails (YYYY-MM-DD, UTC)."},"meeting_count":{"type":"integer","minimum":0,"example":127,"description":"Total past meetings with this person that you and your co-workers held. Meetings either side declined are not counted. A meeting several co-workers attended counts once per co-worker.\n"},"first_meeting_date":{"type":"string","format":"date","nullable":true,"example":"2021-05-11","description":"Date of the earliest of those meetings (YYYY-MM-DD, UTC)."},"last_meeting_date":{"type":"string","format":"date","nullable":true,"example":"2026-10-16","description":"Date of the most recent past meeting (YYYY-MM-DD, UTC)."},"next_meeting_date":{"type":"string","format":"date","nullable":true,"example":"2026-11-12","description":"Date of the next scheduled meeting any of you has with this person (YYYY-MM-DD, UTC), or null."},"top_connectors":{"type":"array","maxItems":3,"description":"Up to 3 people in your team (you included) with the most emails and meetings with this person, strongest first. Empty when nobody has interacted with them.\n","items":{"$ref":"#/components/schemas/TeamRelationshipConnector"}}}},"TeamRelationshipConnector":{"type":"object","description":"A person in your team (you included) who has emailed or met the person. Both keys are always present.","required":["name","ctd_url"],"properties":{"name":{"type":"string","nullable":true,"example":"John Smith","description":"The co-worker's full name."},"ctd_url":{"type":"string","nullable":true,"example":"https://app.ctd.ai/people/3b9e2c1a-7d4f-4e8a-9c2b-5f6a7d8e9f01","description":"Link to the co-worker's profile in CTD."}}},"PublicActivityPerson":{"type":"object","nullable":true,"properties":{"name":{"type":"string","nullable":true},"ctd_url":{"type":"string","nullable":true},"linkedin_url":{"type":"string","nullable":true}}},"PublicActivityCompany":{"type":"object","properties":{"name":{"type":"string","nullable":true},"ctd_url":{"type":"string","nullable":true}}},"PublicActivityDecline":{"type":"object","properties":{"by":{"type":"string","nullable":true},"reason":{"type":"string","nullable":true}}},"PublicActivity":{"type":"object","properties":{"type":{"type":"string","enum":["ask","ghost"]},"status":{"type":"string","example":"sent"},"company":{"$ref":"#/components/schemas/PublicActivityCompany"},"initiator":{"$ref":"#/components/schemas/PublicActivityPerson"},"target":{"$ref":"#/components/schemas/PublicActivityPerson"},"connector_1":{"$ref":"#/components/schemas/PublicActivityPerson"},"connector_2":{"$ref":"#/components/schemas/PublicActivityPerson"},"decline":{"$ref":"#/components/schemas/PublicActivityDecline"},"shared_at":{"type":"string","format":"date-time","nullable":true},"sent_at":{"type":"string","format":"date-time","nullable":true},"status_updated_at":{"type":"string","format":"date-time","nullable":true},"updated_at":{"type":"string","format":"date-time","nullable":true}}},"PublicActivitiesResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicActivity"}},"total_count":{"type":"integer","example":0}}},"PublicExternalMembersResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PublicExternalMember"}},"total_count":{"type":"integer","example":0}}},"PublicExternalMember":{"type":"object","properties":{"email":{"type":"string","format":"email","description":"Email address of the external member.","example":"jane.doe@example.com"},"name":{"type":"string","nullable":true,"description":"Full name of the external member.","example":"Jane Doe"},"status":{"type":"string","description":"Human-readable status of the external member (e.g., 'Accepted', 'Waiting To Be Sent').","example":"Accepted"},"type":{"type":"string","nullable":true,"description":"Human-readable category of the external member (e.g., 'Board Member', 'Investor').","example":"Board Member"},"accepted_date":{"type":"string","format":"date-time","nullable":true,"description":"When the external member accepted the invitation."},"email_account_added":{"type":"boolean","description":"Whether the member connected an email account. Only populated for accepted members; false otherwise."},"linkedin_account_added":{"type":"boolean","description":"Whether the member imported LinkedIn contacts. Only populated for accepted members; false otherwise."},"num_contacts":{"type":"integer","description":"Number of contacts imported by the member. Only populated for accepted members; 0 otherwise.","example":0},"invited_by":{"type":"string","format":"email","nullable":true,"description":"Email address of the person who invited the external member."},"created_at":{"type":"string","format":"date-time","nullable":true,"description":"When the external member record was created."},"sent_at":{"type":"string","format":"date-time","nullable":true,"description":"When the invitation was sent."},"declined_at":{"type":"string","format":"date-time","nullable":true,"description":"When the invitation was declined."},"deactivated_at":{"type":"string","format":"date-time","nullable":true,"description":"When the external member was deactivated."}}},"TargetAccountImportCreatedResponse":{"type":"object","properties":{"import_id":{"type":"string","format":"uuid","description":"Identifier of the created import. Use it to upload batches and to poll the import status.","example":"3f2504e0-4f89-41d3-9a0c-0305e82c3301"}}},"TargetAccountInput":{"type":"object","description":"A single target account row. At least one of `website` or `linkedin_url` must be provided; rows that provide neither are reported in `failed_reasons` and skipped. All fields are optional and accept empty string or null.\n","properties":{"website":{"type":"string","nullable":true,"description":"Company website or primary domain. Normalized before processing (e.g. 'https://example.com' or 'example.com').","example":"example.com"},"linkedin_url":{"type":"string","nullable":true,"description":"Company LinkedIn URL. Normalized to `https://www.linkedin.com/company/<slug>`.","example":"https://www.linkedin.com/company/example"},"account_id":{"type":"string","nullable":true,"description":"Your external identifier for the account (e.g. CRM account id).","example":"0015000000XyZ12AAA"},"account_type":{"type":"string","nullable":true,"description":"Free-form classification of the account.","example":"Customer"},"account_owner_email":{"type":"string","format":"email","nullable":true,"description":"Email address of the account owner. Used to resolve owner data within your organization.","example":"owner@yourcompany.com"},"secondary_account_owner_email":{"type":"string","format":"email","nullable":true,"description":"Email address of a secondary account owner.","example":"co-owner@yourcompany.com"},"tier":{"type":"string","nullable":true,"description":"Free-form account tier label.","example":"Tier 1"},"custom1":{"type":"string","nullable":true,"description":"Custom free-form field 1."},"custom2":{"type":"string","nullable":true,"description":"Custom free-form field 2."},"custom3":{"type":"string","nullable":true,"description":"Custom free-form field 3."},"custom4":{"type":"string","nullable":true,"description":"Custom free-form field 4."},"number_of_opportunities":{"type":"integer","format":"int32","minimum":0,"nullable":true,"description":"Total number of opportunities associated with the account.","example":5},"number_of_open_opportunities":{"type":"integer","format":"int32","minimum":0,"nullable":true,"description":"Number of currently open opportunities associated with the account.","example":2}}},"AddTargetAccountsBatchRequest":{"type":"object","required":["import_id","target_accounts","last_batch"],"properties":{"import_id":{"type":"string","format":"uuid","description":"Identifier of the import (in `ACCEPTING_BATCHES` state) this batch belongs to.","example":"3f2504e0-4f89-41d3-9a0c-0305e82c3301"},"target_accounts":{"type":"array","minItems":1,"maxItems":50,"description":"The target account rows to add. Maximum of 50 rows per batch.","items":{"$ref":"#/components/schemas/TargetAccountInput"}},"last_batch":{"type":"boolean","description":"Whether this is the final batch for the import. When `true`, the import is closed and queued for processing and will no longer accept further batches.\n","example":false}}},"TargetAccountBatchFailedReason":{"type":"object","description":"A row that could not be accepted, together with the reason.","properties":{"website":{"type":"string","nullable":true,"example":null},"linkedin_url":{"type":"string","nullable":true,"example":null},"account_id":{"type":"string","nullable":true,"example":"0015000000XyZ12AAA"},"reason":{"type":"string","description":"Human-readable explanation of why the row was rejected.","example":"Row is invalid, either website or linkedin_url must be provided"}}},"AddTargetAccountsBatchResponse":{"type":"object","properties":{"inserted":{"type":"integer","description":"Number of rows inserted into staging from this batch (after de-duplication).","example":48},"failed":{"type":"integer","description":"Number of rows in this batch that were rejected.","example":2},"failed_reasons":{"type":"array","description":"Details for each rejected row.","items":{"$ref":"#/components/schemas/TargetAccountBatchFailedReason"}}}},"TargetAccountImportStatusResponse":{"type":"object","properties":{"import_id":{"type":"string","format":"uuid","description":"Identifier of the import.","example":"3f2504e0-4f89-41d3-9a0c-0305e82c3301"},"status":{"type":"string","enum":["ACCEPTING_BATCHES","READY_TO_PROCESS","READY_TO_PROCESS_STALE","PROCESSING","COMPLETED","STALE_PROMOTED_COMPLETED","FAILED","PENDING_DELETE"],"description":"Current status of the import.","example":"COMPLETED"},"type":{"type":"string","enum":["IMPORT","DELETE_ALL"],"description":"Type of the import. `IMPORT` for uploads, `DELETE_ALL` for bulk deletions.","example":"IMPORT"},"inserted_row_count":{"type":"integer","description":"Total number of rows inserted into staging across all batches.","example":120},"failed_row_count":{"type":"integer","description":"Total number of rows rejected across all batches.","example":3},"error_message":{"type":"string","nullable":true,"description":"Error detail when the import has failed; otherwise null.","example":null},"stale":{"type":"boolean","description":"Whether this import was superseded by a newer import before processing.","example":false},"last_batch_received_at":{"type":"string","format":"date-time","nullable":true,"description":"Timestamp when the last batch was received; null if no batch has been received yet."},"processed_at":{"type":"string","format":"date-time","nullable":true,"description":"Timestamp when processing completed; null until the import reaches a terminal state."},"created_at":{"type":"string","format":"date-time","description":"Timestamp when the import was created."},"updated_at":{"type":"string","format":"date-time","description":"Timestamp when the import was last updated."}}},"PublicCustomColumnNameMapping":{"type":"object","properties":{"column_name":{"type":"string","description":"The public custom column identifier.","enum":["custom_1","custom_2","custom_3","custom_4","custom_account_owner"],"example":"custom_1"},"display_name":{"type":"string","description":"The display name configured by your organization for this column.","example":"Region"}}},"PublicCustomColumnNamesResponse":{"type":"object","properties":{"mapping":{"type":"array","description":"The mapping between public custom column names and their configured display names.","items":{"$ref":"#/components/schemas/PublicCustomColumnNameMapping"}}}},"RenameCustomColumnsRequest":{"type":"object","required":["mapping"],"properties":{"mapping":{"type":"array","minItems":1,"description":"The display name changes to apply. Each `column_name` must be one of the renameable custom columns and may appear at most once.\n","items":{"type":"object","required":["column_name","display_name"],"properties":{"column_name":{"type":"string","enum":["custom_1","custom_2","custom_3","custom_4","custom_account_owner"],"description":"The custom column to rename.","example":"custom_1"},"display_name":{"type":"string","minLength":1,"description":"The new display name for the column.","example":"Region"}}}}}}},"responses":{"Conflict":{"description":"Conflicts with the current state (seat limit reached, type slug exists, default type, ambiguous LinkedIn profile, no sending mailbox)","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"details":{"type":"array","items":{"type":"object"}}}}}}},"PayloadTooLarge":{"description":"The uploaded file is over 20 MB","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"The LinkedIn connections file is too large"}}}}}},"InternalServerError":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Internal server error"},"code":{"type":"string","example":"10.5","description":"Code used for Frontend"}}}}}},"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Bad request","description":"More descriptive message about error, intended to be used by developers"},"code":{"type":"string","example":"10.4"},"details":{"type":"object","description":"Mostly used for joi errors, what went wrong"}}}}}},"UsageTooSlow":{"description":"Counting usage for this period took longer than 20 seconds. Ask for fewer months.\n","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Usage for this period took too long to count. Ask for fewer months."}}}}}},"NotFound":{"description":"Item Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Item not found","description":"More descriptive message about error, intended to be used by developers"},"code":{"type":"string","example":"23.06"}}}}}},"Forbidden":{"description":"User is forbidden to do this action","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Forbidden","description":"More descriptive message about error, intended to be used by developers"},"code":{"type":"string","example":"10.4.3"}}}}}}}}}