This is HTML content
" ] }, "content_type": { "type": "string", "enum": [ "text", "html" ], "default": "text", "description": "Specifies the format of the provided content. Use \"text\" for plain text or \"html\" for HTML formatted content", "example": "text" } }, "required": [ "activity_content" ] }, "V0UpdatePersonActivityResponse": { "type": "object", "properties": { "error": { "type": [ "string", "null" ] }, "data": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "updated_at" ] } }, "required": [ "error", "data" ] }, "UnifiedGetPersonDetailsResponse": { "type": "object", "properties": { "error": { "type": [ "string", "null" ], "description": "Error message, if any" }, "data": { "allOf": [ { "$ref": "#/components/schemas/GetPersonDetailsData" }, { "type": [ "object", "null" ] } ] } }, "required": [ "error", "data" ] }, "GetPersonDetailsData": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the person" }, "name": { "type": [ "string", "null" ], "description": "The name of the person" }, "linkedin_public_id": { "type": [ "string", "null" ], "description": "The LinkedIn public ID" }, "first_name": { "type": [ "string", "null" ], "description": "First name" }, "last_name": { "type": [ "string", "null" ], "description": "Last name" }, "current_job_title": { "type": [ "string", "null" ], "description": "Current job title" }, "external_source_id": { "type": [ "string", "null" ], "description": "External system identifier" }, "emails": { "type": "array", "items": { "$ref": "#/components/schemas/ContactValue" }, "description": "Email addresses" }, "phones": { "type": "array", "items": { "$ref": "#/components/schemas/ContactValue" }, "description": "Phone numbers" } }, "required": [ "id", "name", "linkedin_public_id", "first_name", "last_name", "current_job_title", "external_source_id", "emails", "phones" ] }, "ContactValue": { "type": "object", "properties": { "contact_data_type": { "type": [ "string", "null" ], "description": "Category of contact (work/personal/etc)" }, "value": { "type": "string", "description": "Contact value" } }, "required": [ "contact_data_type", "value" ] }, "AddPersonRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Full name of the person" }, "first_name": { "type": "string", "description": "First name of the person" }, "last_name": { "type": "string", "description": "Last name of the person" }, "linkedin_url": { "type": "string", "format": "uri", "description": "LinkedIn profile URL" }, "current_job_title": { "type": "string", "description": "Current job title" }, "linkedin_location": { "type": "string", "description": "LinkedIn location" }, "company_name": { "type": "string", "description": "Current company name" }, "emails": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "Additional email addresses as an array" }, "work_email": { "type": "string", "format": "email", "description": "Work email address" }, "work_phone": { "type": "string", "description": "Work phone number" }, "personal_email": { "type": "string", "format": "email", "description": "Personal email address" }, "mobile_phone": { "type": "string", "description": "Mobile phone number" }, "phone_numbers": { "type": "array", "items": { "type": "string" }, "description": "Additional phone numbers as an array" }, "notes": { "type": "string", "description": "Initial notes about the person" }, "job_id": { "type": "string", "description": "Job ID for candidate association" }, "job_name": { "type": "string", "description": "Job name for candidate association" }, "client_name": { "type": "string", "description": "Client company name" }, "client_id": { "type": "string", "description": "Explicit client company ID if known" }, "external_source_id": { "type": "string", "description": "External source ID for the person (e.g. Hubspot, External system, etc.)" }, "enrich_record": { "type": "boolean", "description": "Whether to enrich the person record" } }, "required": [ "name", "linkedin_url" ] }, "UnifiedAddPersonResponse": { "type": "object", "properties": { "error": { "type": [ "string", "null" ], "description": "Error message, if any" }, "data": { "allOf": [ { "$ref": "#/components/schemas/AddPersonData" }, { "type": [ "object", "null" ] } ] } }, "required": [ "error", "data" ] }, "AddPersonData": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the person" }, "name": { "type": "string", "description": "The name of the person" }, "linkedin_public_id": { "type": [ "string", "null" ], "description": "The LinkedIn public ID" }, "current_job_title": { "type": [ "string", "null" ], "description": "Current job title" }, "company_name": { "type": [ "string", "null" ], "description": "Current company name" }, "emails": { "type": "array", "items": { "$ref": "#/components/schemas/ContactValue" }, "description": "Email addresses" }, "linkedin_location": { "type": [ "string", "null" ], "description": "LinkedIn location" }, "phones": { "type": "array", "items": { "$ref": "#/components/schemas/ContactValue" }, "description": "Phone numbers" }, "candidate_id": { "type": [ "string", "null" ], "description": "Candidate ID if associated with a job" }, "client_contact_id": { "type": [ "string", "null" ], "description": "Client contact ID if associated with a client" }, "external_source_id": { "type": [ "string", "null" ], "description": "External source ID for the person" } }, "required": [ "id", "name", "linkedin_public_id", "current_job_title", "company_name", "emails", "linkedin_location", "phones", "candidate_id", "client_contact_id", "external_source_id" ] }, "SearchPersonsResponse": { "type": "object", "properties": { "error": { "type": [ "string", "null" ] }, "data": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/PersonSearchResult" } } }, "required": [ "error", "data" ] }, "PersonSearchResult": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "linkedin_public_id": { "type": [ "string", "null" ] }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "current_job_title": { "type": [ "string", "null" ] }, "emails": { "type": "array", "items": { "$ref": "#/components/schemas/ContactValue" } }, "phones": { "type": "array", "items": { "$ref": "#/components/schemas/ContactValue" } } }, "required": [ "id", "name", "linkedin_public_id", "first_name", "last_name", "current_job_title", "emails", "phones" ] }, "V0UpdatePersonRequest": { "type": "object", "properties": { "linkedin_url": { "type": "string", "description": "LinkedIn profile URL (alternative to using person ID)" }, "emails": { "type": "array", "items": { "$ref": "#/components/schemas/ContactValue" }, "description": "Email addresses to update/add as an array" }, "phone_numbers": { "type": "array", "items": { "$ref": "#/components/schemas/ContactValue" }, "description": "Phone numbers to update/add as an array" }, "name": { "type": "string", "description": "Full name" }, "first_name": { "type": "string", "description": "First name" }, "last_name": { "type": "string", "description": "Last name" }, "current_job_title": { "type": "string", "description": "Current job title" }, "company_name": { "type": "string", "description": "Current company name" }, "linkedin_location": { "type": "string", "description": "LinkedIn location" }, "linkedin_headline": { "type": "string", "description": "LinkedIn headline" }, "address": { "type": "string", "description": "Physical address" }, "enrich_record": { "type": "boolean", "description": "Whether to enrich the person record" }, "work_email": { "type": "string", "description": "Work email address" }, "personal_email": { "type": "string", "description": "Personal email address" }, "mobile_phone": { "type": "string", "description": "Mobile phone number" }, "work_phone": { "type": "string", "description": "Work phone number" } } }, "V0UpdatePersonResponse": { "type": "object", "properties": { "error": { "type": [ "string", "null" ], "description": "Error message if any" }, "data": { "type": [ "object", "null" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "success", "message" ] } }, "required": [ "error", "data" ] } }, "parameters": {}, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Authenticate with a Bearer token: API key, OAuth token, or session token." } } }, "paths": { "/v0/person-activities": { "post": { "summary": "Add a new person activity", "description": "Creates a new activity for a person", "tags": [ "people", "activities" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V0AddPersonActivityRequest" } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnifiedAddPersonActivityResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnifiedAddPersonActivityResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnifiedAddPersonActivityResponse" } } } } } }, "get": { "summary": "Get person activities", "description": "Retrieves activities for a specific person with pagination", "tags": [ "people", "activities" ], "parameters": [ { "in": "query", "name": "person_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "default": 40 } }, { "in": "query", "name": "offset", "required": false, "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPersonActivitiesResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPersonActivitiesResponse" } } } }, "404": { "description": "Person not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPersonActivitiesResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPersonActivitiesResponse" } } } } } } }, "/v0/person-activities/{id}": { "get": { "summary": "Get a person activity", "description": "Retrieves a person activity by ID with its content in both HTML and raw text formats", "tags": [ "people", "activities" ], "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnifiedGetPersonActivityResponse" } } } }, "404": { "description": "Activity not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnifiedGetPersonActivityResponse" } } } } } }, "put": { "summary": "Update a person activity", "description": "Updates the content of an existing person activity. \n Supports both plain text and HTML content formats.\n \n - For plain text, the content will be wrapped in a paragraph structure\n - For HTML, the content will be parsed and converted to the appropriate format while preserving formatting\n \n The activity must belong to the authenticated organization and team.", "tags": [ "people", "activities" ], "parameters": [ { "in": "path", "name": "id", "required": true, "description": "The unique identifier of the activity to update", "schema": { "type": "string" }, "example": "123e4567-e89b-12d3-a456-426614174000" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V0UpdatePersonActivityBody" }, "examples": { "plainText": { "summary": "Plain Text Update", "value": { "activity_content": "This is a simple text update", "content_type": "text" } }, "htmlContent": { "summary": "HTML Content Update", "value": { "activity_content": "This is a formatted update with styling
", "content_type": "html" } } } } } }, "responses": { "200": { "description": "Activity successfully updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V0UpdatePersonActivityResponse" }, "example": { "error": null, "data": { "id": "123e4567-e89b-12d3-a456-426614174000", "updated_at": "2024-03-15T12:00:00Z" } } } } }, "400": { "description": "Invalid request parameters or body", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V0UpdatePersonActivityResponse" }, "example": { "error": "Invalid content format", "data": null } } } }, "404": { "description": "Activity not found or does not belong to the organization/team", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V0UpdatePersonActivityResponse" }, "example": { "error": "Activity not found", "data": null } } } }, "500": { "description": "Internal server error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V0UpdatePersonActivityResponse" }, "example": { "error": "Internal server error", "data": null } } } } } } }, "/v0/persons": { "get": { "summary": "Get person details by LinkedIn URL or ID", "description": "Returns person details by LinkedIn URL or ID", "tags": [ "people" ], "parameters": [ { "schema": { "type": "string", "format": "uri", "description": "The LinkedIn URL of the person" }, "required": false, "name": "linkedin_url", "in": "query" }, { "schema": { "type": "string", "description": "The ID of the person" }, "required": false, "name": "person_id", "in": "query" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnifiedGetPersonDetailsResponse" }, "example": { "error": null, "data": { "id": "123e4567-e89b-12d3-a456-426614174000", "name": "John Doe", "linkedin_public_id": "johndoe", "first_name": "John", "last_name": "Doe", "current_job_title": "Software Engineer", "external_source_id": "ext123", "emails": [ { "contact_data_type": "work", "value": "john@company.com" } ], "phones": [ { "contact_data_type": "mobile", "value": "+1234567890" } ] } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnifiedGetPersonDetailsResponse" }, "example": { "error": "Invalid LinkedIn URL", "data": null } } } }, "404": { "description": "Person not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnifiedGetPersonDetailsResponse" }, "example": { "error": "Person not found", "data": null } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnifiedGetPersonDetailsResponse" }, "example": { "error": "Internal server error", "data": null } } } } } }, "post": { "summary": "Add a new person", "description": "Creates a new person record with comprehensive profile information.\n - Creates associated work experience if company and job title provided\n - Links person to job/candidate if job details provided\n - Links person as client contact if client details provided\n - Handles multiple contact details (emails/phones)\n - Creates initial notes if provided", "tags": [ "people" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddPersonRequest" } } } }, "responses": { "201": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnifiedAddPersonResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnifiedAddPersonResponse" } } } }, "409": { "description": "The person asked to be deleted from, or not contacted by, your workspace, and their email or LinkedIn profile is on its do-not-re-add list. They are added again only if they apply to one of your jobs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnifiedAddPersonResponse" }, "example": { "error": "This person asked to be removed from your workspace and can't be added again.", "data": null } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnifiedAddPersonResponse" } } } } } } }, "/v0/persons/search": { "get": { "summary": "Search for persons by email, phone, or name", "description": "Search for persons using various criteria:\n - Email/Phone search: Exact match, returns all matching persons\n - Name search: Partial match (case-insensitive), returns up to 20 results\n - At least one search parameter (email, phone, or name) must be provided\n - Results include basic person details and all associated contact information", "tags": [ "people" ], "parameters": [ { "schema": { "type": "string", "format": "email", "description": "Email address to search for" }, "required": false, "name": "email", "in": "query" }, { "schema": { "type": "string", "description": "Phone number to search for" }, "required": false, "name": "phone", "in": "query" }, { "schema": { "type": "string", "description": "Name to search for" }, "required": false, "name": "name", "in": "query" } ], "responses": { "200": { "description": "Successfully retrieved search results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchPersonsResponse" }, "example": { "error": null, "data": [ { "id": "123e4567-e89b-12d3-a456-426614174000", "name": "John Smith", "linkedin_public_id": "john-smith-123", "first_name": "John", "last_name": "Smith", "current_job_title": "Software Engineer", "emails": [ { "contact_data_type": "work", "value": "john.smith@company.com" } ], "phones": [ { "contact_data_type": "mobile", "value": "+1234567890" } ] } ] } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchPersonsResponse" }, "example": { "error": "Invalid request parameters", "data": null } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchPersonsResponse" }, "example": { "error": "Internal server error", "data": null } } } } } } }, "/v0/persons/{id}": { "patch": { "summary": "Update person details", "description": "Updates a person's information including contact details and professional information.\n - Contact details (emails/phones) are upserted - existing records are updated, new ones are added\n - Professional details are updated if provided\n - All fields are optional - only provided fields will be updated", "tags": [ "people" ], "parameters": [ { "in": "path", "name": "id", "required": true, "description": "Person ID", "schema": { "type": "string" }, "example": "123e4567-e89b-12d3-a456-426614174000" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V0UpdatePersonRequest" }, "example": { "emails": [ { "contact_data_type": "work", "value": "john.doe@company.com" }, { "contact_data_type": "personal", "value": "john@gmail.com" } ], "phones": [ { "contact_data_type": "work", "value": "+1-555-0123" }, { "contact_data_type": "mobile", "value": "+1-555-0124" } ], "current_job_title": "Senior Software Engineer", "linkedin_location": "San Francisco Bay Area", "linkedin_headline": "Building innovative solutions | Tech Lead at Company", "address": "123 Main St, San Francisco, CA 94105" } } } }, "responses": { "200": { "description": "Successfully updated person", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V0UpdatePersonResponse" }, "example": { "error": null, "data": { "success": true, "message": "Person updated successfully" } } } } }, "400": { "description": "Bad request - invalid data provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V0UpdatePersonResponse" }, "example": { "error": "Invalid request data. Check the request body.", "data": null } } } }, "404": { "description": "Person not found or not accessible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V0UpdatePersonResponse" }, "example": { "error": "Person not found", "data": null } } } }, "409": { "description": "The person asked to be deleted from, or not contacted by, your workspace, and their email or LinkedIn profile is on its do-not-re-add list. They are added again only if they apply to one of your jobs.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V0UpdatePersonResponse" }, "example": { "error": "This person asked to be removed from your workspace and can't be added again.", "data": null } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V0UpdatePersonResponse" }, "example": { "error": "Internal server error", "data": null } } } } } } } }, "webhooks": {}, "security": [ { "bearerAuth": [] } ] }