{ "openapi": "3.0.1", "info": { "title": "Salesfinity API", "description": "The Salesfinity API is a JSON-over-HTTPS REST API for the Salesfinity parallel dialer.\nUse it to manage contact lists, read call logs and AI call scores, pull team and SDR\nanalytics, and enrich email addresses. Webhook subscriptions are managed in the\nSalesfinity application rather than through this API.\n\n## Base URL\n\nAll requests go to `https://client-api.salesfinity.co`. There is no separate sandbox host;\nsee the developer portal for the recommended way to test safely.\n\n## Authentication\n\nEvery endpoint requires an API key sent in the `x-api-key` request header. Generate a key\nin the Salesfinity dashboard under **Settings -> Connections & API**. A key is scoped to a\nsingle team, and every response is filtered to that team.\n\n```bash\ncurl https://client-api.salesfinity.co/v1/team \\\n --header 'x-api-key: YOUR_API_KEY'\n```\n\n## Errors\n\nErrors are always JSON and always use the same envelope, so a client can parse a failure\nthe same way on every endpoint:\n\n```json\n{ \"message\": \"Forbidden resource\", \"error\": \"Forbidden\", \"statusCode\": 403 }\n```\n\n`statusCode` matches the HTTP status. `error` is the stable reason phrase to branch on.\n`message` is human readable, and is an array of strings when request validation fails.\nNote that a missing or invalid API key returns **403**, not 401.\n\n## Pagination\n\nList endpoints accept `page` (1-based) and `limit` query parameters and return the matching\npage alongside the total count. The `limit` default varies by endpoint (10, 50, or 100) and\nis capped at 100 where a cap applies, so read the parameter schema on the operation itself.\n\n## Rate limits\n\nSalesfinity does not currently publish a fixed request quota. Treat HTTP 429 as retryable\nand back off with exponential jitter.", "version": "1.0.0", "termsOfService": "https://salesfinity.ai/terms", "contact": { "name": "Salesfinity Support", "email": "hello@salesfinity.co", "url": "https://support.salesfinity.ai" }, "license": { "name": "MIT", "url": "https://opensource.org/licenses/MIT" } }, "servers": [ { "url": "https://client-api.salesfinity.co", "description": "Production. The only public Salesfinity API host." } ], "security": [ { "ApiKeyAuth": [] } ], "paths": { "/v1/contact-lists": { "post": { "tags": [ "Contact Lists" ], "description": "Creates a new contact list", "operationId": "create-list", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateContactListDTO" } } } }, "responses": { "201": { "description": "Contact list created successfully", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "summary": "Create a contact list" } }, "/v1/contact-lists/{id}/contacts/{contactId}": { "delete": { "tags": [ "Contact Lists" ], "description": "Remove a contact from a contact list", "operationId": "remove-contact", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the contact list." }, { "name": "contactId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The ID of the contact to remove." } ], "responses": { "200": { "description": "Contact removed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "example": { "message": "Contact removed successfully" } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Contact or list not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "security": [ { "ApiKeyAuth": [] } ], "summary": "Remove a contact from a list" } }, "/v1/team": { "get": { "tags": [ "Teams" ], "description": "Returns team information", "operationId": "get-team", "responses": { "200": { "description": "Team information retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetTeamsResponseDTO" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "summary": "Get the current team" } }, "/v1/contact-lists/csv": { "get": { "tags": [ "Contact Lists" ], "summary": "List contact lists", "description": "Returns all CSV contact lists for the team with filtering, sorting, and pagination.", "operationId": "get-contact-lists-csv", "parameters": [ { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search lists by name (case-insensitive)" }, { "name": "filters[user]", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by user ID" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Sort field. Prefix with - for descending. Default: -createdAt" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "Page number" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "description": "Items per page" } ], "responses": { "200": { "description": "CSV contact lists retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CSVListsResponse" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/contact-lists/{id}": { "post": { "tags": [ "Contact Lists" ], "description": "Add a contact to an existing list", "operationId": "add-contact", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Contact list ID to add the contact to, as returned by Create a List or List contact lists." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactListContactDTO" } } } }, "responses": { "201": { "description": "Contact added successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ObjectId" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "summary": "Add a contact to a list" } }, "/v1/contact-lists/{id}/merge": { "post": { "tags": [ "Contact Lists" ], "summary": "Merge contact lists", "description": "Merges contacts from one or more source lists into the target list. Optionally deletes the source lists after merging.", "operationId": "merge-lists", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Target contact list ID to merge into", "schema": { "type": "string", "example": "507f1f77bcf86cd799439011" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MergeContactListsDTO" } } } }, "responses": { "201": { "description": "Lists merged successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactListDTO" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Target contact list not found. Check the path and any ID in it. A 404 also means the resource exists but is not owned by the team that the API key belongs to.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Cannot GET /v1/unknown-route", "error": "Not Found", "statusCode": 404 } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/contact-lists/csv/{id}": { "get": { "tags": [ "Contact Lists" ], "summary": "Get a contact list", "description": "Returns a single CSV contact list with all its contacts. Supports searching, sorting, and paginating contacts.", "operationId": "get-contact-list-by-id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "CSV contact list ID" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search contacts by first name, last name, email, or company" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Sort contacts by field. Prefix with - for descending" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "Page number for contacts" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 50 }, "description": "Contacts per page" } ], "responses": { "200": { "description": "CSV contact list retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CSVListDetailResponse" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "CSV contact list not found. Check the path and any ID in it. A 404 also means the resource exists but is not owned by the team that the API key belongs to.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Cannot GET /v1/unknown-route", "error": "Not Found", "statusCode": 404 } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "tags": [ "Contact Lists" ], "description": "Delete a contact list", "operationId": "delete-contact-list", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the CSV contact list to delete, as returned by Create a List or List contact lists." } ], "responses": { "200": { "description": "Contact list deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } }, "example": { "success": true } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "summary": "Delete a contact list" } }, "/v1/contact-lists/csv/{id}/reimport": { "post": { "tags": [ "Contact Lists" ], "description": "Reimport contacts from CSV", "operationId": "reimport-contacts", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "ID of the CSV contact list to reimport into the dialing queue." } ], "responses": { "201": { "description": "Contacts reimported successfully", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "summary": "Reimport a contact list into the dialing queue" } }, "/v1/dispositions": { "get": { "tags": [ "Dispositions" ], "description": "Returns all dispositions available for the team, including default and custom dispositions", "operationId": "get-dispositions", "parameters": [ { "name": "is_custom", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Filter by custom (true) or default (false) dispositions" }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "positive", "negative", "neutral", "not_answered", "cancelled" ] }, "description": "Filter by disposition category" } ], "responses": { "200": { "description": "Dispositions retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DispositionDTO" } } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "summary": "List dispositions" } }, "/v1/dispositions/{id}": { "get": { "tags": [ "Dispositions" ], "description": "Get a specific disposition by its internal ID", "operationId": "get-disposition-by-id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Internal disposition ID" } ], "responses": { "200": { "description": "Disposition retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DispositionDTO" } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Disposition not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "summary": "Get a disposition" } }, "/v1/sequences": { "get": { "tags": [ "Sequences" ], "description": "Returns all sequences used in call logs for the team", "operationId": "get-sequences", "parameters": [ { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search sequences by name" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "-last_used_at", "last_used_at", "-total_calls", "total_calls", "-name", "name" ] }, "description": "Sort field and order. Default: -last_used_at" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "description": "Results per page" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "Page number" } ], "responses": { "200": { "description": "Sequences retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SequenceDTO" } }, "pagination": { "type": "object", "properties": { "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" } } } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "summary": "List sequences" } }, "/v1/sequences/{id}": { "get": { "tags": [ "Sequences" ], "description": "Get a specific sequence by ID", "operationId": "get-sequence-by-id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Sequence ID" } ], "responses": { "200": { "description": "Sequence retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SequenceDTO" } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Sequence not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "summary": "Get a sequence" } }, "/v1/call-log": { "get": { "tags": [ "Call Logs" ], "description": "Retrieves a paginated list of call logs with filtering and sorting support.", "operationId": "get-call-logs", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "description": "Number of items per page (default: 10, max: 100)" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "The current page number (default: 1)" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Sort field with optional `-` prefix for descending order. Default: `-createdAt`" }, { "name": "filters[start_date]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Start of date range (ISO 8601)" }, { "name": "filters[end_date]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "End of date range (ISO 8601)" }, { "name": "filters[outcome]", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "answered", "no-answer", "cancelled" ] }, "description": "Filter by call outcome" }, { "name": "filters[direction]", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "inbound", "outbound" ] }, "description": "Filter by call direction" }, { "name": "filters[min_duration]", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0 }, "description": "Minimum call duration in seconds" }, { "name": "filters[max_duration]", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0 }, "description": "Maximum call duration in seconds" }, { "name": "filters[has_recording]", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Filter by recording availability" }, { "name": "filters[answered_by]", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "human", "machine_start" ] }, "description": "Filter by who answered the call" }, { "name": "filters[is_completed]", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Filter by completion status" }, { "name": "filters[disposition_ids]", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "integer" } }, "description": "Filter by disposition IDs. See Get Dispositions for available IDs." }, { "name": "filters[exclude_negative_dispositions]", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "When true, only returns calls with positive dispositions (Meeting Set, Referral, Callback Later, etc.)" }, { "name": "filters[user_ids]", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "description": "Filter by user IDs" }, { "name": "filters[contact_list_ids]", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "description": "Filter by contact list IDs" }, { "name": "filters[contact_ids]", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "description": "Filter by contact IDs (the contact's _id)" }, { "name": "filters[crm_ids]", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "description": "Filter by CRM IDs (the contact's crm_id)" }, { "name": "filters[sequences]", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "description": "Filter by sequence IDs. See Get Sequences to discover available sequences." }, { "name": "filters[from]", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "description": "Filter by caller phone numbers" }, { "name": "filters[to]", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "description": "Filter by called phone numbers" }, { "name": "filters[search]", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Full-text search across the contact's name, company, account, title and email, the to/from and contact phone numbers, and the call notes, summary and disposition/call purpose/call sentiment names. Call transcripts are not searched." } ], "responses": { "200": { "description": "A paginated list of call logs with metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallLogListResponse" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "summary": "List call logs" } }, "/v1/analytics/overview": { "get": { "tags": [ "Analytics" ], "description": "Returns aggregated analytics metrics with growth rates compared to the previous period", "operationId": "get-analytics-overview", "parameters": [ { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Start date for the analytics period (ISO 8601). Examples: 2024-01-01, 2024-01-01T00:00:00.000Z, 2024-01-01T00:00:00-05:00. If omitted, defaults to 7 days before end_date." }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "End date for the analytics period (ISO 8601). Examples: 2024-01-31, 2024-01-31T23:59:59.999Z, 2024-01-31T23:59:59-05:00. If omitted, defaults to the current date." }, { "name": "user_ids", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "description": "Filter by specific user IDs" }, { "name": "disposition_ids", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "integer" } }, "description": "Filter by disposition IDs (1-14)" }, { "name": "timezone", "in": "query", "required": false, "schema": { "type": "string" }, "description": "IANA timezone for date calculations (e.g., America/New_York)" } ], "responses": { "200": { "description": "Analytics overview retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsOverviewResponse" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "summary": "Get analytics overview" } }, "/v1/analytics/list-performance": { "get": { "tags": [ "Analytics" ], "description": "Returns call metrics grouped by contact list with pagination", "operationId": "get-list-performance", "parameters": [ { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Start date for the analytics period (ISO 8601). Examples: 2024-01-01, 2024-01-01T00:00:00.000Z, 2024-01-01T00:00:00-05:00. If omitted, defaults to 7 days before end_date." }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "End date for the analytics period (ISO 8601). Examples: 2024-01-31, 2024-01-31T23:59:59.999Z, 2024-01-31T23:59:59-05:00. If omitted, defaults to the current date." }, { "name": "user_ids", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "description": "Filter by specific user IDs" }, { "name": "disposition_ids", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "integer" } }, "description": "Filter by disposition IDs (1-14)" }, { "name": "timezone", "in": "query", "required": false, "schema": { "type": "string" }, "description": "IANA timezone for date calculations (e.g., America/New_York)" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "Page number" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "description": "Items per page" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search by list name" } ], "responses": { "200": { "description": "List performance retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListPerformanceResponse" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "summary": "List call performance by contact list" } }, "/v1/analytics/sdr-performance": { "get": { "tags": [ "Analytics" ], "description": "Returns call metrics grouped by SDR (user) with pagination", "operationId": "get-sdr-performance", "parameters": [ { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "Start date for the analytics period (ISO 8601). Examples: 2024-01-01, 2024-01-01T00:00:00.000Z, 2024-01-01T00:00:00-05:00. If omitted, defaults to 7 days before end_date." }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "End date for the analytics period (ISO 8601). Examples: 2024-01-31, 2024-01-31T23:59:59.999Z, 2024-01-31T23:59:59-05:00. If omitted, defaults to the current date." }, { "name": "user_ids", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "description": "Filter by specific user IDs" }, { "name": "disposition_ids", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "integer" } }, "description": "Filter by disposition IDs (1-14)" }, { "name": "timezone", "in": "query", "required": false, "schema": { "type": "string" }, "description": "IANA timezone for date calculations (e.g., America/New_York)" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "Page number" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "description": "Items per page" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search by SDR name or email" } ], "responses": { "200": { "description": "SDR performance retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SDRPerformanceResponse" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "summary": "List call performance by SDR" } }, "/v1/snoozed-contacts": { "get": { "tags": [ "Snoozed Contacts" ], "description": "Returns all snoozed contacts for the team with pagination and filtering", "operationId": "get-snoozed-contacts", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "Page number" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Items per page" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Sort field(s). Prefix with - for descending" }, { "name": "linkedin_username", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by LinkedIn username" }, { "name": "external_contact_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by external contact ID" }, { "name": "email", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by email" }, { "name": "phone_number", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by phone number" } ], "responses": { "200": { "description": "Snoozed contacts retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SnoozedContactsResponse" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "summary": "List snoozed contacts" } }, "/v1/snoozed-contacts/by-linkedin/{username}": { "get": { "tags": [ "Snoozed Contacts" ], "description": "Get a snoozed contact by LinkedIn username", "operationId": "get-snoozed-contact-by-linkedin", "parameters": [ { "name": "username", "in": "path", "required": true, "schema": { "type": "string" }, "description": "LinkedIn username" } ], "responses": { "200": { "description": "Snoozed contact retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SnoozedContactDTO" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Snoozed contact not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "summary": "Get a snoozed contact by LinkedIn username" } }, "/v1/snoozed-contacts/{id}": { "get": { "tags": [ "Snoozed Contacts" ], "description": "Get a snoozed contact by ID", "operationId": "get-snoozed-contact-by-id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Snoozed contact ID" } ], "responses": { "200": { "description": "Snoozed contact retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SnoozedContactDTO" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Snoozed contact not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "summary": "Get a snoozed contact" }, "put": { "tags": [ "Snoozed Contacts" ], "description": "Update a snoozed contact", "operationId": "update-snoozed-contact", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Snoozed contact ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSnoozedContactDTO" } } } }, "responses": { "200": { "description": "Snoozed contact updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SnoozedContactDTO" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Snoozed contact not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "summary": "Update a snoozed contact" }, "delete": { "tags": [ "Snoozed Contacts" ], "description": "Delete a snoozed contact", "operationId": "delete-snoozed-contact", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Snoozed contact ID" } ], "responses": { "200": { "description": "Snoozed contact deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Snoozed contact not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "summary": "Delete a snoozed contact" } }, "/v1/follow-up": { "get": { "tags": [ "Follow-up Tasks" ], "description": "Returns all follow-up tasks for the team with pagination", "operationId": "get-follow-ups", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "Page number" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Items per page" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Sort field(s). Prefix with - for descending" } ], "responses": { "200": { "description": "Follow-up tasks retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FollowUpResponse" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "summary": "List follow-up tasks" } }, "/v1/custom-fields": { "get": { "tags": [ "Custom Fields" ], "description": "Returns all custom field mappings configured for the team. Custom fields represent field mappings between Salesfinity and integrated CRM platforms.", "operationId": "get-custom-fields", "responses": { "200": { "description": "Custom fields retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CustomFieldsDTO" } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "summary": "List custom fields" } }, "/v1/call-log/{id}": { "get": { "tags": [ "Call Logs" ], "description": "Get a call log by ID", "operationId": "get-call-log-by-id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Call log ID" } ], "responses": { "200": { "description": "Call log retrieved successfully", "content": { "application/json": { "schema": { "type": "object" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Call log not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "summary": "Get a call log" } }, "/v1/scored-calls": { "get": { "tags": [ "Scored Calls" ], "description": "Retrieves a paginated list of AI-scored calls with detailed insights, scoring facets, lead qualification, and coaching recommendations.", "operationId": "get-scored-calls", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 }, "description": "Page number" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "description": "Items per page" }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Sort field(s). Prefix with - for descending. Default: -createdAt" }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Filter by start date (ISO 8601)" }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Filter by end date (ISO 8601)" }, { "name": "min_score", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0, "maximum": 100 }, "description": "Minimum total score" }, { "name": "max_score", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0, "maximum": 100 }, "description": "Maximum total score" }, { "name": "user_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter by user ID" } ], "responses": { "200": { "description": "Scored calls retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ScoredCallDTO" } }, "pagination": { "type": "object", "properties": { "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "pages": { "type": "integer" } } } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "summary": "List scored calls" } }, "/v1/scored-calls/{id}": { "get": { "tags": [ "Scored Calls" ], "description": "Retrieves a single scored call by its ID with full AI-generated insight.", "operationId": "get-scored-call-by-id", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Scored call ID" } ], "responses": { "200": { "description": "Scored call retrieved successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ScoredCallDTO" } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Scored call not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "summary": "Get a scored call" } }, "/v2/notes": { "post": { "tags": [ "Notes" ], "summary": "Create a note", "description": "Creates a note attached to a person (Contact) or company (Company), identified by domain identifiers rather than by list/contact IDs. For a person, supply at least one of linkedin_url, email, crm_id, or phone. For a company, supply at least one of website_url or name. If no matching record exists yet, a minimal Contact or Company is created on the fly and the note is attached to its stable ID.", "operationId": "create-note", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateNoteDTO" } } } }, "responses": { "201": { "description": "Note created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteDTO" } } } }, "400": { "description": "Validation failed (e.g. missing identifiers for the chosen type), or the user is not a member of the team. Check the request body and query parameters against the schema on this operation. `message` lists every field that failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": [ "limit must not be greater than 100" ], "error": "Bad Request", "statusCode": 400 } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "get": { "tags": [ "Notes" ], "summary": "List notes", "description": "Looks up the person or company by the provided identifiers and returns the notes attached to it. Resolve-only: returns 404 if no matching record exists (nothing is created on read). Notes are sorted pinned first, then by createdAt descending. For a person, supply at least one of linkedin_url, email, crm_id, or phone. For a company, supply at least one of website_url or name.", "operationId": "list-notes", "parameters": [ { "name": "type", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "person", "company" ] }, "description": "Target type. Determines which identifier fields are required." }, { "name": "linkedin_url", "in": "query", "required": false, "schema": { "type": "string" }, "description": "LinkedIn profile URL (person only)" }, { "name": "email", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Email address (person only)" }, { "name": "crm_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "External CRM identifier (person only)" }, { "name": "phone", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Phone number in E.164 format (person only)" }, { "name": "website_url", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Company website URL (company only)" }, { "name": "name", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Company name (company only)" } ], "responses": { "200": { "description": "Notes retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotesListResponseDTO" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "No matching person or company found. Check the path and any ID in it. A 404 also means the resource exists but is not owned by the team that the API key belongs to.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Cannot GET /v1/unknown-route", "error": "Not Found", "statusCode": 404 } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v2/notes/{id}": { "patch": { "tags": [ "Notes" ], "summary": "Update a note", "description": "Updates the content of an existing note. Only the original author may edit a note.", "operationId": "update-note", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Note ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateNoteDTO" } } } }, "responses": { "200": { "description": "Note updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteDTO" } } } }, "403": { "description": "Only the author can edit this note. Send a valid key in the `x-api-key` header. Salesfinity returns 403 (not 401) for a missing, malformed, revoked, or wrong-team key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Forbidden resource", "error": "Forbidden", "statusCode": 403 } } } }, "404": { "description": "Note not found. Check the path and any ID in it. A 404 also means the resource exists but is not owned by the team that the API key belongs to.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Cannot GET /v1/unknown-route", "error": "Not Found", "statusCode": 404 } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "tags": [ "Notes" ], "summary": "Delete a note", "description": "Deletes an existing note. Only the original author may delete a note.", "operationId": "delete-note", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Note ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteNoteDTO" } } } }, "responses": { "200": { "description": "Note deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } } } } } }, "403": { "description": "Only the author can delete this note. Send a valid key in the `x-api-key` header. Salesfinity returns 403 (not 401) for a missing, malformed, revoked, or wrong-team key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Forbidden resource", "error": "Forbidden", "statusCode": 403 } } } }, "404": { "description": "Note not found. Check the path and any ID in it. A 404 also means the resource exists but is not owned by the team that the API key belongs to.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Cannot GET /v1/unknown-route", "error": "Not Found", "statusCode": 404 } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v2/notes/{id}/pin": { "post": { "tags": [ "Notes" ], "summary": "Toggle a note pin", "description": "Toggles whether a note is pinned. Any team member may toggle a pin (not just the author). Pinned notes sort to the top.", "operationId": "pin-note", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Note ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PinNoteDTO" } } } }, "responses": { "201": { "description": "Pin toggled successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteDTO" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Note not found. Check the path and any ID in it. A 404 also means the resource exists but is not owned by the team that the API key belongs to.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Cannot GET /v1/unknown-route", "error": "Not Found", "statusCode": 404 } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/api/enrichment/email": { "post": { "tags": [ "Enrichment" ], "summary": "Start an email enrichment", "description": "Starts an asynchronous lookup of a work or personal email address for a LinkedIn profile. Returns immediately with a request `_id` and a `status` of `pending`; the result is delivered later either by polling `GET /v1/api/enrichment/email/{id}` or via the optional `callback_url` webhook. Each completed lookup costs 1 enrichment credit (charged only when an email is found). Requires a positive credit balance.", "operationId": "enrich-email", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrichEmailDTO" } } } }, "responses": { "201": { "description": "Enrichment request accepted. Poll the returned _id, or wait for the callback.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailEnrichmentRequestDTO" } } } }, "400": { "description": "Validation failed (e.g. linkedin_url is not a linkedin.com/in/ URL, or type is not work|personal). Check the request body and query parameters against the schema on this operation. `message` lists every field that failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": [ "limit must not be greater than 100" ], "error": "Bad Request", "statusCode": 400 } } } }, "402": { "description": "Insufficient enrichment credits. Top up to continue. The team has run out of enrichment credits. Top up in the dashboard, then retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Insufficient enrichment credits", "error": "Payment Required", "statusCode": 402 } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/api/enrichment/email/{id}": { "get": { "tags": [ "Enrichment" ], "summary": "Get an email enrichment result", "description": "Returns the current state of an email enrichment request. While the lookup is in progress `status` is `pending` or `processing`. When finished `status` is `completed` (with the found `email`) or `not-found` (no email available). Polling is a fallback for the callback and is safe to call repeatedly \u2014 a request is never charged twice.", "operationId": "get-email-enrichment", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The enrichment request _id returned by POST /v1/api/enrichment/email." } ], "responses": { "200": { "description": "Current state of the enrichment request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailEnrichmentRequestDTO" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "No enrichment request found for the given id. Check the path and any ID in it. A 404 also means the resource exists but is not owned by the team that the API key belongs to.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Cannot GET /v1/unknown-route", "error": "Not Found", "statusCode": 404 } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/api/enrichment/credits": { "get": { "tags": [ "Enrichment" ], "summary": "Get enrichment credit balance", "description": "Returns the current enrichment credit balance for the team that owns the API key. Each completed email enrichment costs 1 credit.", "operationId": "get-enrichment-credits", "responses": { "200": { "description": "Current credit balance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditBalanceDTO" } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } } }, "components": { "schemas": { "EnrichEmailDTO": { "type": "object", "required": [ "linkedin_url", "type" ], "properties": { "linkedin_url": { "type": "string", "description": "LinkedIn profile URL. Must be a linkedin.com/in/ URL.", "example": "https://www.linkedin.com/in/username" }, "type": { "type": "string", "enum": [ "work", "personal" ], "description": "Which email type to find." }, "callback_url": { "type": "string", "format": "uri", "description": "Optional. Webhook URL POSTed when the enrichment finishes. Retried up to 3 times.", "example": "https://example.com/webhooks/enrichment" }, "external_id": { "type": "string", "maxLength": 256, "description": "Optional. Echoed back in the callback payload for client-side correlation.", "example": "lead-42" } } }, "EmailEnrichmentRequestDTO": { "type": "object", "properties": { "_id": { "type": "string", "description": "Enrichment request ID. Use this to poll GET /v1/api/enrichment/email/{id}.", "example": "507f1f77bcf86cd799439011" }, "status": { "type": "string", "enum": [ "pending", "processing", "completed", "not-found", "failed" ], "description": "Current state of the request. `completed` means an email was found; `not-found` means none was available." }, "linkedin_url": { "type": "string", "example": "https://www.linkedin.com/in/username" }, "enrichment_type": { "type": "string", "enum": [ "work_email", "personal_email" ], "description": "Present once the lookup resolves. Reflects the requested email type." }, "email": { "type": "object", "nullable": true, "description": "Populated when status is `completed`. Null when status is `not-found`.", "properties": { "email": { "type": "string", "example": "john@acme.com" }, "type": { "type": "string", "example": "work" } } }, "external_id": { "type": "string", "description": "The external_id supplied on the original request, if any.", "example": "lead-42" } } }, "CreditBalanceDTO": { "type": "object", "required": [ "balance" ], "properties": { "balance": { "type": "integer", "description": "Number of enrichment credits remaining for the team.", "example": 250 } } }, "Error": { "type": "object", "title": "Error", "description": "The error envelope returned by every Salesfinity API error response. The shape is identical across all status codes and all endpoints.", "required": [ "message", "error", "statusCode" ], "properties": { "message": { "description": "Human-readable description of the failure. A string for most errors, and an array of strings when request validation fails, with one entry per field that did not validate.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "example": "Forbidden resource" }, "error": { "type": "string", "description": "Stable HTTP reason phrase for the status code. Branch on this rather than on `message`.", "example": "Forbidden" }, "statusCode": { "type": "integer", "format": "int32", "description": "HTTP status code, repeated in the body so it survives transports that drop it.", "example": 403 } }, "example": { "message": "Forbidden resource", "error": "Forbidden", "statusCode": 403 } }, "CSVListSummary": { "type": "object", "properties": { "_id": { "type": "string" }, "name": { "type": "string" }, "user": { "type": "string" }, "total_contacts": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "CSVListsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CSVListSummary" } }, "pagination": { "type": "object", "properties": { "total": { "type": "integer" }, "page": { "type": "integer" }, "next": { "type": "integer", "nullable": true } } } } }, "CSVContactObject": { "type": "object", "properties": { "_id": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "email": { "type": "string" }, "company": { "type": "string" }, "title": { "type": "string" }, "phone_numbers": { "type": "array", "items": { "$ref": "#/components/schemas/NumbersDTO" } }, "linkedin": { "type": "string" }, "website": { "type": "string" }, "notes": { "type": "string" }, "account": { "type": "string" }, "priority": { "type": "number" }, "timezone": { "type": "string" }, "custom_fields": { "type": "array", "items": { "$ref": "#/components/schemas/CustomFieldInputDTO" } } } }, "CSVListDetailResponse": { "type": "object", "properties": { "data": { "type": "object", "properties": { "_id": { "type": "string" }, "name": { "type": "string" }, "user": { "type": "string" }, "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/CSVContactObject" } } } }, "pagination": { "type": "object", "properties": { "total": { "type": "integer" }, "page": { "type": "integer" }, "next": { "type": "integer", "nullable": true } } } } }, "MergeContactListsDTO": { "type": "object", "required": [ "source_list_ids" ], "properties": { "source_list_ids": { "type": "array", "description": "IDs of the source lists to merge into the target list", "items": { "type": "string" }, "minItems": 1, "maxItems": 20, "example": [ "507f1f77bcf86cd799439011", "507f1f77bcf86cd799439012" ] }, "delete_sources": { "type": "boolean", "description": "Whether to delete the source lists after merging", "default": false } } }, "UserDTO": { "type": "object", "properties": { "_id": { "type": "string" }, "email": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" } }, "required": [ "_id", "email", "first_name", "last_name" ] }, "MemberDTO": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/UserDTO" }, "status": { "type": "string" }, "license": { "type": "string" } }, "required": [ "user", "status", "license" ] }, "GetTeamsResponseDTO": { "type": "object", "properties": { "_id": { "type": "string" }, "name": { "type": "string" }, "users": { "type": "array", "items": { "$ref": "#/components/schemas/MemberDTO" } } }, "required": [ "_id", "name", "users" ] }, "NumbersDTO": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "mobile", "direct", "office" ] }, "number": { "type": "string" }, "country_code": { "type": "string" }, "extension": { "type": "string" } }, "required": [ "type", "number" ] }, "ContactListContactDTO": { "type": "object", "properties": { "account": { "type": "string", "maxLength": 500, "description": "Account or organization identifier" }, "first_name": { "type": "string", "maxLength": 200, "description": "Contact first name" }, "last_name": { "type": "string", "maxLength": 200, "description": "Contact last name" }, "linkedin": { "type": "string", "maxLength": 500, "description": "LinkedIn profile URL" }, "email": { "type": "string", "maxLength": 320, "description": "Contact email address" }, "website": { "type": "string", "maxLength": 500, "description": "Website URL" }, "notes": { "type": "string", "maxLength": 2000, "description": "Free-text notes about the contact" }, "phone_numbers": { "type": "array", "items": { "$ref": "#/components/schemas/NumbersDTO" }, "maxItems": 10, "description": "Phone numbers (max 10 per contact)" }, "company": { "type": "string", "maxLength": 300, "description": "Company name" }, "title": { "type": "string", "maxLength": 300, "description": "Job title" }, "priority": { "type": "number", "description": "Contact priority (lower is higher priority)" }, "timezone": { "type": "string", "maxLength": 100, "description": "IANA timezone identifier (e.g. America/New_York)" }, "external_relations": { "type": "object", "description": "External system references (e.g. CRM IDs)" }, "custom_fields": { "type": "array", "items": { "$ref": "#/components/schemas/CustomFieldInputDTO" }, "maxItems": 10, "description": "Custom fields (max 10 per contact)" } } }, "CustomFieldInputDTO": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "string", "number", "boolean" ], "description": "Field data type" }, "label": { "type": "string", "maxLength": 100, "description": "Display label for the field" }, "value": { "description": "Field value (string, number, boolean, or string array)" } }, "required": [ "type", "label" ] }, "CreateContactListDTO": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Name of the contact list" }, "user_id": { "type": "string", "description": "ID of the team member who owns this list" }, "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/ContactListContactDTO" }, "maxItems": 2000, "description": "Array of contacts (optional, max 2,000)" } }, "required": [ "name", "user_id" ] }, "DispositionDTO": { "type": "object", "properties": { "_id": { "type": "string", "description": "Unique identifier" }, "id": { "type": "integer", "description": "Disposition ID" }, "name": { "type": "string", "description": "Human-readable disposition name" }, "is_custom": { "type": "boolean", "description": "Whether this is a custom disposition" }, "is_required": { "type": "boolean", "description": "Whether this disposition is required" }, "category": { "type": "string", "enum": [ "positive", "negative", "neutral", "not_answered", "cancelled" ], "description": "Disposition category" } }, "required": [ "_id", "id", "name", "is_custom", "category" ] }, "SequenceDTO": { "type": "object", "properties": { "id": { "type": "string", "description": "Sequence ID from external integration" }, "name": { "type": "string", "description": "Sequence name" }, "last_used_at": { "type": "string", "format": "date-time", "description": "Most recent call date in this sequence" }, "first_used_at": { "type": "string", "format": "date-time", "description": "First call date in this sequence" }, "total_calls": { "type": "integer", "description": "Total calls made within this sequence" } }, "required": [ "id", "name", "total_calls" ] }, "MetricWithGrowth": { "type": "object", "properties": { "value": { "type": "number" }, "growth_rate": { "type": "number", "description": "Percentage change compared to the previous period of equal length" } }, "required": [ "value", "growth_rate" ] }, "AnalyticsOverviewResponse": { "type": "object", "properties": { "total_calls": { "$ref": "#/components/schemas/MetricWithGrowth" }, "total_inbound_calls": { "$ref": "#/components/schemas/MetricWithGrowth" }, "connected_calls": { "$ref": "#/components/schemas/MetricWithGrowth" }, "conversations": { "$ref": "#/components/schemas/MetricWithGrowth" }, "connection_rate": { "$ref": "#/components/schemas/MetricWithGrowth" }, "conversation_rate": { "$ref": "#/components/schemas/MetricWithGrowth" }, "avg_calls_per_day": { "$ref": "#/components/schemas/MetricWithGrowth" }, "total_call_duration": { "$ref": "#/components/schemas/MetricWithGrowth" }, "total_meetings_set": { "$ref": "#/components/schemas/MetricWithGrowth" }, "total_follow_up_tasks": { "$ref": "#/components/schemas/MetricWithGrowth" }, "unique_contacts": { "$ref": "#/components/schemas/MetricWithGrowth" }, "unique_companies": { "$ref": "#/components/schemas/MetricWithGrowth" } }, "required": [ "total_calls", "total_inbound_calls", "connected_calls", "conversations", "connection_rate", "conversation_rate", "avg_calls_per_day", "total_call_duration", "total_meetings_set", "total_follow_up_tasks", "unique_contacts", "unique_companies" ] }, "ListOwner": { "type": "object", "properties": { "_id": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "email": { "type": "string" } } }, "ListPerformanceItem": { "type": "object", "properties": { "_id": { "type": "string" }, "name": { "type": "string" }, "source": { "type": "string" }, "total_calls": { "type": "integer" }, "connected_calls": { "type": "integer" }, "conversations": { "type": "integer" }, "meetings_set": { "type": "integer" }, "good_quality_contacts": { "type": "integer" }, "data_quality": { "type": "number" }, "owner": { "$ref": "#/components/schemas/ListOwner" } } }, "ListPerformanceResponse": { "type": "object", "properties": { "totalCount": { "type": "integer" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ListPerformanceItem" } }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "next": { "type": "integer", "nullable": true }, "prev": { "type": "integer", "nullable": true } }, "required": [ "totalCount", "data", "page", "limit" ] }, "SDRPerformanceItem": { "type": "object", "properties": { "_id": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "email": { "type": "string" }, "image": { "type": "string" }, "total_calls": { "type": "integer" }, "connected_calls": { "type": "integer" }, "connection_rate": { "type": "number" }, "conversations": { "type": "integer" }, "conversation_rate": { "type": "number" }, "avg_dials_day": { "type": "number" }, "total_duration": { "type": "integer" }, "meetings_set": { "type": "integer" }, "data_quality": { "type": "number" } } }, "SDRPerformanceResponse": { "type": "object", "properties": { "totalCount": { "type": "integer" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/SDRPerformanceItem" } }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "next": { "type": "integer", "nullable": true }, "prev": { "type": "integer", "nullable": true } }, "required": [ "totalCount", "data", "page", "limit" ] }, "ContactListDTO": { "type": "object", "properties": { "_id": { "type": "string", "description": "Unique identifier" }, "name": { "type": "string", "description": "Contact list name" }, "source": { "type": "string", "enum": [ "csv", "hubspot", "salesforce", "manual" ], "description": "List source" }, "user": { "$ref": "#/components/schemas/UserDTO" }, "total_contacts": { "type": "integer", "description": "Number of contacts" } }, "required": [ "_id", "name", "source" ] }, "ContactListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ContactListDTO" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "next": { "type": "integer", "nullable": true } } }, "SnoozedContactDTO": { "type": "object", "properties": { "_id": { "type": "string", "description": "Unique identifier" }, "team": { "type": "string", "description": "Team ID" }, "user": { "$ref": "#/components/schemas/UserDTO" }, "contact_list": { "type": "string", "description": "Contact list ID" }, "linkedin_username": { "type": "string", "description": "LinkedIn username" }, "external_contact_id": { "type": "string", "description": "External CRM contact ID" }, "email": { "type": "string", "description": "Email address" }, "phone_number": { "type": "string", "description": "Phone number" }, "snooze_until": { "type": "string", "format": "date-time", "description": "Snooze expiration date" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "_id", "team", "phone_number", "snooze_until" ] }, "SnoozedContactsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SnoozedContactDTO" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "next": { "type": "integer", "nullable": true } } }, "UpdateSnoozedContactDTO": { "type": "object", "properties": { "linkedin_username": { "type": "string", "description": "LinkedIn username" }, "external_contact_id": { "type": "string", "description": "External CRM contact ID" }, "email": { "type": "string", "description": "Email address" }, "phone_number": { "type": "string", "description": "Phone number" }, "snooze_until": { "type": "string", "format": "date-time", "description": "New snooze expiration date" } } }, "FollowUpTaskDTO": { "type": "object", "properties": { "_id": { "type": "string", "description": "Unique identifier" }, "team": { "type": "string", "description": "Team ID" }, "user": { "$ref": "#/components/schemas/UserDTO" }, "call_log": { "type": "string", "description": "Associated call log ID" }, "contact": { "type": "string", "description": "Contact ID" }, "company": { "type": "string", "description": "Company ID" }, "priority": { "type": "string", "enum": [ "high", "medium", "low" ], "description": "Task priority" }, "status": { "type": "string", "enum": [ "not_overdue", "overdue", "completed" ], "description": "Task status" }, "follow_up_date": { "type": "string", "format": "date-time", "description": "Scheduled follow-up date" }, "first_name": { "type": "string", "description": "Contact first name" }, "last_name": { "type": "string", "description": "Contact last name" }, "tags": { "type": "array", "items": { "type": "string", "enum": [ "timing", "budget", "competitor" ] }, "description": "Task tags" }, "touches": { "type": "integer", "description": "Number of contact attempts" }, "context": { "type": "string", "description": "Additional context" }, "is_archived": { "type": "boolean", "description": "Whether task is archived" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "_id", "team", "priority", "status", "follow_up_date" ] }, "FollowUpResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FollowUpTaskDTO" } }, "total": { "type": "integer" }, "page": { "type": "integer" }, "next": { "type": "integer", "nullable": true } } }, "CustomFieldDTO": { "type": "object", "properties": { "type": { "type": "string", "description": "Field category" }, "field_type": { "type": "string", "description": "Data type of the field" }, "internal_name": { "type": "string", "description": "Salesfinity field name" }, "external_key": { "type": "string", "description": "CRM field key" }, "external_name": { "type": "string", "description": "CRM field display name" } } }, "CustomFieldsDTO": { "type": "object", "properties": { "_id": { "type": "string", "description": "Unique identifier" }, "source": { "type": "string", "enum": [ "csv", "salesforce", "salesloft", "outreach", "apollo", "hubspot", "active-campaign", "custom", "pipe-drive", "monday" ], "description": "Integration source" }, "team": { "type": "string", "description": "Team ID" }, "user": { "type": "string", "description": "User ID" }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/CustomFieldDTO" }, "description": "Contact field mappings" }, "lead_fields": { "type": "array", "items": { "$ref": "#/components/schemas/CustomFieldDTO" }, "description": "Lead field mappings" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "_id", "source", "team" ] }, "ScoredCallDTO": { "type": "object", "properties": { "_id": { "type": "string", "description": "Unique identifier" }, "insight": { "type": "object", "description": "Full scoring insight", "properties": { "total_score": { "type": "number", "description": "Overall call score (0-100)" }, "lead": { "type": "object", "properties": { "function": { "type": "string" }, "tech_stack_mentioned": { "type": "array", "items": { "type": "string" } }, "current_vendor": { "type": "string" }, "fit_score": { "type": "number" }, "is_decision_maker": { "type": "boolean" }, "is_correct_persona": { "type": "boolean" }, "pain_point_resonated": { "type": "boolean" }, "is_qualified_meeting": { "type": "boolean" }, "is_likely_to_buy": { "type": "boolean" }, "prospect_lifecycle_stage": { "type": "array", "items": { "type": "string" } } } }, "messaging": { "type": "object", "properties": { "value_prop_resonated": { "type": "array", "items": { "type": "string" } }, "objection_outcome": { "type": "array", "items": { "type": "string" } }, "emotional_triggers": { "type": "array", "items": { "type": "string" } }, "recommendation_to_nail_messaging": { "type": "string" } } }, "targeting_feedback": { "type": "object", "properties": { "persona_fit": { "type": "string" }, "industry_fit": { "type": "string" }, "persona_seniority": { "type": "string" }, "title_relevance": { "type": "string" }, "data_quality_issue": { "type": "array", "items": { "type": "string" } }, "future_follow_up_needed": { "type": "boolean" }, "follow_up_reason": { "type": "array", "items": { "type": "string" } } } }, "metadata": { "type": "object", "properties": { "duration_sec": { "type": "number" }, "asr_confidence_avg": { "type": "number" }, "audio_features_available": { "type": "boolean" }, "talk_listen_ratio_rep": { "type": "number" }, "total_questions": { "type": "integer" }, "open_question_ratio": { "type": "number" }, "interruptions_by_rep": { "type": "integer" }, "core_pitch_duration_sec": { "type": "number" }, "estimated_wpm_rep": { "type": "number" }, "objections_detected": { "type": "array", "items": { "type": "string" } } } }, "facets": { "type": "object", "properties": { "intro": { "$ref": "#/components/schemas/ScoringFacet" }, "discovery": { "$ref": "#/components/schemas/ScoringFacet" }, "pitch": { "$ref": "#/components/schemas/ScoringFacet" }, "tonality": { "$ref": "#/components/schemas/ScoringFacet" }, "objection_handling": { "$ref": "#/components/schemas/ScoringFacet" }, "cta": { "$ref": "#/components/schemas/ScoringFacet" } } }, "gaps": { "type": "object", "properties": { "skill": { "type": "number" }, "playbook": { "type": "number" }, "rationale": { "type": "string" } } }, "coaching": { "type": "object", "properties": { "top_wins": { "type": "array", "items": { "type": "string" } }, "top_opportunities": { "type": "array", "items": { "type": "string" } }, "suggested_drills": { "type": "array", "items": { "type": "object", "properties": { "facet": { "type": "string" }, "assignment": { "type": "string" } } } } } } } }, "call_log": { "type": "object", "properties": { "_id": { "type": "string" }, "contact": { "type": "object" }, "recording_url": { "type": "string" }, "duration": { "type": "number" } } }, "user": { "$ref": "#/components/schemas/UserDTO" }, "type": { "type": "string", "enum": [ "call" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "_id", "insight", "type" ] }, "ScoringFacet": { "type": "object", "properties": { "score": { "type": "number", "description": "Facet score (0-100)" }, "weight_pct": { "type": "number", "description": "Weight percentage of this facet" }, "explanation": { "type": "string", "description": "Human-readable explanation" }, "insufficient_evidence": { "type": "boolean" }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "start_sec": { "type": "number" }, "end_sec": { "type": "number" }, "text": { "type": "string" } } } } } }, "CallLogDTO": { "type": "object", "properties": { "_id": { "type": "string" }, "call_id": { "type": "string" }, "outcome": { "type": "string", "enum": [ "answered", "no-answer", "cancelled" ] }, "direction": { "type": "string", "enum": [ "inbound", "outbound" ] }, "answered_by": { "type": "string", "enum": [ "human", "machine_start" ] }, "duration": { "type": "number", "description": "Call duration in seconds" }, "to": { "type": "string", "description": "Called phone number" }, "from": { "type": "string", "description": "Caller phone number" }, "disposition": { "type": "object", "properties": { "internal_id": { "type": "integer" }, "external_id": { "type": "string" }, "external_name": { "type": "string" } } }, "contact": { "type": "object" }, "contact_list": { "type": "object", "description": "The dialing-queue list (ContactList) the call was placed from. Its _id is the queue id. Unchanged for backward compatibility." }, "source": { "type": "object", "description": "The original source list the call came from. Additive; contact_list is left untouched.", "properties": { "type": { "type": "string", "description": "Integration source type (e.g. csv, hubspot, salesforce). Null if unknown.", "nullable": true }, "id": { "type": "string", "description": "The original source list id. For CSV lists this is the CSV list id (CsvContacts._id). Null for non-CSV lists (no external list id is stored).", "nullable": true }, "name": { "type": "string", "description": "The source list name. Null when unresolved.", "nullable": true } } }, "user": { "$ref": "#/components/schemas/UserDTO" }, "recording_url": { "type": "string" }, "notes": { "type": "string" }, "transcription": { "type": "string" }, "summary": { "type": "string" }, "is_completed": { "type": "boolean" }, "started_at": { "type": "string", "format": "date-time" }, "ended_at": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "CallLogListResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CallLogDTO" } }, "pagination": { "type": "object", "properties": { "total": { "type": "integer" }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "pages": { "type": "integer" } } } } }, "NoteAuthorDTO": { "type": "object", "properties": { "_id": { "type": "string", "example": "507f1f77bcf86cd799439011" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "email": { "type": "string" }, "image": { "type": "string" } } }, "NoteDTO": { "type": "object", "properties": { "_id": { "type": "string", "example": "507f1f77bcf86cd799439011" }, "team": { "type": "string", "example": "507f1f77bcf86cd799439012" }, "author": { "allOf": [ { "$ref": "#/components/schemas/NoteAuthorDTO" } ], "description": "Note author. Populated when available; otherwise just the user ID under _id." }, "content": { "type": "string", "description": "Plain text content of the note" }, "is_pinned": { "type": "boolean", "description": "Whether this note is pinned to the top" }, "pinned_at": { "type": "string", "format": "date-time", "nullable": true }, "pinned_by": { "type": "string", "nullable": true }, "contact": { "type": "string", "nullable": true, "description": "Contact this note is attached to (mutually exclusive with company)" }, "company": { "type": "string", "nullable": true, "description": "Company this note is attached to (mutually exclusive with contact)" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "NotesListResponseDTO": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "person", "company" ], "description": "Target type echoed from the request" }, "contact_id": { "type": "string", "nullable": true, "example": "507f1f77bcf86cd799439011", "description": "Resolved unified Contact ID (present when type=person). Stable across reimports and dialer drains." }, "company_id": { "type": "string", "nullable": true, "example": "507f1f77bcf86cd799439012", "description": "Resolved unified Company ID (present when type=company)." }, "notes": { "type": "array", "description": "Notes attached to the resolved target, pinned first then by creation date descending", "items": { "$ref": "#/components/schemas/NoteDTO" } } } }, "CreateNoteDTO": { "type": "object", "required": [ "type", "user_id", "content" ], "properties": { "type": { "type": "string", "enum": [ "person", "company" ], "example": "person", "description": "Target type. Determines which identifier fields are required." }, "user_id": { "type": "string", "description": "ID of the team member authoring the note. Must be a member of the team that owns the API key.", "example": "507f1f77bcf86cd799439011" }, "content": { "type": "string", "maxLength": 10000, "description": "Plain text content of the note", "example": "Mentioned moving back from Lisbon next quarter." }, "linkedin_url": { "type": "string", "maxLength": 500, "example": "https://linkedin.com/in/johndoe", "description": "LinkedIn profile URL (person only). Username is extracted automatically. Person notes require at least one of linkedin_url, email, crm_id, or phone." }, "email": { "type": "string", "format": "email", "maxLength": 320, "example": "john@example.com", "description": "Email address (person only)" }, "crm_id": { "type": "string", "maxLength": 200, "example": "salesforce:003XXX", "description": "External CRM identifier (person only)" }, "phone": { "type": "string", "maxLength": 50, "example": "+14155552671", "description": "Phone number in E.164 format (person only)" }, "company_name": { "type": "string", "maxLength": 300, "example": "Acme Corp", "description": "Company name to link to the person if a new Contact is created. Ignored if the person already exists. (person only)" }, "company_website": { "type": "string", "maxLength": 500, "example": "https://acme.com", "description": "Company website to link to the person if a new Contact is created. Ignored if the person already exists. (person only)" }, "website_url": { "type": "string", "maxLength": 500, "example": "https://acme.com", "description": "Company website URL (company only). Normalized to hostname for matching. Company notes require at least one of website_url or name." }, "name": { "type": "string", "maxLength": 300, "example": "Acme Corp", "description": "Company name (company only). Case-insensitive match against the company name list." } } }, "UpdateNoteDTO": { "type": "object", "required": [ "content", "user_id" ], "properties": { "content": { "type": "string", "maxLength": 10000, "description": "Updated plain text content of the note", "example": "Updated note content" }, "user_id": { "type": "string", "description": "ID of the team member performing the update. Must match the original author of the note.", "example": "507f1f77bcf86cd799439011" } } }, "DeleteNoteDTO": { "type": "object", "required": [ "user_id" ], "properties": { "user_id": { "type": "string", "description": "ID of the team member performing the delete. Must match the original author of the note.", "example": "507f1f77bcf86cd799439011" } } }, "PinNoteDTO": { "type": "object", "required": [ "user_id" ], "properties": { "user_id": { "type": "string", "description": "ID of the team member toggling the pin. Must be a member of the team that owns the API key.", "example": "507f1f77bcf86cd799439011" } } }, "ObjectId": { "type": "string", "title": "ObjectId", "description": "A 24-character hexadecimal identifier for a Salesfinity resource. Returned on its own by endpoints whose only result is the id of the record they created or affected.", "pattern": "^[0-9a-fA-F]{24}$", "example": "507f1f77bcf86cd799439011" } }, "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Team-scoped API key generated in the Salesfinity dashboard under Settings -> Connections & API. A missing or invalid key returns HTTP 403." } }, "responses": { "Forbidden": { "description": "Forbidden. The `x-api-key` header is missing, malformed, revoked, or belongs to another team. Send a valid key in the `x-api-key` header. Salesfinity returns 403 (not 401) for a missing, malformed, revoked, or wrong-team key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Forbidden resource", "error": "Forbidden", "statusCode": 403 } } } }, "TooManyRequests": { "description": "Too Many Requests. The client is being throttled and should retry with backoff. Back off and retry with exponential jitter. Treat 429 as retryable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Too many requests", "error": "Too Many Requests", "statusCode": 429 } } } }, "InternalServerError": { "description": "Internal Server Error. Something went wrong on the Salesfinity side. Retry with exponential backoff. If it persists, contact hello@salesfinity.co with the request path and timestamp.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "message": "Internal server error", "error": "Internal Server Error", "statusCode": 500 } } } } } }, "externalDocs": { "description": "Salesfinity API documentation", "url": "https://docs.salesfinity.ai" }, "tags": [ { "name": "Contact Lists", "description": "Create, read, merge, and delete CSV contact lists, and add or remove the contacts inside them." }, { "name": "Teams", "description": "Read the team that owns the API key, including its members, licenses, and statuses." }, { "name": "Dispositions", "description": "Read the default and custom call outcomes configured for the team." }, { "name": "Sequences", "description": "Read the sequences referenced by the team's call logs." }, { "name": "Call Logs", "description": "Read the raw call history for the team, with filtering, sorting, and pagination." }, { "name": "Analytics", "description": "Aggregated call metrics for the team, by contact list, and by SDR." }, { "name": "Snoozed Contacts", "description": "Read and manage contacts that have been snoozed out of the dialing queue." }, { "name": "Follow-up Tasks", "description": "Read follow-up tasks created from call outcomes." }, { "name": "Custom Fields", "description": "Read the custom field mappings configured for the team." }, { "name": "Scored Calls", "description": "Read AI-scored calls with per-facet scoring and coaching recommendations." }, { "name": "Notes", "description": "Attach freeform notes to a person or company, list them, and pin the ones that matter." }, { "name": "Enrichment", "description": "Look up work or personal email addresses and check the team's remaining enrichment credits." } ] }