{"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. 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","minProperties":1,"properties":{"company_stage":{"type":"string","nullable":true,"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.\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.","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/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.","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/PublicPathsResponseV2"}}}},"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 numeric path ID for the authenticated enterprise. 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.\n","tags":["Paths"],"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":"pathId","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d+$"},"description":"Numeric identifier of the path to update."}],"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.","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/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/connector":{"get":{"operationId":"getPathsByConnectorV2","summary":"Paths through a specific connector","description":"Paths that pass through the specified connector within your organization'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":"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/PublicPathsResponseV2"}}}},"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.","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/PublicGlobalPathsResponseV2"}}}},"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","description":"Returns 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"}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"ctd-api-key","description":"Enterprise CTD API key, used for authentication."}},"schemas":{"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":"integer","description":"Unique identifier of the path in the path_new table."},"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_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":1234567,"stage":"Not started","degree":1,"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":1234567,"stage":"Not started","degree":1,"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."}}},"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":"integer","description":"Unique identifier of the path in the path_new table."},"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},"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":1234567,"stage":"Not started","degree":1,"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"}]}],"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":1234567,"stage":"Not started","degree":1,"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"}]}],"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"}]}}]}},"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."}}},"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":{"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"}}}}}},"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"}}}}}}}}}