{ "openapi": "3.0.0", "info": { "title": "ProspectSafari V1", "description": "Everything you can do in ProspectSafari with companies, contacts, deals and their timelines, as JSON over HTTPS.\n\n## Getting started\n1. Create an API key on the Integrations page of ProspectSafari. You get a key and a secret; the secret is shown once, so store it.\n2. Send both on every call, as the headers `X-API-Key` and `X-API-Secret`. To try the endpoints in a browser, open `https://app.prospectsafari.com/api/documentation`, press **Authorize** and paste both.\n3. Send and receive JSON (`Content-Type: application/json`). Every address starts with `https://app.prospectsafari.com/api/v1`.\n\nThe API acts as the user who owns the key: it sees the records that user sees and can only send email from the mailboxes of that user. A key which was deactivated on the Integrations page gets a 401.\n\n## Ids\nEvery record has a numeric `id`. The lookups (Lists, Team Members, Task Queues, Deal Pipelines with their stages, Checklists, Documents, Quizzes, Email Templates, Custom Fields, Sending Addresses, Message Types) give you the ids the other endpoints ask for.\n\n## Lists and paging\nEvery list answers `{ data: [...], pagination: { page, per_page, total, total_pages } }`, oldest record first. `per_page` is 25 by default and 100 at most. Each list has its own filters, see the parameters of the endpoint.\n\n## Writing\n- Create with POST, change with PUT. An update only changes the fields you send, everything else keeps its value.\n- Only the fields on the input schema are read, unknown fields are ignored.\n- Dates are ISO 8601. What comes back is UTC, like `2024-04-29T10:00:00Z`. `founded` and `last_funding` are plain dates (`YYYY-MM-DD`); a bare year or a year-month is read as the 1st of that January / month.\n- HTML you send (notes, emails, templates...) is cleaned before it is stored: scripts, forms and event handlers are removed.\n- Custom fields go in and out as `custom_fields: [{ custom_field: , value: ... }]`, the ids come from `GET /custom_fields`.\n- A list that belongs to a record (the stages of a pipeline, the steps of a checklist, the questions of a quiz, the emails of a sequence) is replaced as a whole when you send it. Send a stage, step or question back with its `id` to keep it.\n- A PDF document is uploaded as `multipart/form-data` (`POST /documents`, `POST /documents/{id}/pdf`); everything else is JSON.\n- Changing a checklist, or the checklist of a pipeline stage, re-checks the deals which use it in the background: their tasks are created or removed a few moments after the call answers.\n\n## What leaves ProspectSafari\nOnly `POST /timeline_items/emails` reaches somebody outside: it sends (or schedules) a real email from a mailbox of the key owner. Logged messages and meetings are records only: no SMS, no calendar invitation, nothing is sent to the contact. The `url` of a public document opens for anyone you give it to; a private document only opens for a logged-in member of the workspace.\n\n## Errors\nEvery error answers `{ message }`, a 422 adds `errors: { field: [...] }`.\n- 401: the key or secret is wrong, or the key was deactivated\n- 403: the key owner is not allowed to do this\n- 404: no such endpoint, or the id does not belong to your workspace\n- 409: conflict, e.g. a company with that website or a contact with that email already exists, the meeting is synced with a calendar, or a pipeline stage you want to remove still has deals\n- 422: the input is not valid, `errors` says which field and why\n- 429: too many requests, wait the number of seconds in the `Retry-After` header\n\n## Limits\n300 requests per minute and 100 emails per hour, per API key.\n\n## Webhooks\nOn the Integrations page you can set a URL. ProspectSafari POSTs to it when a contact or company is updated or deleted; the payload is described under Webhooks below.", "contact": { "email": "simone@prospectsafari.com" }, "license": { "name": "Proprietary License", "url": "" }, "version": "1.4.0" }, "paths": { "/api/v1/checklists": { "get": { "tags": [ "Checklist" ], "summary": "List all checklists", "description": "Lists the checklists of the workspace together with their steps. A deal stage points to its checklist with checklist_id (see deal pipelines). To work through the checklist of a deal use the checklist endpoints of the deal.", "operationId": "listChecklists", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Checklist" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "type": "object" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid page or per_page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] }, "post": { "tags": [ "Checklist" ], "summary": "Create a new checklist", "description": "Creates a checklist with its steps. It does nothing until a deal stage uses it: set checklist_id on a stage with PUT /deal_pipelines/{id}. Only admins of the workspace can create checklists, and the plan of the workspace must include the full sales coach.", "operationId": "createChecklist", "requestBody": { "description": "Checklist data", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChecklistInput" } } } }, "responses": { "200": { "description": "Checklist created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Checklist" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The owner of the API key is not an admin, or the plan doesn't include checklists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] } }, "/api/v1/checklists/{id}": { "get": { "tags": [ "Checklist" ], "summary": "Get a single checklist", "description": "Returns one checklist definition with its steps. 404 when the id is not a checklist of your workspace. To tick steps off use the checklist endpoints of the deal.", "operationId": "getChecklist", "parameters": [ { "name": "id", "in": "path", "description": "ID of the checklist to retrieve", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Checklist retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Checklist" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Checklist not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] }, "put": { "tags": [ "Checklist" ], "summary": "Update an existing checklist", "description": "Only the fields you send are changed. If you send checklist_steps, that list replaces all the steps: keep a step by sending its id (its fields you leave out keep their value), add one by leaving id out, delete one by leaving it out of the list. Saving re-checks, in the background, every deal sitting in a stage that uses the checklist: tasks of new steps are created and tasks of deleted steps are removed, as when the checklist is saved in ProspectSafari. To change many steps, send them all in one call rather than one call per step. Only admins of the workspace can change checklists.", "operationId": "updateChecklist", "parameters": [ { "name": "id", "in": "path", "description": "Checklist ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "description": "Checklist data to update", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChecklistInput" } } } }, "responses": { "200": { "description": "Checklist updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Checklist" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The owner of the API key is not an admin, or the checklist is disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Checklist not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] }, "delete": { "tags": [ "Checklist" ], "summary": "Delete a checklist", "description": "Deletes the checklist. The stages which used it are left without a checklist, and the open (not completed) tasks it created on deals are deleted. Completed tasks stay. Only admins of the workspace can delete checklists. This can't be undone through the API.", "operationId": "deleteChecklist", "parameters": [ { "name": "id", "in": "path", "description": "ID of the checklist to delete", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Checklist deleted successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Checklist deleted successfully" }, "id": { "description": "ID of the deleted checklist", "type": "integer", "example": 4 } }, "type": "object" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The owner of the API key is not an admin of the workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Checklist not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] } }, "/api/v1/checklists/{id}/steps": { "get": { "tags": [ "Checklist" ], "summary": "List the steps of a checklist", "description": "Lists the steps of one checklist, in order. The same steps come with the checklist itself (GET /checklists/{id}).", "operationId": "listChecklistSteps", "parameters": [ { "name": "id", "in": "path", "description": "ID of the checklist", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ChecklistStep" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "type": "object" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Checklist not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid page or per_page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] }, "post": { "tags": [ "Checklist" ], "summary": "Add a step to a checklist", "description": "Adds one step, last or at the position in order. text and type are required, a step without priority / due_date / task_owner gets 1 (Medium) / 3 (3 days) / CURRENT_USER. Like any change to a checklist this re-checks, in the background, every deal in a stage that uses it. Only admins of the workspace can change checklists.", "operationId": "createChecklistStep", "parameters": [ { "name": "id", "in": "path", "description": "ID of the checklist", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "description": "Step data", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChecklistStepInput" } } } }, "responses": { "200": { "description": "Checklist step created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChecklistStep" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The owner of the API key is not an admin, or the checklist is disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Checklist not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] } }, "/api/v1/checklists/{id}/steps/{step_id}": { "get": { "tags": [ "Checklist" ], "summary": "Get a single step of a checklist", "description": "Returns one step. 404 when the checklist is not in your workspace or the step is not one of its steps.", "operationId": "getChecklistStep", "parameters": [ { "name": "id", "in": "path", "description": "ID of the checklist", "required": true, "schema": { "type": "integer" } }, { "name": "step_id", "in": "path", "description": "ID of the step", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Checklist step retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChecklistStep" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Checklist or step not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] }, "put": { "tags": [ "Checklist" ], "summary": "Update a step of a checklist", "description": "Only the fields you send are changed; send order to move the step. If you send conditions, that list replaces the current conditions of the step. Like any change to a checklist this re-checks, in the background, every deal in a stage that uses it. Only admins of the workspace can change checklists.", "operationId": "updateChecklistStep", "parameters": [ { "name": "id", "in": "path", "description": "ID of the checklist", "required": true, "schema": { "type": "integer" } }, { "name": "step_id", "in": "path", "description": "ID of the step", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "description": "Step data to update", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChecklistStepInput" } } } }, "responses": { "200": { "description": "Checklist step updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChecklistStep" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The owner of the API key is not an admin, or the checklist is disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Checklist or step not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] }, "delete": { "tags": [ "Checklist" ], "summary": "Delete a step of a checklist", "description": "Deletes one step. A checklist keeps at least one step: to remove the last one delete the checklist. The background re-check removes the open tasks the step created on deals. Only admins of the workspace can change checklists.", "operationId": "deleteChecklistStep", "parameters": [ { "name": "id", "in": "path", "description": "ID of the checklist", "required": true, "schema": { "type": "integer" } }, { "name": "step_id", "in": "path", "description": "ID of the step to delete", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Checklist step deleted successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Checklist step deleted successfully" }, "id": { "description": "ID of the deleted step", "type": "integer", "example": 7 } }, "type": "object" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The owner of the API key is not an admin, or the checklist is disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Checklist or step not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "It is the last step of the checklist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "The checklist has no description yet, set one first with PUT /checklists/{id}", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] } }, "/api/v1/companies": { "get": { "tags": [ "Company" ], "summary": "List all companies", "description": "Lists the companies of the workspace, oldest first. Use the filters to narrow the list down and page + per_page to walk through it.", "operationId": "listCompanies", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "name": "list_id", "in": "query", "description": "Only companies in this list", "required": false, "schema": { "type": "integer" } }, { "name": "name", "in": "query", "description": "Only companies whose name contains this text. Useful to check if a company already exists.", "required": false, "schema": { "type": "string" } }, { "name": "user_workspace_id", "in": "query", "description": "Only companies owned by this team member", "required": false, "schema": { "type": "integer" } }, { "name": "status", "in": "query", "description": "Only companies with this status", "required": false, "schema": { "$ref": "#/components/schemas/status_options" } }, { "name": "updated_since", "in": "query", "description": "Only companies updated at or after this moment. Useful to sync changes.", "required": false, "schema": { "type": "string", "format": "date-time", "example": "2024-04-29T10:00:00Z" } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Company" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "type": "object" } } } }, "401": { "description": "Unauthorised" }, "422": { "description": "Invalid filter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] }, "post": { "tags": [ "Company" ], "summary": "Create a new company", "description": "Creates a company in your workspace. Send list_id or list_name to say which list it goes on (a list_name which doesn't exist yet is created); without either it goes on the default list of the key owner. When a company with the same website already exists nothing is created and you get a 409 which names that company.", "operationId": "createCompany", "requestBody": { "description": "Company data", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyInput" } } } }, "responses": { "200": { "description": "Company created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" } } } }, "401": { "description": "Unauthorised" }, "409": { "description": "Conflict with existing company", "content": { "application/json": { "schema": { "properties": { "company": { "$ref": "#/components/schemas/Company" }, "message": { "description": "conflict error message", "type": "string", "example": "Conflict: the website https://www.samplecompany.com already exists on another company" } }, "type": "object" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] } }, "/api/v1/companies/{id}": { "get": { "tags": [ "Company" ], "summary": "Get a single company", "description": "Retrieves a single company by its unique ID", "operationId": "getCompany", "parameters": [ { "name": "id", "in": "path", "description": "ID of the company to retrieve", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Company retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" } } } }, "401": { "description": "Unauthorised" }, "404": { "description": "Company not found" }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] }, "put": { "tags": [ "Company" ], "summary": "Update an existing company", "description": "Only the fields you send are changed, every other field keeps its current value (on update name is not required). The company only moves to another list if you send list_id or list_name.", "operationId": "updateCompany", "parameters": [ { "name": "id", "in": "path", "description": "Company ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "description": "Company data to update", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyInput" } } } }, "responses": { "200": { "description": "Company updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" } } } }, "401": { "description": "Unauthorised" }, "403": { "description": "The owner of the API key is not allowed to edit this company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Company not found" }, "409": { "description": "Conflict with existing company", "content": { "application/json": { "schema": { "properties": { "company": { "$ref": "#/components/schemas/Company" }, "message": { "description": "conflict error message", "type": "string", "example": "Conflict: the website https://www.samplecompany.com already exists on another company" } }, "type": "object" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] }, "delete": { "tags": [ "Company" ], "summary": "Delete a company", "description": "Permanently deletes the company together with its tasks. Contacts which only belong to this company are deleted too, contacts which also belong to another company are only disconnected. This can't be undone.", "operationId": "deleteCompany", "parameters": [ { "name": "id", "in": "path", "description": "ID of company to delete", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Company deleted successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Company deleted successfully" }, "id": { "description": "ID of the deleted company", "type": "integer", "example": 1 } }, "type": "object" } } } }, "401": { "description": "Unauthorised" }, "403": { "description": "The owner of the API key is not allowed to edit this company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Company not found" }, "409": { "description": "The company can't be deleted right now", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] } }, "/api/v1/contacts": { "get": { "tags": [ "Contact" ], "summary": "List all contacts", "description": "Lists the contacts of the workspace, oldest first. Use the filters to narrow the list down and page + per_page to walk through it.", "operationId": "listContacts", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "name": "company_id", "in": "query", "description": "Only contacts connected to this company", "required": false, "schema": { "type": "integer" } }, { "name": "email", "in": "query", "description": "Only the contact using this email address. Useful to check if a contact already exists.", "required": false, "schema": { "type": "string", "format": "email" } }, { "name": "updated_since", "in": "query", "description": "Only contacts updated at or after this moment. Useful to sync changes.", "required": false, "schema": { "type": "string", "format": "date-time", "example": "2024-04-29T10:00:00Z" } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "type": "object" } } } }, "401": { "description": "Unauthorised" }, "422": { "description": "Invalid filter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] }, "post": { "tags": [ "Contact" ], "summary": "Create a new contact", "description": "Creates a contact on the company marked main_company in company_contacts (otherwise the first connected one) and connects it to the other companies listed. If a contact of the workspace already uses one of the emails nothing is changed and you receive a 409 with that contact.", "operationId": "createContact", "requestBody": { "description": "Contact data", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactInput" } } } }, "responses": { "200": { "description": "Contact created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "401": { "description": "Unauthorised" }, "403": { "description": "The owner of the API key is not allowed to edit this company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Conflict with existing contact", "content": { "application/json": { "schema": { "properties": { "contact": { "$ref": "#/components/schemas/Contact" }, "message": { "description": "conflict error message", "type": "string", "example": "Conflict: a contact with the email john@example.com already exists" } }, "type": "object" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] } }, "/api/v1/contacts/{id}": { "get": { "tags": [ "Contact" ], "summary": "Get a single contact", "description": "Retrieves a single contact by its unique ID", "operationId": "getContact", "parameters": [ { "name": "id", "in": "path", "description": "ID of the contact to retrieve", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Contact retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "401": { "description": "Unauthorised" }, "404": { "description": "Contact not found" }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] }, "put": { "tags": [ "Contact" ], "summary": "Update an existing contact", "description": "Only the fields you send are changed (on update company_contacts is not required). Careful with the 3 lists: contact_emails (or email) and contact_urls REPLACE what the contact has, company_contacts only changes the companies listed. A contact must always stay connected to at least one company.", "operationId": "updateContact", "parameters": [ { "name": "id", "in": "path", "description": "Contact ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "description": "Contact data to update", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactInput" } } } }, "responses": { "200": { "description": "Contact updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "401": { "description": "Unauthorised" }, "403": { "description": "The owner of the API key is not allowed to edit the company of this contact", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Contact not found" }, "409": { "description": "Conflict with existing contact", "content": { "application/json": { "schema": { "properties": { "contact": { "$ref": "#/components/schemas/Contact" }, "message": { "description": "conflict error message", "type": "string", "example": "Conflict: a contact with the email john@example.com already exists" } }, "type": "object" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] }, "delete": { "tags": [ "Contact" ], "summary": "Delete a contact", "description": "Permanently deletes the contact from every company it is connected to, together with its timeline items. If the contact was the only one on a deal, another contact of the company takes its place. This can't be undone.", "operationId": "deleteContact", "parameters": [ { "name": "id", "in": "path", "description": "ID of contact to delete", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Contact deleted successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Contact deleted successfully" }, "id": { "description": "ID of the deleted contact", "type": "integer", "example": 15 } }, "type": "object" } } } }, "401": { "description": "Unauthorised" }, "403": { "description": "The owner of the API key is not allowed to edit a company of this contact", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Contact not found" }, "409": { "description": "The contact can't be deleted right now", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] } }, "/api/v1/custom_fields": { "get": { "tags": [ "Custom Field" ], "summary": "List all custom fields", "description": "Lists the custom fields of the workspace (deleted ones are left out). Use it to find the id to send inside custom_fields on a deal, and to read the custom_fields returned on companies, contacts and deals.", "operationId": "listCustomFields", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "name": "entity_type", "in": "query", "description": "Only custom fields attached to this kind of object", "required": false, "schema": { "$ref": "#/components/schemas/custom_field_entity_type_options" } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CustomField" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "type": "object" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid filter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] } }, "/api/v1/custom_fields/{id}": { "get": { "tags": [ "Custom Field" ], "summary": "Get a single custom field", "description": "Returns one custom field definition. 404 when the id is not a custom field of your workspace.", "operationId": "getCustomField", "parameters": [ { "name": "id", "in": "path", "description": "ID of the custom field to retrieve", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Custom field retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomField" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Custom field not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] } }, "/api/v1/deals": { "get": { "tags": [ "Deal" ], "summary": "List all deals", "description": "Lists the deals of the workspace, oldest first. Use the filters to narrow the list down and page + per_page to walk through it.", "operationId": "listDeals", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "name": "company_id", "in": "query", "description": "Only deals of this company", "required": false, "schema": { "type": "integer" } }, { "name": "deal_pipeline_id", "in": "query", "description": "Only deals in this deal pipeline", "required": false, "schema": { "type": "integer" } }, { "name": "deal_stage_id", "in": "query", "description": "Only deals in this deal stage", "required": false, "schema": { "type": "integer" } }, { "name": "outcome", "in": "query", "description": "Only deals with this outcome", "required": false, "schema": { "$ref": "#/components/schemas/deal_outcome_options" } }, { "name": "updated_since", "in": "query", "description": "Only deals updated at or after this moment. Useful to sync changes.", "required": false, "schema": { "type": "string", "format": "date-time", "example": "2024-04-29T10:00:00Z" } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Deal" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "type": "object" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid filter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] }, "post": { "tags": [ "Deal" ], "summary": "Create a new deal", "description": "Creates a deal on a company. Exactly like creating a deal inside ProspectSafari, this applies the checklist of the deal stage (which can create tasks) and updates the status of the company and its contacts.", "operationId": "createDeal", "requestBody": { "description": "Deal data", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealInput" } } } }, "responses": { "200": { "description": "Deal created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deal" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The owner of the API key is not allowed to edit this company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] } }, "/api/v1/deals/{id}": { "get": { "tags": [ "Deal" ], "summary": "Get a single deal", "description": "Retrieves a single deal by its unique ID", "operationId": "getDeal", "parameters": [ { "name": "id", "in": "path", "description": "ID of the deal to retrieve", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Deal retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deal" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Deal not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] }, "put": { "tags": [ "Deal" ], "summary": "Update an existing deal", "description": "Only the fields you send are changed, every other field keeps its current value. Send null on description to clear it. If you send contacts it replaces the full list of contacts on the deal. Moving the deal to another stage applies the checklist of the new stage, exactly like inside ProspectSafari.", "operationId": "updateDeal", "parameters": [ { "name": "id", "in": "path", "description": "Deal ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "description": "Deal data to update", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealInput" } } } }, "responses": { "200": { "description": "Deal updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deal" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The owner of the API key is not allowed to edit this company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Deal not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] }, "delete": { "tags": [ "Deal" ], "summary": "Delete a deal", "description": "Deletes the deal and the not yet completed tasks its checklist created.", "operationId": "deleteDeal", "parameters": [ { "name": "id", "in": "path", "description": "ID of deal to delete", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Deal deleted successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Deal deleted successfully" }, "id": { "description": "ID of the deleted deal", "type": "integer", "example": 1 } }, "type": "object" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The owner of the API key is not allowed to edit this company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Deal not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] } }, "/api/v1/deals/{id}/checklist": { "get": { "tags": [ "Deal" ], "summary": "Get the checklist of a deal", "description": "Returns the checklist of the stage the deal is in right now, with where the deal stands on every step.", "operationId": "getDealChecklist", "parameters": [ { "name": "id", "in": "path", "description": "Deal ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Checklist of the deal retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealChecklist" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Deal not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] } }, "/api/v1/deals/{id}/checklist_steps/{step_id}/complete": { "post": { "tags": [ "Deal" ], "summary": "Tick a checklist step off on a deal", "description": "Exactly like ticking the step inside ProspectSafari: the task of the step is completed, the task of the next step is created, and when it was the last open step the deal moves to the next stage of its pipeline (the answer then shows the checklist of that new stage). No request body.", "operationId": "completeDealChecklistStep", "parameters": [ { "name": "id", "in": "path", "description": "Deal ID", "required": true, "schema": { "type": "integer" } }, { "name": "step_id", "in": "path", "description": "ID of the checklist step. Must be a step of the checklist of the stage the deal is in.", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Step completed, the checklist of the deal as it is now", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealChecklist" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The owner of the API key is not allowed to edit this company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Deal not found, or the step is not on the checklist of the deal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The step is already completed, doesn't apply to this deal, or its checklist is disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] } }, "/api/v1/deals/{id}/checklist_steps/{step_id}/uncomplete": { "post": { "tags": [ "Deal" ], "summary": "Untick a checklist step on a deal", "description": "Exactly like unticking the step inside ProspectSafari: the step is open again and the not yet completed tasks of the steps after it are removed. No request body.", "operationId": "uncompleteDealChecklistStep", "parameters": [ { "name": "id", "in": "path", "description": "Deal ID", "required": true, "schema": { "type": "integer" } }, { "name": "step_id", "in": "path", "description": "ID of the checklist step. Must be a step of the checklist of the stage the deal is in.", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Step open again, the checklist of the deal as it is now", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealChecklist" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The owner of the API key is not allowed to edit this company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Deal not found, or the step is not on the checklist of the deal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The step is not completed, or its checklist is disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] } }, "/api/v1/deals/{id}/documents": { "get": { "tags": [ "Deal" ], "summary": "Get the documents of a deal", "description": "Returns the documents the Sales Coach shows for this deal right now (its Resources tab): the ones of the next step of its checklist, of the stage it is in, and of the custom field options the deal, its company and its contacts have. Each comes with the reasons it is shown. Open one at its url; GET /documents/{id} gives the content.", "operationId": "getDealDocuments", "parameters": [ { "name": "id", "in": "path", "description": "Deal ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "The documents of the deal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealDocuments" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Deal not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] } }, "/api/v1/deals/{id}/qualification": { "get": { "tags": [ "Deal" ], "summary": "Get the qualification questions of a deal", "description": "Returns the qualification questionnaire of the stage the deal is in (the Qualify tab of the Sales Coach): every question with the answers it accepts and the current answer, plus the win probability and confidence they produce.", "operationId": "getDealQualification", "parameters": [ { "name": "id", "in": "path", "description": "Deal ID", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "The questionnaire of the deal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealQualification" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Deal not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] } }, "/api/v1/deals/{id}/qualification/{question_id}": { "put": { "tags": [ "Deal" ], "summary": "Answer a qualification question of a deal", "description": "Exactly like clicking an answer in the Qualify tab of the Sales Coach: the answer is saved (a new answer replaces the old one, the history is kept) and the win probability of the deal is recalculated. The answer shows the questionnaire as it is now, with the new probability.", "operationId": "answerDealQualificationQuestion", "parameters": [ { "name": "id", "in": "path", "description": "Deal ID", "required": true, "schema": { "type": "integer" } }, { "name": "question_id", "in": "path", "description": "ID of the question. Must be a question of the questionnaire of the stage the deal is in.", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "value" ], "properties": { "value": { "description": "One of the values in choices of the question: 0, 50 or 100 for a Yes / Maybe / No question, 0, 25, 50, 75 or 100 for the others.", "type": "integer", "example": 100 } }, "type": "object" } } } }, "responses": { "200": { "description": "Answer saved, the questionnaire of the deal as it is now", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealQualification" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The owner of the API key is not allowed to edit this company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Deal not found, or the question is not in the questionnaire of the deal", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The question doesn't apply to this deal (it depends on another answer), or the questionnaire is disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "value is not one of the choices of the question", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] } }, "/api/v1/deal_pipelines": { "get": { "tags": [ "Deal Pipeline" ], "summary": "List all deal pipelines", "description": "Lists the deal pipelines of the workspace together with their stages. Use it to find the deal_pipeline_id and deal_stage_id needed to create a deal.", "operationId": "listDealPipelines", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DealPipeline" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "type": "object" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid page or per_page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] }, "post": { "tags": [ "Deal Pipeline" ], "summary": "Create a new deal pipeline", "description": "Creates a pipeline with its stages, in the order sent. Each stage needs a name and a type. Only admins of the workspace can create pipelines.", "operationId": "createDealPipeline", "requestBody": { "description": "Deal pipeline data", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealPipelineInput" } } } }, "responses": { "200": { "description": "Deal pipeline created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealPipeline" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The owner of the API key is not an admin of the workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] } }, "/api/v1/deal_pipelines/{id}": { "get": { "tags": [ "Deal Pipeline" ], "summary": "Get a single deal pipeline", "description": "Retrieves a single deal pipeline, together with its stages, by its unique ID", "operationId": "getDealPipeline", "parameters": [ { "name": "id", "in": "path", "description": "ID of the deal pipeline to retrieve", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Deal pipeline retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealPipeline" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Deal pipeline not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] }, "put": { "tags": [ "Deal Pipeline" ], "summary": "Update an existing deal pipeline", "description": "Only the fields you send are changed. If you send deal_stages, that list replaces all the stages: keep a stage by sending its id (its fields you leave out keep their value), add one by leaving id out, remove one by leaving it out of the list. A stage which still has deals can't be removed: move its deals first (PUT /deals/{id} with deal_stage_id). When the checklist of a stage changes, the open tasks its deals had from the old checklist are removed in the background. Set active to false to stop offering the pipeline for new deals. Only admins of the workspace can change pipelines.", "operationId": "updateDealPipeline", "parameters": [ { "name": "id", "in": "path", "description": "Deal pipeline ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "description": "Deal pipeline data to update", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealPipelineInput" } } } }, "responses": { "200": { "description": "Deal pipeline updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DealPipeline" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The owner of the API key is not an admin of the workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Deal pipeline not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "A stage left out of deal_stages still has deals", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] } }, "/api/v1/documents": { "get": { "tags": [ "Document" ], "summary": "List all documents", "description": "Lists the documents of the Sales Coach, oldest first, with where each one is attached. The content (html) only comes with GET /documents/{id}.", "operationId": "listDocuments", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Document" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "type": "object" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid page or per_page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] }, "post": { "tags": [ "Document" ], "summary": "Create a new document", "description": "Creates a document from exactly one of: html (a TEXT document), link (a LINK document) or pdf (a PDF document, sent as multipart/form-data). It shows up in the Sales Coach once it is attached: document_ids of a pipeline stage (PUT /deal_pipelines/{id}) or of a checklist step (PUT /checklists/{id}/steps/{step_id}). Only admins of the workspace can create documents, and the plan of the workspace must include the full sales coach.", "operationId": "createDocument", "requestBody": { "description": "Document data", "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DocumentUploadInput" } }, "application/json": { "schema": { "$ref": "#/components/schemas/DocumentInput" } } } }, "responses": { "200": { "description": "Document created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The owner of the API key is not an admin, or the plan doesn't include documents", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input, e.g. none or more than one of html, link and pdf", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] } }, "/api/v1/documents/{id}": { "get": { "tags": [ "Document" ], "summary": "Get a single document", "description": "Returns one document with its content (html, for types TEXT and DESIGN). A PDF opens at url. 404 when the id is not a document of your workspace.", "operationId": "getDocument", "parameters": [ { "name": "id", "in": "path", "description": "ID of the document to retrieve", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Document retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] }, "put": { "tags": [ "Document" ], "summary": "Update an existing document", "description": "Only the fields you send are changed. The content can only change within the type of the document: html for a TEXT document, link for a LINK document; a PDF is replaced with POST /documents/{id}/pdf. A DESIGN document was built with the drag and drop editor, so its html can only be changed inside ProspectSafari. To change the type, create a new document. Only admins of the workspace can change documents.", "operationId": "updateDocument", "parameters": [ { "name": "id", "in": "path", "description": "Document ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "description": "Document data to update", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentInput" } } } }, "responses": { "200": { "description": "Document updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The owner of the API key is not an admin, or the document is disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The content sent doesn't fit the type of the document", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] }, "delete": { "tags": [ "Document" ], "summary": "Delete a document", "description": "Permanently deletes the document (and its PDF). It disappears from every stage, checklist step and custom field option it was attached to, and its url stops working. Only admins of the workspace can delete documents. This can't be undone.", "operationId": "deleteDocument", "parameters": [ { "name": "id", "in": "path", "description": "ID of the document to delete", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Document deleted successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Document deleted successfully" }, "id": { "description": "ID of the deleted document", "type": "integer", "example": 12 } }, "type": "object" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The owner of the API key is not an admin of the workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] } }, "/api/v1/documents/{id}/pdf": { "post": { "tags": [ "Document" ], "summary": "Replace the PDF of a document", "description": "Uploads a new file for a PDF document, as multipart/form-data with the field pdf (5 MB at most). The url of the document stays the same. Only admins of the workspace can change documents.", "operationId": "replaceDocumentPdf", "parameters": [ { "name": "id", "in": "path", "description": "ID of a PDF document", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "description": "The new file", "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "pdf" ], "properties": { "pdf": { "description": "The PDF file, 5 MB at most", "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "200": { "description": "PDF replaced successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The owner of the API key is not an admin, or the document is disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Document not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The document is not a PDF document", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "No file, not a PDF, or larger than 5 MB", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] } }, "/api/v1/email_sequences": { "get": { "tags": [ "Email Sequence" ], "summary": "List all email sequences", "description": "Lists the email sequences of the workspace with their emails, oldest first.", "operationId": "listEmailSequences", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EmailSequence" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "type": "object" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid page or per_page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] }, "post": { "tags": [ "Email Sequence" ], "summary": "Create a new email sequence", "description": "Creates a sequence of emails. Nothing is sent: a sequence only becomes emails when it is started for a contact inside ProspectSafari. The number of sequences is limited by the plan of the workspace. A private template you put in a sequence becomes shared with the workspace (workspace_share true), so every team member can start the sequence.", "operationId": "createEmailSequence", "requestBody": { "description": "Email sequence data", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailSequenceInput" } } } }, "responses": { "200": { "description": "Email sequence created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailSequence" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The plan of the workspace doesn't allow more sequences", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] } }, "/api/v1/email_sequences/{id}": { "get": { "tags": [ "Email Sequence" ], "summary": "Get a single email sequence", "description": "Returns one email sequence with its emails. 404 when the id is not a sequence of your workspace.", "operationId": "getEmailSequence", "parameters": [ { "name": "id", "in": "path", "description": "ID of the email sequence to retrieve", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Email sequence retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailSequence" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Email sequence not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] }, "put": { "tags": [ "Email Sequence" ], "summary": "Update an existing email sequence", "description": "Only the fields you send are changed. If you send emails, that list replaces all the current emails of the sequence. Emails already scheduled from this sequence are not changed. Only admins of the workspace can change a sequence. Every update (a rename too) makes each private template of the sequence shared with the workspace (workspace_share true).", "operationId": "updateEmailSequence", "parameters": [ { "name": "id", "in": "path", "description": "Email sequence ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "description": "Email sequence data to update", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailSequenceInput" } } } }, "responses": { "200": { "description": "Email sequence updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailSequence" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The owner of the API key is not an admin of the workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Email sequence not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] }, "delete": { "tags": [ "Email Sequence" ], "summary": "Delete an email sequence", "description": "Permanently deletes the sequence. Emails already scheduled from it are still sent: cancel them one by one with DELETE /timeline_items/emails/{id}. The templates it used are not touched. Only admins of the workspace can delete a sequence. This can't be undone.", "operationId": "deleteEmailSequence", "parameters": [ { "name": "id", "in": "path", "description": "ID of the email sequence to delete", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Email sequence deleted successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Email sequence deleted successfully" }, "id": { "description": "ID of the deleted email sequence", "type": "integer", "example": 1 } }, "type": "object" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The owner of the API key is not an admin of the workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Email sequence not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] } }, "/api/v1/email_templates": { "get": { "tags": [ "Email Template" ], "summary": "List all email templates", "description": "Lists the email templates the owner of the API key can use: the ones shared with the workspace plus their own, oldest first.", "operationId": "listEmailTemplates", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EmailTemplate" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "type": "object" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid page or per_page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] }, "post": { "tags": [ "Email Template" ], "summary": "Create a new email template", "description": "Creates a text template owned by the owner of the API key. The number of templates is limited by the plan of the workspace.", "operationId": "createEmailTemplate", "requestBody": { "description": "Email template data", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailTemplateInput" } } } }, "responses": { "200": { "description": "Email template created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailTemplate" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The plan of the workspace doesn't allow more templates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] } }, "/api/v1/email_templates/{id}": { "get": { "tags": [ "Email Template" ], "summary": "Get a single email template", "description": "Returns one email template with its subject and html. 404 when the id is not a template you can use.", "operationId": "getEmailTemplate", "parameters": [ { "name": "id", "in": "path", "description": "ID of the email template to retrieve", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Email template retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailTemplate" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Email template not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] }, "put": { "tags": [ "Email Template" ], "summary": "Update an existing email template", "description": "Only the fields you send are changed, every other field keeps its current value. If has_pending_emails is true the scheduled emails will be sent with the new content. The html of a template built with the visual editor (visual_editor = true) can't be changed here.", "operationId": "updateEmailTemplate", "parameters": [ { "name": "id", "in": "path", "description": "Email template ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "description": "Email template data to update", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailTemplateInput" } } } }, "responses": { "200": { "description": "Email template updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailTemplate" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The owner of the API key is not allowed to edit this template", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Email template not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The html of a template built with the visual editor can't be changed through the API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] }, "delete": { "tags": [ "Email Template" ], "summary": "Delete an email template", "description": "Permanently deletes the template. It is also taken out of the email sequences which use it, and a sequence left without any email is deleted too. Emails already sent with it stay as they are. This can't be undone.", "operationId": "deleteEmailTemplate", "parameters": [ { "name": "id", "in": "path", "description": "ID of email template to delete", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Email template deleted successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Email template deleted successfully" }, "id": { "description": "ID of the deleted email template", "type": "integer", "example": 1 } }, "type": "object" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The owner of the API key is not allowed to delete this template", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Email template not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The email template can't be deleted through the API", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] } }, "/api/v1/lists": { "get": { "tags": [ "List" ], "summary": "List all lists", "description": "Lists the lists you can put companies in: every list of the workspace if the owner of the API key is an admin, otherwise only the lists that team member owns.", "operationId": "listLists", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyList" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "type": "object" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid page or per_page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] } }, "/api/v1/lists/{id}": { "get": { "tags": [ "List" ], "summary": "Get a single list", "description": "Returns one list. 404 when the id is not a list of your workspace.", "operationId": "getList", "parameters": [ { "name": "id", "in": "path", "description": "ID of the list to retrieve", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "List retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyList" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "List not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] } }, "/api/v1/message_types": { "get": { "tags": [ "Message Type" ], "summary": "List all message types", "description": "Lists the kinds of message which can be logged on a timeline. The value of one of them is the message_type needed to log a message.", "operationId": "listMessageTypes", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MessageType" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "type": "object" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid page or per_page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] } }, "/api/v1/quizzes": { "get": { "tags": [ "Quiz" ], "summary": "List all quizzes", "description": "Lists the qualification quizzes of the Sales Coach, oldest first, with their sections and questions and the pipelines which use them.", "operationId": "listQuizzes", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Quiz" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "type": "object" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid page or per_page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] }, "post": { "tags": [ "Quiz" ], "summary": "Create a new quiz", "description": "Creates a qualification quiz with its sections and questions. It does nothing until a pipeline uses it: set quiz_id on a pipeline with PUT /deal_pipelines/{id}. Until the workspace has won and lost enough deals with it, every question weighs the same. Only admins of the workspace can create quizzes, and the plan of the workspace must include the full sales coach.", "operationId": "createQuiz", "requestBody": { "description": "Quiz data", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuizInput" } } } }, "responses": { "200": { "description": "Quiz created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quiz" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The owner of the API key is not an admin, or the plan doesn't include quizzes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] } }, "/api/v1/quizzes/{id}": { "get": { "tags": [ "Quiz" ], "summary": "Get a single quiz", "description": "Returns one quiz with its sections and questions. 404 when the id is not a quiz of your workspace. The answers of one deal are at GET /deals/{id}/qualification.", "operationId": "getQuiz", "parameters": [ { "name": "id", "in": "path", "description": "ID of the quiz to retrieve", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Quiz retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quiz" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Quiz not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] }, "put": { "tags": [ "Quiz" ], "summary": "Update an existing quiz", "description": "Only the fields you send are changed. If you send sections, that list replaces all the sections and questions: keep a question by sending its id (its fields you leave out keep their value, its answers on deals stay), add one by leaving id out, delete one by leaving it out (the answers deals gave to it are deleted too). Saving recalculates the question weights and the win probability of the deals which use the quiz, as when it is saved in ProspectSafari. Only admins of the workspace can change quizzes.", "operationId": "updateQuiz", "parameters": [ { "name": "id", "in": "path", "description": "Quiz ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "description": "Quiz data to update", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuizInput" } } } }, "responses": { "200": { "description": "Quiz updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quiz" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The owner of the API key is not an admin, or the quiz is disabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Quiz not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] }, "delete": { "tags": [ "Quiz" ], "summary": "Delete a quiz", "description": "Permanently deletes the quiz with its questions and every answer deals gave to them. The pipelines which used it are left without a quiz; their deals keep the win probability they had. Only admins of the workspace can delete quizzes. This can't be undone.", "operationId": "deleteQuiz", "parameters": [ { "name": "id", "in": "path", "description": "ID of the quiz to delete", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Quiz deleted successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Quiz deleted successfully" }, "id": { "description": "ID of the deleted quiz", "type": "integer", "example": 2 } }, "type": "object" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The owner of the API key is not an admin of the workspace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Quiz not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] } }, "/api/v1/sending_addresses": { "get": { "tags": [ "Sending Address" ], "summary": "List the addresses you can send email from", "description": "Lists the email addresses the owner of the API key connected to ProspectSafari. The id of one of them is the from_id needed to create an email.", "operationId": "listSendingAddresses", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SendingAddress" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "type": "object" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid page or per_page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] } }, "/webhook": { "post": { "tags": [ "Webhooks" ], "summary": "The payload ProspectSafari POSTs to your webhook URL", "description": "Not an endpoint of this API. This describes the request ProspectSafari makes to the URL set on the Integrations page, each time a company, contact or timeline item of the kinds you ticked there changes (companies only once they reached the status you chose). The URL must be a public https address. Answer with a 2xx status to acknowledge the payload.", "operationId": "webhookPayload", "requestBody": { "description": "What your URL receives", "required": true, "content": { "application/json": { "schema": { "properties": { "event": { "description": "What kind of record it is about", "type": "string", "example": "company", "enum": [ "company", "contact", "timeline_item" ] }, "properties": { "description": "The record, flattened: its ids, main fields, one _company_url per listed url and every custom field under its own name.", "type": "object", "example": { "id": 384222, "owner_id": 2, "name": "Sample Company", "website": "https://www.samplecompany.com", "country": "United States", "city": "Sample City", "address": "1234 Sample Street", "zip": "123456", "linkedin_company_url": "https://www.linkedin.com/company/sample-company" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Your server acknowledges the payload" }, "400": { "description": "Your server rejects the payload" } } } }, "/api/v1/task_queues": { "get": { "tags": [ "Task Queue" ], "summary": "List all task queues", "description": "Lists the task queues of the workspace. Every task sits in one queue, use this to find the task_queue_id needed to create a task.", "operationId": "listTaskQueues", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TaskQueue" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "type": "object" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid page or per_page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] } }, "/api/v1/task_queues/{id}": { "get": { "tags": [ "Task Queue" ], "summary": "Get a single task queue", "description": "Returns one task queue. 404 when the id is not a task queue of your workspace.", "operationId": "getTaskQueue", "parameters": [ { "name": "id", "in": "path", "description": "ID of the task queue to retrieve", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Task queue retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskQueue" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Task queue not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] } }, "/api/v1/team_members": { "get": { "tags": [ "Team Member" ], "summary": "List all team members", "description": "Lists the team members of the workspace. The id of a team member is the user_workspace_id used on deals, timeline items...", "operationId": "listTeamMembers", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TeamMember" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "type": "object" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid page or per_page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] } }, "/api/v1/team_members/{id}": { "get": { "tags": [ "Team Member" ], "summary": "Get a single team member", "description": "Returns one member of the workspace. 404 when the id is not a member of your workspace.", "operationId": "getTeamMember", "parameters": [ { "name": "id", "in": "path", "description": "ID of the team member to retrieve", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Team member retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamMember" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Team member not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] } }, "/api/v1/timeline_items": { "get": { "tags": [ "Timeline Item" ], "summary": "List all timeline items", "description": "Lists the timeline items (emails, phone calls, notes, meetings, tasks, messages) of the workspace, oldest first. Use the filters to narrow the list down and page + per_page to walk through it.", "operationId": "listTimelineItems", "parameters": [ { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/per_page" }, { "name": "type", "in": "query", "description": "Only items of this type", "required": false, "schema": { "$ref": "#/components/schemas/timeline_item_type_options" } }, { "name": "company_id", "in": "query", "description": "Only items of this company", "required": false, "schema": { "type": "integer" } }, { "name": "contact_id", "in": "query", "description": "Only items of this contact", "required": false, "schema": { "type": "integer" } }, { "name": "deal_id", "in": "query", "description": "Only items of this deal", "required": false, "schema": { "type": "integer" } }, { "name": "user_workspace_id", "in": "query", "description": "Only items which belong to this team member", "required": false, "schema": { "type": "integer" } }, { "name": "completed", "in": "query", "description": "Only tasks (every other type is left out): true for the tasks which are done, false for the ones still open. Example: type=tasks&completed=false&user_workspace_id=2 lists the open tasks of team member 2.", "required": false, "schema": { "type": "boolean" } }, { "name": "updated_since", "in": "query", "description": "Only items updated at or after this moment. Useful to sync changes.", "required": false, "schema": { "type": "string", "format": "date-time", "example": "2024-04-29T10:00:00Z" } }, { "name": "sub_type", "in": "query", "description": "Only items with this sub_type. Needs type, because the numbers mean something else for every type. Example: type=tasks&sub_type=2 = phone call tasks (task sub types: 0 Email, 1 Research note, 2 Phone call, 3 Other, 4 Send message).", "required": false, "schema": { "type": "integer" } }, { "name": "date_from", "in": "query", "description": "Only items whose date_time is at or after this moment (for a task: due at or after, for a meeting: starting at or after).", "required": false, "schema": { "type": "string", "format": "date-time", "example": "2024-04-29T00:00:00Z" } }, { "name": "date_to", "in": "query", "description": "Only items whose date_time is at or before this moment. Example, the calls still to make today: type=tasks&sub_type=2&completed=false&date_to=2024-04-29T23:59:59Z&sort=date_time", "required": false, "schema": { "type": "string", "format": "date-time", "example": "2024-04-29T23:59:59Z" } }, { "name": "sort", "in": "query", "description": "Order of the list: id (default, oldest first), date_time (earliest date_time first, e.g. tasks in the order they are due) or -date_time (latest first, e.g. the most recent activity).", "required": false, "schema": { "type": "string", "enum": [ "id", "date_time", "-date_time" ] } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TimelineItem" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "type": "object" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid filter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] } }, "/api/v1/timeline_items/{id}": { "get": { "tags": [ "Timeline Item" ], "summary": "Get a single timeline item", "description": "Retrieves a single timeline item of any type by its unique ID", "operationId": "getTimelineItem", "parameters": [ { "name": "id", "in": "path", "description": "ID of the timeline item to retrieve", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Timeline item retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimelineItem" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Timeline item not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] } }, "/api/v1/timeline_items/notes": { "post": { "tags": [ "Timeline Item" ], "summary": "Create a new note", "description": "Adds a note to the timeline of a company.", "operationId": "createTimelineItemNote", "requestBody": { "description": "Note data", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteInput" } } } }, "responses": { "200": { "description": "Note created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimelineItem" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The owner of the API key is not allowed to edit this company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] } }, "/api/v1/timeline_items/notes/{id}": { "put": { "tags": [ "Timeline Item" ], "summary": "Update an existing note", "description": "Only the fields you send are changed, every other field keeps its current value. Send null on contact_id to remove the contact from the note.", "operationId": "updateTimelineItemNote", "parameters": [ { "name": "id", "in": "path", "description": "Note ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "description": "Note data to update", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteInput" } } } }, "responses": { "200": { "description": "Note updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimelineItem" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The owner of the API key is not allowed to edit this company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Note not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The note can't be updated right now", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] }, "delete": { "tags": [ "Timeline Item" ], "summary": "Delete a note", "description": "Permanently deletes the note. This can't be undone.", "operationId": "deleteTimelineItemNote", "parameters": [ { "name": "id", "in": "path", "description": "ID of note to delete", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Note deleted successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Note deleted successfully" }, "id": { "description": "ID of the deleted note", "type": "integer", "example": 1 } }, "type": "object" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The owner of the API key is not allowed to edit this company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Note not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The note can't be deleted right now", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] } }, "/api/v1/timeline_items/phone_calls": { "post": { "tags": [ "Timeline Item" ], "summary": "Log a phone call", "description": "Logs a call which already happened (nothing is dialed). Exactly like logging a call inside ProspectSafari this counts a call attempt on the phone number (every outcome except 0, Incoming call), recalculates its connection rate and updates the status of the company and the contact. call_line_type, call_line_status and call_line_note describe the phone line, not this call: send them to change the line, leave them out to keep the line as it is. Outcome 6 (Wrong number) always marks the line as INVALID + BAD_NUMBER.", "operationId": "createTimelineItemPhoneCall", "requestBody": { "description": "Phone call data", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneCallInput" } } } }, "responses": { "200": { "description": "Phone call logged successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimelineItem" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The owner of the API key is not allowed to edit this company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] } }, "/api/v1/timeline_items/phone_calls/{id}": { "put": { "tags": [ "Timeline Item" ], "summary": "Update a logged phone call", "description": "Only the fields you send are changed, every other field keeps its current value. Changing contact_phone_number_id moves the call (and its call attempt) to the other phone number. call_line_type, call_line_status and call_line_note are ignored here: to change the phone line update the contact.", "operationId": "updateTimelineItemPhoneCall", "parameters": [ { "name": "id", "in": "path", "description": "Phone call ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "description": "Phone call data to update", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneCallInput" } } } }, "responses": { "200": { "description": "Phone call updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimelineItem" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The owner of the API key is not allowed to edit this company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Phone call not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The phone call can't be updated right now", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] }, "delete": { "tags": [ "Timeline Item" ], "summary": "Delete a logged phone call", "description": "Deletes the call and takes its call attempt back off the phone number (later attempts on the same number are renumbered).", "operationId": "deleteTimelineItemPhoneCall", "parameters": [ { "name": "id", "in": "path", "description": "ID of phone call to delete", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Phone call deleted successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Phone call deleted successfully" }, "id": { "description": "ID of the deleted phone call", "type": "integer", "example": 1 } }, "type": "object" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The owner of the API key is not allowed to edit this company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Phone call not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The phone call can't be deleted right now", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] } }, "/api/v1/timeline_items/tasks": { "post": { "tags": [ "Timeline Item" ], "summary": "Create a new task", "description": "Creates a task for a team member. date_time is the moment the task is due. A task with priority 0 (High) is also put in the calendar of its owner, if that team member connected a calendar to ProspectSafari.", "operationId": "createTimelineItemTask", "requestBody": { "description": "Task data", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskInput" } } } }, "responses": { "200": { "description": "Task created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimelineItem" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The owner of the API key is not allowed to edit this company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] } }, "/api/v1/timeline_items/tasks/{id}": { "put": { "tags": [ "Timeline Item" ], "summary": "Update an existing task", "description": "Only the fields you send are changed, every other field keeps its current value. Change date_time to reschedule the task. To mark the task as done use the complete endpoint.", "operationId": "updateTimelineItemTask", "parameters": [ { "name": "id", "in": "path", "description": "Task ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "description": "Task data to update", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskInput" } } } }, "responses": { "200": { "description": "Task updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimelineItem" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The owner of the API key is not allowed to edit this company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Task not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The task can't be updated right now", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] }, "delete": { "tags": [ "Timeline Item" ], "summary": "Delete a task", "description": "Deletes the task. If it was in the calendar of its owner (High priority) it is removed from there too.", "operationId": "deleteTimelineItemTask", "parameters": [ { "name": "id", "in": "path", "description": "ID of task to delete", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Task deleted successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Task deleted successfully" }, "id": { "description": "ID of the deleted task", "type": "integer", "example": 1 } }, "type": "object" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The owner of the API key is not allowed to edit this company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Task not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The task can't be deleted right now", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] } }, "/api/v1/timeline_items/tasks/{id}/complete": { "post": { "tags": [ "Timeline Item" ], "summary": "Mark a task as done", "description": "Completes the task, exactly like ticking it off inside ProspectSafari. If the task was created by a checklist this also completes the checklist step, which can create the next tasks of the checklist and move the deal to its next stage. No request body.", "operationId": "completeTimelineItemTask", "parameters": [ { "name": "id", "in": "path", "description": "ID of the task to complete", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Task completed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimelineItem" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The owner of the API key is not allowed to edit this company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Task not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The task is already completed, or can't be completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] } }, "/api/v1/timeline_items/emails": { "post": { "tags": [ "Timeline Item" ], "summary": "Send an email", "description": "Sends a real email to a contact, from one of the sending addresses of the owner of the API key. The email is scheduled for date_time (now if not defined) and ProspectSafari sends it from the mailbox, exactly like an email written inside the app: it shows up on the timeline, opens and clicks are tracked, replies arrive in the mailbox. Until it is sent (sub_type_name EMAIL_SCHEDULED) it can be cancelled with the delete endpoint. An unsubscribed address is refused.", "operationId": "createTimelineItemEmail", "requestBody": { "description": "Email data", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendEmailInput" } } } }, "responses": { "200": { "description": "Email scheduled successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimelineItem" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The owner of the API key is not allowed to edit this company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The address has unsubscribed from emails", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] } }, "/api/v1/email_sequences/{id}/start": { "post": { "tags": [ "Email Sequence" ], "summary": "Start a sequence for a contact", "description": "Puts a contact in an email sequence, exactly like choosing the sequence in the email popup of ProspectSafari: one real email is scheduled per step, each one the wait of its step after the one before (the first at date_time, now if not defined), all sent from a mailbox of the owner of the API key. When the contact replies, ProspectSafari cancels the emails which are still waiting, like in the app. To stop the sequence yourself, cancel the emails which are still scheduled (DELETE /timeline_items/emails/{id}). Every custom_text_1, custom_text_2, custom_text_3 placeholder in the templates needs a value in placeholders. One start counts as one email for the limit of emails per hour; the mailbox's own hourly and daily sending limits still apply when the emails go out.", "operationId": "startEmailSequence", "parameters": [ { "name": "id", "in": "path", "description": "ID of the email sequence", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartSequenceInput" } } } }, "responses": { "200": { "description": "Sequence started: the scheduled emails, in the order they go out", "content": { "application/json": { "schema": { "properties": { "sequence_id": { "type": "integer", "example": 3 }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/TimelineItem" } } }, "type": "object" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The owner of the API key is not allowed to edit this company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Email sequence not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The address has unsubscribed, the sequence has no emails, or a step uses a template which was deleted or has no content", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input, or a custom_text placeholder without value", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] } }, "/api/v1/timeline_items/emails/{id}": { "delete": { "tags": [ "Timeline Item" ], "summary": "Cancel a scheduled email", "description": "Deletes an email which has not been sent yet (sub_type_name EMAIL_SCHEDULED, EMAIL_SCHEDULED_PAUSED or EMAIL_SCHEDULED_CANCELED), so it is never sent. An email which was already sent or received can't be deleted through the API.", "operationId": "deleteTimelineItemEmail", "parameters": [ { "name": "id", "in": "path", "description": "ID of the email to cancel", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Email cancelled successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Email deleted successfully" }, "id": { "description": "ID of the deleted email", "type": "integer", "example": 1 } }, "type": "object" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The owner of the API key is not allowed to edit this company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Email not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The email was already sent (or received), it can't be deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] } }, "/api/v1/timeline_items/messages": { "post": { "tags": [ "Timeline Item" ], "summary": "Log a message", "description": "Logs a message (WhatsApp, LinkedIn, SMS...) which was sent or received somewhere else. The API never sends a message itself. ${first_name}, ${last_name}, ${city} and ${company_name} inside the content are filled in from the contact and the company.", "operationId": "createTimelineItemMessage", "requestBody": { "description": "Message data", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageInput" } } } }, "responses": { "200": { "description": "Message logged successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimelineItem" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The owner of the API key is not allowed to edit this company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] } }, "/api/v1/timeline_items/messages/{id}": { "put": { "tags": [ "Timeline Item" ], "summary": "Update a logged message", "description": "Only the fields you send are changed, every other field keeps its current value. Nothing is sent to anybody.", "operationId": "updateTimelineItemMessage", "parameters": [ { "name": "id", "in": "path", "description": "Message ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "description": "Message data to update", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageInput" } } } }, "responses": { "200": { "description": "Message updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimelineItem" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The owner of the API key is not allowed to edit this company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Message not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The message can't be updated right now", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] }, "delete": { "tags": [ "Timeline Item" ], "summary": "Delete a logged message", "description": "Permanently deletes the logged message. Only the record in ProspectSafari goes, nothing is sent to the contact. This can't be undone.", "operationId": "deleteTimelineItemMessage", "parameters": [ { "name": "id", "in": "path", "description": "ID of message to delete", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Message deleted successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Message deleted successfully" }, "id": { "description": "ID of the deleted message", "type": "integer", "example": 1 } }, "type": "object" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The owner of the API key is not allowed to edit this company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Message not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The message can't be deleted right now", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] } }, "/api/v1/timeline_items/meetings": { "post": { "tags": [ "Timeline Item" ], "summary": "Record a meeting", "description": "Records a meeting on the timeline of a company. The meeting only lives inside ProspectSafari: it is not put in a Google / Outlook calendar and nobody receives an invitation. To invite people create the meeting inside ProspectSafari.", "operationId": "createTimelineItemMeeting", "requestBody": { "description": "Meeting data", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeetingInput" } } } }, "responses": { "200": { "description": "Meeting recorded successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimelineItem" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The owner of the API key is not allowed to edit this company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] } }, "/api/v1/timeline_items/meetings/{id}": { "put": { "tags": [ "Timeline Item" ], "summary": "Update a recorded meeting", "description": "Only the fields you send are changed, every other field keeps its current value. Moving a SCHEDULED, CONFIRMED or ALL_DECLINED meeting to another date_time sets its status to RESCHEDULED. A meeting which was connected to a calendar inside ProspectSafari (calendar_synced = true) can't be changed here: the calendar would notify the attendees.", "operationId": "updateTimelineItemMeeting", "parameters": [ { "name": "id", "in": "path", "description": "Meeting ID", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "description": "Meeting data to update", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeetingInput" } } } }, "responses": { "200": { "description": "Meeting updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TimelineItem" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The owner of the API key is not allowed to edit this company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Meeting not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The meeting is synced with a calendar, or can't be updated right now", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] }, "delete": { "tags": [ "Timeline Item" ], "summary": "Delete a recorded meeting", "description": "Deletes the meeting. A meeting which was connected to a calendar inside ProspectSafari (calendar_synced = true) can't be deleted here: the calendar would send cancellations to the attendees.", "operationId": "deleteTimelineItemMeeting", "parameters": [ { "name": "id", "in": "path", "description": "ID of meeting to delete", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Meeting deleted successfully", "content": { "application/json": { "schema": { "properties": { "message": { "type": "string", "example": "Meeting deleted successfully" }, "id": { "description": "ID of the deleted meeting", "type": "integer", "example": 1 } }, "type": "object" } } } }, "401": { "description": "Unauthorised", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "The owner of the API key is not allowed to edit this company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Meeting not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The meeting is synced with a calendar, or can't be deleted right now", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Too many requests: slow down" }, "500": { "description": "Temporary server error" } }, "security": [ { "X-API-Key": [], "X-API-Secret": [] } ] } } }, "components": { "schemas": { "checklist_step_type_options": { "description": "What the step asks for: 0 (Send email), 1 (Data entry and research), 2 (Phone call), 3 (Step without a task), 4 (Cold call task), 5 (Warning: alert), 6 (Send message). Types 0, 1, 2, 4 and 6 create a task and need task_queue_id, type 3 never creates one, type 5 creates one only when it has a task_queue_id.", "type": "integer", "example": 2, "enum": [ 0, 1, 2, 3, 4, 5, 6 ] }, "checklist_step_due_date_options": { "description": "When the task of the step is due, counted from the moment the task is created: 0 (3 hours), 1 (1 day), 2 (2 days), 3 (3 days), 4 (4 days), 5 (5 days), 6 (1 week), 7 (2 weeks), 8 (1 month).", "type": "integer", "example": 1, "enum": [ 0, 1, 2, 3, 4, 5, 6, 7, 8 ] }, "checklist_step_task_owner_options": { "description": "Who gets the task of the step. CURRENT_USER: the team member working the deal (who ticked the previous step off). COMPANY_OWNER: the owner of the company of the deal. TEAM_MEMBER: always the team member in task_user_workspace_id.", "type": "string", "example": "CURRENT_USER", "enum": [ "CURRENT_USER", "COMPANY_OWNER", "TEAM_MEMBER" ] }, "checklist_step_contacts_conditions_options": { "description": "How conditions on contact fields are counted when the deal has several contacts: 0 (true if ONE OR MORE contacts meet ALL contact conditions), 1 (true if ALL contacts meet ALL contact conditions), 2 (true if one or more contacts meet ONE OR MORE contact conditions).", "type": "integer", "example": 0, "enum": [ 0, 1, 2 ] }, "checklist_step_condition_operator_options": { "description": "How the field is compared with value. exists / no_exists ignore value. includes / no_includes take a list of values (the field is one of them / none of them). Text is compared without minding upper and lower case.", "type": "string", "example": "=", "enum": [ "=", "!=", ">", "<", "contains", "no_contains", "exists", "no_exists", "includes", "no_includes" ] }, "ChecklistStepCondition": { "properties": { "condition_type": { "description": "0: the step only applies to a deal when the condition is true. 1: the step is ticked off automatically when the condition is true.", "type": "integer", "example": 0, "enum": [ 0, 1 ] }, "field": { "description": "The field the condition looks at. Fixed fields: city, country_id, contact_field_first_name, contact_field_last_name, contact_field_email, contact_field_call_attempts, contact_field_best_phone_connection_rate, contact_phone_field_phone_number, contact_phone_field_call_attempts, contact_phone_field_phone_connection_rate, contact_phone_field_call_line_type, contact_email_field_email_status, contact_email_field_email_score, contact_email_email_field_email_type, contact_email_email_field_email_verification_status, deal_field_probability, deal_field_min_probability, deal_field_max_probability, deal_field_probability_confidence, contact_special_service_1_result, contact_special_service_1_sent_date, contact_special_service_1_completed_date. With the id of a custom field (see custom_fields): workspace_field_ID (company field), workspace_field_CONTACT_ID, workspace_field_DEAL_ID. Also workspace_decision_ID, custom_deal_field_ID and custom_contact_field_ID.", "type": "string", "example": "city" }, "operator": { "$ref": "#/components/schemas/checklist_step_condition_operator_options" }, "value": { "description": "What the field is compared with. The list of an includes / no_includes condition comes back as JSON text, e.g. [3,7]; you can send it back as it is or as a list.", "type": "string", "example": "Berlin", "nullable": true } }, "type": "object" }, "ChecklistStep": { "properties": { "id": { "description": "Unique ID", "type": "integer", "example": 7 }, "order": { "description": "Position of the step inside the checklist (starts at 0)", "type": "integer", "example": 0 }, "text": { "type": "string", "example": "Call the decision maker" }, "explanation": { "type": "string", "example": "Ask about their current supplier.", "nullable": true }, "type": { "$ref": "#/components/schemas/checklist_step_type_options" }, "priority": { "$ref": "#/components/schemas/task_priority_options" }, "due_date": { "$ref": "#/components/schemas/checklist_step_due_date_options" }, "task_queue_id": { "description": "UID of the task queue the task of this step goes in. Null: the step creates no task.", "type": "integer", "example": 1, "nullable": true }, "task_owner": { "$ref": "#/components/schemas/checklist_step_task_owner_options" }, "task_user_workspace_id": { "description": "UID of the team member who gets the task when task_owner is TEAM_MEMBER, otherwise null", "type": "integer", "example": null, "nullable": true }, "contacts_visible_conditions": { "$ref": "#/components/schemas/checklist_step_contacts_conditions_options" }, "contacts_autoclick_conditions": { "$ref": "#/components/schemas/checklist_step_contacts_conditions_options" }, "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/ChecklistStepCondition" } }, "document_ids": { "description": "UIDs of the documents the Sales Coach shows while this is the next step of a deal (see documents)", "type": "array", "items": { "type": "integer" }, "example": [ 12 ] } }, "type": "object" }, "Checklist": { "properties": { "id": { "description": "Unique ID", "type": "integer", "example": 4 }, "name": { "type": "string", "example": "Qualification" }, "description": { "type": "string", "example": "Steps to qualify a new lead", "nullable": true }, "disabled": { "description": "True when the checklist can't be used or changed (usually after the subscription was downgraded)", "type": "boolean", "example": false }, "created_at": { "type": "string", "format": "date-time", "example": "2024-04-29T10:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2024-04-29T10:00:00Z" }, "checklist_steps": { "description": "Steps of the checklist, in order", "type": "array", "items": { "$ref": "#/components/schemas/ChecklistStep" } } }, "type": "object" }, "ChecklistStepInput": { "properties": { "id": { "description": "Only inside checklist_steps of PUT /checklists/{id}: the id of an existing step to keep. Its fields you don't send keep their value. Leave it out for a new step.", "type": "integer", "example": 7 }, "order": { "description": "Only on POST and PUT /checklists/{id}/steps: the position to put the step at (0 = first). Left out: a new step goes last, an updated one stays where it is. Inside checklist_steps the order of the list counts instead.", "type": "integer", "example": 0, "minimum": 0 }, "text": { "description": "Required for a new step", "type": "string", "example": "Call the decision maker", "maxLength": 255 }, "explanation": { "type": "string", "example": "Ask about their current supplier.", "nullable": true, "maxLength": 3000 }, "type": { "$ref": "#/components/schemas/checklist_step_type_options" }, "priority": { "$ref": "#/components/schemas/task_priority_options" }, "due_date": { "$ref": "#/components/schemas/checklist_step_due_date_options" }, "task_queue_id": { "description": "UID of the task queue the task goes in (see task_queues). Required for types 0, 1, 2, 4 and 6, must be empty for type 3.", "type": "integer", "example": 1, "nullable": true }, "task_owner": { "$ref": "#/components/schemas/checklist_step_task_owner_options" }, "task_user_workspace_id": { "description": "UID of the team member who gets the task (see team_members). Sending it sets task_owner to TEAM_MEMBER.", "type": "integer", "example": 2, "nullable": true }, "contacts_visible_conditions": { "$ref": "#/components/schemas/checklist_step_contacts_conditions_options" }, "contacts_autoclick_conditions": { "$ref": "#/components/schemas/checklist_step_contacts_conditions_options" }, "conditions": { "description": "All the conditions of the step: the list you send replaces the current one, an empty list removes them.", "type": "array", "items": { "$ref": "#/components/schemas/ChecklistStepCondition" }, "maxItems": 20 }, "document_ids": { "description": "UIDs of the documents the Sales Coach shows while this is the next step of a deal (see documents). The list replaces the current one, an empty list removes them all.", "type": "array", "items": { "type": "integer" }, "example": [ 12 ], "maxItems": 20 } }, "type": "object" }, "ChecklistInput": { "required": [ "name", "description", "checklist_steps" ], "properties": { "name": { "type": "string", "example": "Qualification", "maxLength": 255 }, "description": { "type": "string", "example": "Steps to qualify a new lead", "maxLength": 3000 }, "checklist_steps": { "description": "All the steps, in order. On update the list you send replaces the current one: a step whose id is missing from it is deleted. A new step without priority / due_date / task_owner gets 1 (Medium) / 3 (3 days) / CURRENT_USER.", "type": "array", "items": { "$ref": "#/components/schemas/ChecklistStepInput" }, "maxItems": 100, "minItems": 1 } }, "type": "object" }, "Company": { "properties": { "id": { "description": "Unique ID", "type": "integer", "example": 1 }, "list_id": { "description": "UID of list the company belongs to.", "type": "integer", "example": 1 }, "user_workspace_id": { "description": "UID of the team member who owns the company. Null: nobody owns it.", "type": "integer", "example": 2, "nullable": true }, "name": { "type": "string", "example": "Sample Company" }, "description": { "type": "string", "example": "Company description here" }, "icon": { "description": "URL of the icon of the company", "type": "string", "example": "https://www.samplecompany.com/favicon.ico", "nullable": true }, "website": { "type": "string", "example": "https://www.samplecompany.com" }, "status": { "$ref": "#/components/schemas/status_options" }, "address": { "properties": { "street": { "type": "string", "example": "1234 Sample Street" }, "city": { "type": "string", "example": "Sample City" }, "region": { "type": "string", "example": "Sample Region" }, "country": { "description": "Country alpha2Code", "type": "string", "example": "US" }, "postal_code": { "type": "string", "example": "123456" }, "longitude": { "type": "number", "example": -73.98, "nullable": true }, "latitude": { "type": "number", "example": 40.75, "nullable": true } }, "type": "object" }, "employees": { "properties": { "minimum": { "type": "integer", "example": 10 }, "maximum": { "type": "integer", "example": 100 } }, "type": "object" }, "founded": { "description": "Date the company was founded (YYYY-MM-DD)", "type": "string", "format": "date", "example": "1999-01-01", "nullable": true }, "last_funding": { "description": "Date of the last funding round (YYYY-MM-DD)", "type": "string", "format": "date", "example": "2020-06-01", "nullable": true }, "total_funding": { "type": "integer", "example": 5000000 }, "annual_revenue": { "type": "integer", "example": 1000000 }, "origin": { "$ref": "#/components/schemas/origin_options" }, "created_at": { "type": "string", "format": "date-time", "example": "2024-04-29T10:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2024-04-29T10:00:00Z" }, "company_urls": { "description": "Social + listing urls of the company", "type": "array", "items": { "type": "string", "example": "https://www.linkedin.com/company/sample-company" } }, "keywords_found": { "description": "Words or phrases of your String (keyword) Listeners (Settings) which the website scrape found on the company website. Empty until the website was scraped.", "type": "array", "items": { "properties": { "keyword": { "type": "string", "example": "e-commerce" }, "count": { "description": "How often it was found", "type": "integer", "example": 3, "nullable": true }, "listener": { "description": "Name of the String Listener the word belongs to", "type": "string", "example": "Tech stack", "nullable": true } }, "type": "object" } }, "links_found": { "description": "ONLY ON GET /companies/{id} (left out of the list, it takes too long for 100 companies at once). Links on the company website to domains of interest, as marked by your Link Listeners (Settings), e.g. a competitor's booking system.", "type": "array", "items": { "properties": { "domain": { "type": "string", "example": "beddy.io" }, "listener": { "description": "Name of the Link Listener which marked it", "type": "string", "example": "Booking systems" } }, "type": "object" } }, "company_contacts": { "description": "The contacts connected to the company: the same connection a contact shows in its own company_contacts, seen from the company.", "type": "array", "items": { "properties": { "contact_id": { "description": "UID of the contact", "type": "integer", "example": 15 }, "job_title": { "type": "string", "example": "Head of Sales", "nullable": true }, "main_company": { "description": "True when this is the main company of the contact", "type": "boolean", "nullable": true }, "main_contact": { "description": "True when this is the main contact of the company", "type": "boolean", "nullable": true }, "working_contact": { "type": "boolean", "nullable": true }, "active_at_company": { "type": "boolean", "nullable": true }, "buying_role_id": { "type": "integer", "nullable": true } }, "type": "object" } }, "custom_fields": { "type": "array", "items": { "properties": { "custom_field": { "description": "UID of the custom field", "type": "integer", "example": 12 }, "value": { "example": "Referral", "nullable": true } }, "type": "object" } }, "custom_decisions": { "type": "array", "items": { "properties": { "custom_decision": { "description": "UID of the custom decision", "type": "integer", "example": 4 }, "value": { "type": "integer", "example": 1, "nullable": true } }, "type": "object" } } }, "type": "object" }, "CompanyInput": { "required": [ "name" ], "properties": { "name": { "description": "Name of the company", "type": "string", "example": "Sample Company" }, "list_name": { "description": "Name of list you wish to connect to. If list doesn't exist it will be created.", "type": "string", "example": "First list" }, "list_id": { "description": "UID of list you wish this Company to be in. If this is defined we will ignore list_name", "type": "integer", "example": 1 }, "description": { "description": "A brief description about the company", "type": "string", "example": "Company description here" }, "website": { "description": "We will scrape the website", "type": "string", "example": "https://www.samplecompany.com" }, "status": { "$ref": "#/components/schemas/status_options" }, "address": { "properties": { "street": { "type": "string", "example": "1234 Sample Street" }, "city": { "type": "string", "example": "Sample City" }, "region": { "type": "string", "example": "Sample Region" }, "country": { "type": "string", "example": "Sample Country" }, "postal_code": { "type": "string", "example": "123456" } }, "type": "object" }, "employees": { "properties": { "minimum": { "type": "integer", "example": 10 }, "maximum": { "type": "integer", "example": 100 } }, "type": "object" }, "founded": { "description": "Date the company was founded, YYYY-MM-DD. A year (1999) or a year and month (1999-06) is accepted too and read as the 1st of that January / month.", "type": "string", "format": "date", "example": "1999-01-01", "nullable": true }, "last_funding": { "description": "Date of the last funding round, YYYY-MM-DD. A year or a year and month is accepted too, like founded.", "type": "string", "format": "date", "example": "2020-06-01", "nullable": true }, "total_funding": { "type": "integer", "example": 5000000 }, "annual_revenue": { "type": "integer", "example": 1000000 }, "company_urls": { "description": "Social + listing urls of the company (LinkedIn, Facebook...). Urls are added or updated, never removed.", "type": "array", "items": { "type": "string", "example": "https://www.linkedin.com/company/sample-company" } }, "user_workspace_id": { "description": "UID of the team member who owns the company (see team_members). Send null on update to leave the company without an owner.", "type": "integer", "example": 2, "nullable": true }, "custom_fields": { "description": "Only the custom fields listed are changed, all others are left as they are. value null removes the value.", "type": "array", "items": { "required": [ "custom_field" ], "properties": { "custom_field": { "description": "UID of the custom field (see custom_fields?entity_type=COMPANY)", "type": "integer", "example": 12 }, "value": { "example": "Referral", "nullable": true } }, "type": "object" } }, "custom_decisions": { "description": "Only the decisions listed are changed, all others are left as they are. value null removes the decision.", "type": "array", "items": { "required": [ "custom_decision" ], "properties": { "custom_decision": { "description": "UID of the custom decision", "type": "integer", "example": 4 }, "value": { "description": "Grade given on the decision: 0 (none), 1 (A), 2 (B), 3 (C)", "type": "integer", "example": 1, "nullable": true, "enum": [ 0, 1, 2, 3 ] } }, "type": "object" } } }, "type": "object" }, "ContactInput": { "title": "ContactInput", "description": "Contact schema", "required": [ "company_contacts" ], "properties": { "first_name": { "type": "string", "nullable": true }, "last_name": { "type": "string", "nullable": true }, "profile_pic": { "description": "URL of the profile picture", "type": "string", "nullable": true }, "email": { "description": "Shortcut for a contact with a single email. Ignored if contact_emails is sent.", "type": "string", "format": "email", "example": "john@example.com", "nullable": true }, "contact_emails": { "description": "Full list of emails of the contact. On update this REPLACES the emails of the contact: an email which isn't in the list is removed. Don't send it (and don't send email) to leave the emails as they are.", "type": "array", "items": { "required": [ "email" ], "properties": { "id": { "description": "ID of an existing email of this contact", "type": "integer", "nullable": true }, "email": { "description": "Contact's email address", "type": "string", "format": "email", "example": "john@example.com" }, "main": { "description": "Main email of the contact. If none is marked, the first one is used.", "type": "boolean", "example": true, "nullable": true } }, "type": "object" } }, "address": { "properties": { "street": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "region": { "type": "string", "nullable": true }, "country": { "description": "Country name, alpha2Code or alpha3Code", "type": "string", "example": "US", "nullable": true }, "postal_code": { "type": "string", "nullable": true } }, "type": "object", "nullable": true }, "contact_phone_numbers": { "type": "array", "items": { "properties": { "id": { "type": "integer", "nullable": true }, "phone_number": { "type": "string", "nullable": false }, "main": { "type": "boolean", "nullable": true }, "name": { "type": "string", "nullable": true }, "call_line_type": { "$ref": "#/components/schemas/call_line_type_options" }, "call_line_note": { "type": "string", "nullable": true }, "call_line_status": { "$ref": "#/components/schemas/call_line_status_options" } }, "type": "object" } }, "contact_urls": { "description": "Urls of the contact (LinkedIn...). On update this REPLACES the urls of the contact. Don't send it to leave the urls as they are.", "type": "array", "items": { "type": "string", "nullable": true } }, "custom_fields": { "description": "Only the custom fields listed are changed, all others are left as they are. value null removes the value.", "type": "array", "items": { "required": [ "custom_field" ], "properties": { "custom_field": { "description": "UID of the custom field (see custom_fields?entity_type=CONTACT)", "type": "integer", "example": 12 }, "value": { "example": "Referral", "nullable": true } }, "type": "object" } }, "company_contacts": { "description": "Companies the contact works at. Required on create, with at least one connected company: a contact always belongs to a company. On update only the companies listed are changed.", "type": "array", "items": { "required": [ "company_id", "connected" ], "properties": { "company_id": { "type": "integer", "nullable": false }, "connected": { "description": "True connects the contact to the company (or updates the connection), false disconnects it.", "type": "boolean", "nullable": false }, "main_company": { "type": "boolean", "nullable": true }, "main_contact": { "type": "boolean", "nullable": true }, "working_contact": { "type": "boolean", "nullable": true }, "active_at_company": { "type": "boolean", "nullable": true }, "job_title": { "type": "string", "nullable": true }, "buying_role_id": { "type": "integer", "nullable": true } }, "type": "object" } } }, "type": "object" }, "Contact": { "title": "Contact", "description": "Contact schema", "properties": { "id": { "description": "Unique ID", "type": "integer", "example": 15 }, "first_name": { "type": "string", "nullable": true }, "last_name": { "type": "string", "nullable": true }, "profile_pic": { "description": "URL of the profile picture", "type": "string", "nullable": true }, "origin": { "$ref": "#/components/schemas/origin_options" }, "total_call_attempts": { "type": "integer", "example": 3, "nullable": true }, "best_lci": { "description": "Highest Line Connect Index (LCI) of the phone numbers of the contact: how likely a call is to reach the contact. Higher is better. The same number the app sorts its Call List by.", "type": "number", "example": 6.12, "nullable": true }, "contact_fields": { "description": "Custom fields of the contact", "type": "array", "items": { "properties": { "custom_field": { "description": "UID of the custom field", "type": "integer", "example": 12 }, "value": { "example": "Referral", "nullable": true } }, "type": "object" } }, "created_at": { "type": "string", "format": "date-time", "example": "2024-04-29T10:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2024-04-29T10:00:00Z" }, "contact_emails": { "type": "array", "items": { "properties": { "id": { "type": "integer", "nullable": true }, "email": { "description": "Contact's email address", "type": "string", "example": "john@example.com" }, "main": { "description": "Main email of the contact", "type": "boolean", "example": true }, "email_verified_on": { "description": "Date and time when the email was verified", "type": "string", "format": "date-time", "example": "2024-04-29T10:00:00Z" }, "email_status": { "$ref": "#/components/schemas/email_status_options" }, "email_type": { "$ref": "#/components/schemas/email_type_options" }, "is_catchall": { "description": "Indicates if the email is a catch-all", "type": "boolean" }, "email_verification_status": { "$ref": "#/components/schemas/email_verification_status_options" }, "email_score": { "description": "The % score of the email", "type": "integer", "format": "float", "example": 85 }, "total_emails_sent": { "description": "Total number of emails sent", "type": "integer", "example": 5 }, "total_emails_received": { "description": "Total number of emails received", "type": "integer", "example": 4 }, "total_emails_clicked": { "description": "Total number of emails clicked", "type": "integer", "example": 2 }, "first_sent": { "description": "The date and time the first email was sent", "type": "string", "format": "date-time", "example": "2022-01-01T00:00:00Z" }, "last_sent": { "description": "The date and time the last email was sent", "type": "string", "format": "date-time", "example": "2023-01-01T00:00:00Z" }, "first_received": { "description": "The date and time the first email was received", "type": "string", "format": "date-time", "example": "2022-01-01T01:00:00Z" }, "last_received": { "description": "The date and time the last email was received", "type": "string", "format": "date-time", "example": "2023-01-01T01:00:00Z" }, "last_click": { "description": "The date and time the last email was clicked", "type": "string", "format": "date-time", "example": "2023-01-01T02:00:00Z" }, "unsubscribed": { "description": "Indicates if the email has unsubscribed", "type": "boolean", "example": false } }, "type": "object" } }, "address": { "properties": { "street": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "region": { "type": "string", "nullable": true }, "country": { "description": "Country alpha2Code", "type": "string", "example": "US", "nullable": true }, "postal_code": { "type": "string", "nullable": true }, "longitude": { "type": "number", "nullable": true }, "latitude": { "type": "number", "nullable": true } }, "type": "object" }, "contact_phone_numbers": { "type": "array", "items": { "properties": { "id": { "type": "integer", "nullable": true }, "original_phone_number": { "description": "Original phone number", "type": "string", "example": "123-456-7890" }, "formatted_phone_number": { "description": "Formatted phone number", "type": "string", "example": "+1 (123) 456-7890" }, "name": { "description": "Name/Type of the phone number", "type": "string", "example": "Mobile" }, "description": { "description": "Description of the phone number", "type": "string", "example": "Peronal mobile line" }, "call_line_verified_on": { "description": "Date and time when the call line was verified", "type": "string", "format": "date-time", "example": "2024-04-29T10:00:00Z" }, "call_line_type": { "$ref": "#/components/schemas/call_line_type_options" }, "call_line_status": { "$ref": "#/components/schemas/call_line_status_options" }, "call_attempts": { "description": "Number of call attempts", "type": "integer", "example": 3 }, "lci": { "description": "Line Connect Index of this number: how likely a call on it is to reach the contact. Higher is better. ProspectSafari recalculates it after every logged call.", "type": "number", "example": 4.83 }, "country": { "description": "Country alpha2Code", "type": "string", "example": "US" }, "timezone": { "description": "Timezone associated with the phone number", "type": "string", "example": "['America/New_York']" }, "region": { "description": "Region associated with the phone number", "type": "string", "example": "North America" } }, "type": "object" } }, "contact_urls": { "type": "array", "items": { "type": "string", "nullable": true } }, "company_contacts": { "type": "array", "items": { "properties": { "company_id": { "description": "ID of the company associated with the contact", "type": "integer", "example": 123, "nullable": false }, "main_company": { "description": "Indicates if the company is the main one", "type": "boolean", "example": true, "nullable": false }, "main_contact": { "description": "Indicates if the contact is the main one for the company", "type": "boolean", "example": false, "nullable": false }, "working_contact": { "description": "Indicates if the contact is a working contact (Working contacts are included in deals and in various parts of sales process)", "type": "boolean", "example": true, "nullable": false }, "active_at_company": { "description": "Indicates if the contact is currently active at the company", "type": "boolean", "example": true, "nullable": false }, "job_title": { "description": "Job title of the contact", "type": "string", "example": "Marketing Manager", "nullable": true }, "buying_role_id": { "description": "Buying role associated with the contact", "type": "string", "example": "Decision Maker", "nullable": true } }, "type": "object" } } }, "type": "object" }, "custom_field_entity_type_options": { "description": "What the custom field is attached to", "type": "string", "example": "COMPANY", "enum": [ "COMPANY", "CONTACT", "DEAL" ] }, "custom_field_data_type_options": { "description": "Kind of value the custom field holds: 0 (Text), 1 (Select / Radio: one of the options), 2 (Numeric), 3 (Checkboxes: several of the options), 4 (Text with default options), 5 (Numeric with default options), 6 (Multi text).", "type": "integer", "example": 0, "enum": [ 0, 1, 2, 3, 4, 5, 6 ] }, "custom_field_availability_options": { "description": "Who can use the custom field inside ProspectSafari: 0 (Normal), 1 (Mandatory), 2 (Restricted edit), 3 (Restricted view and edit).", "type": "integer", "example": 0, "enum": [ 0, 1, 2, 3 ] }, "CustomField": { "properties": { "id": { "description": "Unique ID. This is the workspace_field_id (custom_field on companies) used in custom_fields.", "type": "integer", "example": 12 }, "name": { "type": "string", "example": "Lead source" }, "description": { "type": "string", "example": "Where the lead came from", "nullable": true }, "entity_type": { "$ref": "#/components/schemas/custom_field_entity_type_options" }, "data_type": { "$ref": "#/components/schemas/custom_field_data_type_options" }, "availability": { "$ref": "#/components/schemas/custom_field_availability_options" }, "options": { "description": "Options of the field, in order. Empty for fields without options.", "type": "array", "items": { "properties": { "id": { "type": "integer", "example": 40 }, "name": { "type": "string", "example": "Referral" } }, "type": "object" } } }, "type": "object" }, "deal_outcome_options": { "description": "Outcome of the deal. Which values are allowed depends on the type of the deal stage (see deal_stage_type_options): stage type 0 (Opportunity) allows 0 (Open), 1 (Try later), 2 (Unqualified), 3 (Lost). Stage type 1 (Deal) allows 7 (Open), 8 (Won), 9 (Lost). Stage type 2 (Prospect) allows 20 (Cold), 21 (Warm), 22 (Dead). If no outcome is sent the first one allowed on the stage is used.", "type": "integer", "example": 7, "enum": [ 0, 1, 2, 3, 7, 8, 9, 20, 21, 22 ] }, "DealCustomField": { "required": [ "custom_field" ], "properties": { "custom_field": { "description": "UID of the custom field (see custom_fields?entity_type=DEAL)", "type": "integer", "example": 12 }, "value": { "description": "Value of the custom field. Send null to clear it.", "example": "Referral", "nullable": true } }, "type": "object" }, "Deal": { "properties": { "id": { "description": "Unique ID", "type": "integer", "example": 1 }, "company_id": { "description": "UID of the company the deal belongs to.", "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Sample Deal" }, "description": { "type": "string", "example": "Deal description here", "nullable": true }, "value": { "description": "Value of the deal", "type": "integer", "example": 5000 }, "outcome": { "$ref": "#/components/schemas/deal_outcome_options" }, "outcome_name": { "description": "Readable name of the outcome", "type": "string", "example": "Open" }, "completed": { "description": "True when the deal is Won (8) or Lost (9)", "type": "boolean", "example": false }, "main": { "description": "Indicates if this is the main deal of the company. A company has at most one main deal.", "type": "boolean", "example": true }, "deal_pipeline_id": { "type": "integer", "example": 1 }, "deal_stage_id": { "type": "integer", "example": 3 }, "progress": { "description": "Progress through the pipeline, from 0 to 10000 (10000 = 100%). Calculated by ProspectSafari from stage weights and completed checklist steps.", "type": "number", "example": 2500 }, "probability": { "description": "Win probability from 0 to 10000 (10000 = 100%), calculated by ProspectSafari from the answers to the qualification questions (see GET /deals/{id}/qualification), weighted by your own past wins and losses.", "type": "integer", "example": 6200 }, "min_probability": { "description": "Lowest the probability can still become: every unanswered or Maybe question answered the worst way", "type": "integer", "example": 4100 }, "max_probability": { "description": "Highest the probability can still become: every unanswered or Maybe question answered the best way", "type": "integer", "example": 8300 }, "confidence": { "description": "How sure the probability is, from 0 to 10000: 10000 minus the gap between max_probability and min_probability (a 20% gap = 80% confidence). Rises as more questions are answered.", "type": "integer", "example": 5800 }, "date_time": { "description": "Date of the deal. Set automatically to the moment of completion when the deal becomes Won or Lost.", "type": "string", "format": "date-time", "example": "2024-04-29T10:00:00Z" }, "last_touched": { "type": "string", "format": "date-time", "example": "2024-04-29T10:00:00Z", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "example": "2024-04-29T10:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2024-04-29T10:00:00Z" }, "contacts": { "description": "UIDs of the contacts on the deal", "type": "array", "items": { "type": "integer", "example": 15 } }, "custom_fields": { "type": "array", "items": { "$ref": "#/components/schemas/DealCustomField" } } }, "type": "object" }, "DealInput": { "required": [ "name", "company_id", "deal_pipeline_id", "deal_stage_id", "contacts" ], "properties": { "name": { "description": "Name of the deal", "type": "string", "example": "Sample Deal" }, "company_id": { "description": "UID of the company the deal belongs to. Can't be changed after the deal is created.", "type": "integer", "example": 1 }, "deal_pipeline_id": { "description": "UID of the deal pipeline", "type": "integer", "example": 1 }, "deal_stage_id": { "description": "UID of the deal stage. Must belong to the deal pipeline.", "type": "integer", "example": 3 }, "contacts": { "description": "UIDs of the contacts on the deal. At least one. Every contact must already be connected to the company.", "type": "array", "items": { "type": "integer", "example": 15 } }, "description": { "type": "string", "example": "Deal description here", "nullable": true }, "value": { "description": "Value of the deal. 0 if not defined on create.", "type": "integer", "example": 5000 }, "outcome": { "$ref": "#/components/schemas/deal_outcome_options" }, "main": { "description": "Set as main deal of the company (the previous main deal stops being main). False if not defined on create.", "type": "boolean", "example": false }, "date_time": { "description": "Date of the deal. Now if not defined on create.", "type": "string", "format": "date-time", "example": "2024-04-29T10:00:00Z" }, "custom_fields": { "description": "Only the custom fields listed are changed, all others are left as they are.", "type": "array", "items": { "$ref": "#/components/schemas/DealCustomField" } } }, "type": "object" }, "DealChecklistStep": { "description": "A step of a checklist (same fields as ChecklistStep) together with where this deal stands on it.", "properties": { "id": { "description": "Unique ID of the step", "type": "integer", "example": 7 }, "order": { "type": "integer", "example": 0 }, "text": { "type": "string", "example": "Call the decision maker" }, "explanation": { "type": "string", "example": "Ask about their current supplier.", "nullable": true }, "type": { "$ref": "#/components/schemas/checklist_step_type_options" }, "priority": { "$ref": "#/components/schemas/task_priority_options" }, "due_date": { "$ref": "#/components/schemas/checklist_step_due_date_options" }, "task_queue_id": { "type": "integer", "example": 1, "nullable": true }, "task_owner": { "$ref": "#/components/schemas/checklist_step_task_owner_options" }, "task_user_workspace_id": { "type": "integer", "example": null, "nullable": true }, "contacts_visible_conditions": { "$ref": "#/components/schemas/checklist_step_contacts_conditions_options" }, "contacts_autoclick_conditions": { "$ref": "#/components/schemas/checklist_step_contacts_conditions_options" }, "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/ChecklistStepCondition" } }, "document_ids": { "description": "UIDs of the documents the Sales Coach shows while this is the next step (see GET /deals/{id}/documents)", "type": "array", "items": { "type": "integer" }, "example": [ 12 ] }, "applies": { "description": "False when the conditions of the step say it doesn't apply to this deal. Such a step can't be completed and isn't counted in the progress of the deal.", "type": "boolean", "example": true }, "completed": { "type": "boolean", "example": false }, "completed_on": { "type": "string", "format": "date-time", "example": "2024-04-30T09:00:00Z", "nullable": true }, "completed_by": { "description": "Who ticked the step off, e.g. USER (a person, or the API) or AUTO_CHECK (the conditions of the step)", "type": "string", "example": "USER", "nullable": true }, "task_id": { "description": "UID of the task (timeline item) this step created for the deal", "type": "integer", "example": 22, "nullable": true } }, "type": "object" }, "DealQualificationQuestion": { "description": "One qualification question, with the answers it accepts and the answer it has on this deal.", "properties": { "id": { "description": "ID of the question, used to answer it", "type": "integer", "example": 31 }, "section": { "description": "Name of the section of the questionnaire the question is in", "type": "string", "example": "Decision process", "nullable": true }, "question": { "type": "string", "example": "Have we met the economic buyer?" }, "explanation": { "type": "string", "example": "The person who signs off the budget, not the champion.", "nullable": true }, "type": { "description": "0 (Yes / Maybe / No), 1 (Scale 1 to 5), 2 (Evidence based: 5 descriptions, pick the one which fits), 3 (Strongly disagree to Strongly agree)", "type": "integer", "example": 0, "enum": [ 0, 1, 2, 3 ] }, "choices": { "description": "The answers this question accepts. Send the value to answer.", "type": "array", "items": { "properties": { "value": { "type": "integer", "example": 100 }, "label": { "type": "string", "example": "Yes" } }, "type": "object" } }, "applies": { "description": "False when the question depends on the answer to another question and that answer is not (yet) the one it needs. Such a question can't be answered.", "type": "boolean", "example": true }, "answer": { "description": "Value of the current answer, null when not answered", "type": "integer", "example": 100, "nullable": true }, "answer_label": { "type": "string", "example": "Yes", "nullable": true } }, "type": "object" }, "DealQualification": { "properties": { "deal_id": { "type": "integer", "example": 1 }, "deal_stage_id": { "description": "Stage the deal is in. The questionnaire is the one of this stage.", "type": "integer", "example": 3 }, "quiz_id": { "description": "Null when the stage has no questionnaire (questions is then empty)", "type": "integer", "example": 2, "nullable": true }, "name": { "type": "string", "example": "B2B qualification", "nullable": true }, "disabled": { "description": "True when the questionnaire can't be used (usually after the subscription was downgraded): answers are refused", "type": "boolean", "example": false }, "probability": { "description": "Same as on the deal", "type": "integer", "example": 6200 }, "min_probability": { "type": "integer", "example": 4100 }, "max_probability": { "type": "integer", "example": 8300 }, "confidence": { "type": "integer", "example": 5800 }, "questions": { "type": "array", "items": { "$ref": "#/components/schemas/DealQualificationQuestion" } } }, "type": "object" }, "DealChecklist": { "properties": { "deal_id": { "type": "integer", "example": 1 }, "deal_stage_id": { "description": "Stage the deal is in right now. The checklist is the one of this stage.", "type": "integer", "example": 3 }, "checklist_id": { "description": "Null when the stage has no checklist (steps is then empty)", "type": "integer", "example": 4, "nullable": true }, "name": { "type": "string", "example": "Qualification", "nullable": true }, "progress": { "description": "Progress of the deal through its pipeline, from 0 to 10000 (same value as on the deal)", "type": "number", "example": 2500 }, "steps": { "type": "array", "items": { "$ref": "#/components/schemas/DealChecklistStep" } } }, "type": "object" }, "DealDocumentReason": { "description": "One reason the Sales Coach shows the document for this deal.", "properties": { "source": { "description": "CHECKLIST_STEP: attached to the next step of the checklist of the deal. DEAL_STAGE: attached to the stage the deal is in. CUSTOM_FIELD: attached to an option of a custom field which the deal, its company or one of its contacts has as value. CUSTOM_DEAL_FIELD / CUSTOM_CONTACT_FIELD: attached to an option of the older custom deal and contact fields.", "type": "string", "example": "DEAL_STAGE", "enum": [ "CHECKLIST_STEP", "DEAL_STAGE", "CUSTOM_FIELD", "CUSTOM_DEAL_FIELD", "CUSTOM_CONTACT_FIELD" ] }, "id": { "description": "ID of the step, stage, custom field or option", "type": "integer", "example": 3 }, "name": { "description": "Its text or name (for a custom field: the option)", "type": "string", "example": "Proposal sent" } }, "type": "object" }, "DealDocument": { "description": "A document (same fields as in GET /documents, without html and used_in) and why the Sales Coach shows it for this deal.", "properties": { "id": { "type": "integer", "example": 12 }, "name": { "type": "string", "example": "Pricing one-pager" }, "notes": { "type": "string", "example": "Send after the discovery call, before the proposal." }, "type": { "$ref": "#/components/schemas/document_type_options" }, "public": { "description": "True when the team marked it for sharing with customers", "type": "boolean", "example": false }, "disabled": { "type": "boolean", "example": false }, "url": { "description": "Where the document opens (for anyone when public, otherwise only for a logged-in member of the workspace)", "type": "string", "example": "https://app.prospectsafari.com/document/Xy7..." }, "link": { "type": "string", "example": null, "nullable": true }, "shown_because": { "type": "array", "items": { "$ref": "#/components/schemas/DealDocumentReason" } } }, "type": "object" }, "DealDocuments": { "properties": { "deal_id": { "type": "integer", "example": 1 }, "deal_stage_id": { "type": "integer", "example": 3 }, "documents": { "description": "Each document once, in the order the Resources tab shows them: the next checklist step first, then the stage, then the custom fields", "type": "array", "items": { "$ref": "#/components/schemas/DealDocument" } } }, "type": "object" }, "deal_stage_type_options": { "description": "Type of the deal stage: 0 (Opportunity), 1 (Deal), 2 (Prospect). The type decides which outcomes a deal can have while it is in this stage, see deal_outcome_options.", "type": "integer", "example": 1, "enum": [ 0, 1, 2 ] }, "DealStage": { "properties": { "id": { "description": "Unique ID", "type": "integer", "example": 3 }, "name": { "type": "string", "example": "Proposal sent" }, "description": { "type": "string", "example": "Stage description here", "nullable": true }, "customer_value_description": { "type": "string", "example": "What the customer gets out of this stage", "nullable": true }, "type": { "$ref": "#/components/schemas/deal_stage_type_options" }, "order": { "description": "Position of the stage inside the pipeline (starts at 0)", "type": "integer", "example": 2 }, "weight": { "description": "Share of the pipeline this stage represents. The weights of all stages of a pipeline add up to 10000 (= 100%).", "type": "integer", "example": 2500 }, "checklist_id": { "description": "UID of the checklist applied to deals in this stage", "type": "integer", "example": 4, "nullable": true }, "quiz_id": { "description": "UID of the qualification quiz deals in this stage answer (GET /deals/{id}/qualification). Set through quiz_id of the pipeline, which gives every stage the same quiz.", "type": "integer", "example": 2, "nullable": true }, "document_ids": { "description": "UIDs of the documents the Sales Coach shows for deals in this stage (see documents)", "type": "array", "items": { "type": "integer" }, "example": [ 12, 15 ] } }, "type": "object" }, "DealPipeline": { "properties": { "id": { "description": "Unique ID", "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Sales pipeline" }, "description": { "type": "string", "example": "Pipeline description here", "nullable": true }, "active": { "type": "boolean", "example": true }, "default": { "description": "Indicates if this is the default pipeline of the workspace", "type": "boolean", "example": true }, "quiz_id": { "description": "UID of the qualification quiz of the pipeline (see quizzes), null for none", "type": "integer", "example": 2, "nullable": true }, "deal_stages": { "description": "Stages of the pipeline, in order", "type": "array", "items": { "$ref": "#/components/schemas/DealStage" } } }, "type": "object" }, "DealStageInput": { "properties": { "id": { "description": "Only on update: the id of an existing stage to keep. Its fields you don't send keep their value. Leave it out for a new stage.", "type": "integer", "example": 3 }, "name": { "description": "Required for a new stage", "type": "string", "example": "Proposal sent", "maxLength": 255 }, "description": { "type": "string", "example": "Stage description here", "nullable": true, "maxLength": 255 }, "customer_value_description": { "type": "string", "example": "What the customer gets out of this stage", "nullable": true, "maxLength": 255 }, "type": { "$ref": "#/components/schemas/deal_stage_type_options" }, "weight": { "description": "Size of the stage compared with the other stages of the list. They are scaled so they add up to 10000. Left out: an existing stage keeps its current weight (already on the 10000 scale), a new stage gets the average of the others.", "type": "number", "example": 25, "minimum": 0 }, "checklist_id": { "description": "UID of the checklist for deals in this stage (see checklists), null for none. Changing it removes, in the background, the open tasks the deals of this stage had from the old checklist.", "type": "integer", "example": 4, "nullable": true }, "document_ids": { "description": "UIDs of the documents the Sales Coach shows for deals in this stage (see documents). The list replaces the current one, an empty list removes them all. Left out: an existing stage keeps its documents.", "type": "array", "items": { "type": "integer" }, "example": [ 12, 15 ], "maxItems": 20 } }, "type": "object" }, "DealPipelineInput": { "required": [ "name", "description", "deal_stages" ], "properties": { "name": { "type": "string", "example": "Sales pipeline", "maxLength": 255 }, "description": { "type": "string", "example": "Pipeline description here", "maxLength": 2000 }, "active": { "description": "False hides the pipeline when new deals are created in ProspectSafari. True if not defined on create.", "type": "boolean", "example": true }, "default": { "description": "The pipeline ProspectSafari offers first for a new deal. False if not defined on create.", "type": "boolean", "example": false }, "quiz_id": { "description": "UID of the qualification quiz the deals of this pipeline answer (see quizzes), null for none. Every stage gets it. Changing it from one quiz to another recalculates the win probability of the deals.", "type": "integer", "example": 2, "nullable": true }, "deal_stages": { "description": "All the stages, in order. On update the list you send replaces the current one: keep a stage by sending its id, add one by leaving id out, remove one by leaving it out of the list (refused while deals are in it).", "type": "array", "items": { "$ref": "#/components/schemas/DealStageInput" }, "maxItems": 50, "minItems": 1 } }, "type": "object" }, "document_type_options": { "description": "What the document is: TEXT (written in the text editor, html), DESIGN (built with the drag and drop editor of ProspectSafari, html), PDF (an uploaded file) or LINK (a page elsewhere, e.g. a Google Doc, opened from link). The type is set when the document is created and never changes.", "type": "string", "example": "TEXT", "enum": [ "TEXT", "DESIGN", "PDF", "LINK" ] }, "DocumentUse": { "description": "Where the document is attached, so the Sales Coach shows it to the salesperson.", "properties": { "deal_stages": { "description": "Pipeline stages which show it to every deal in the stage", "type": "array", "items": { "properties": { "deal_pipeline_id": { "type": "integer", "example": 1 }, "deal_stage_id": { "type": "integer", "example": 3 } }, "type": "object" } }, "checklist_steps": { "description": "Checklist steps which show it while the step is the next one to do", "type": "array", "items": { "properties": { "checklist_id": { "type": "integer", "example": 4 }, "checklist_step_id": { "type": "integer", "example": 7 } }, "type": "object" } } }, "type": "object" }, "Document": { "properties": { "id": { "description": "Unique ID", "type": "integer", "example": 12 }, "name": { "type": "string", "example": "Pricing one-pager" }, "notes": { "description": "What the document is for and when to use it. The salesperson sees it next to the name.", "type": "string", "example": "Send after the discovery call, before the proposal." }, "type": { "$ref": "#/components/schemas/document_type_options" }, "public": { "description": "True when the team marked it for sharing with customers (ProspectSafari then offers Share for it): its url opens for anyone. A private document only opens for a logged-in member of the workspace.", "type": "boolean", "example": false }, "disabled": { "description": "True when the document can't be opened or changed (usually after the subscription was downgraded)", "type": "boolean", "example": false }, "url": { "description": "Where the document opens (the html, the PDF, or a redirect to link). A public document opens for anyone who has the address, a private one only for a logged-in member of the workspace. The address is long and random, so it can't be guessed.", "type": "string", "example": "https://app.prospectsafari.com/document/Xy7..." }, "link": { "description": "Only for type LINK: the address it points to", "type": "string", "example": "https://docs.google.com/document/d/1AbC/preview", "nullable": true }, "html": { "description": "Only on GET /documents/{id}, for types TEXT and DESIGN: the content", "type": "string", "example": "

Pricing

Starter: 49 per month

", "nullable": true }, "used_in": { "$ref": "#/components/schemas/DocumentUse" }, "created_at": { "type": "string", "format": "date-time", "example": "2024-04-29T10:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2024-04-29T10:00:00Z" } }, "type": "object" }, "DocumentInput": { "required": [ "name", "notes" ], "properties": { "name": { "type": "string", "example": "Pricing one-pager", "maxLength": 255 }, "notes": { "description": "What the document is for and when to use it", "type": "string", "example": "Send after the discovery call, before the proposal.", "maxLength": 5000 }, "public": { "description": "Marks the document for sharing with customers. False if not defined on create.", "type": "boolean", "example": false }, "html": { "description": "Creates a TEXT document with this content. On update: the new content of a TEXT document. Cleaned before it is stored (scripts, forms and event handlers are removed).", "type": "string", "example": "

Pricing

Starter: 49 per month

" }, "link": { "description": "Creates a LINK document: an http(s) address. A Google Docs address is turned into its /preview address, like ProspectSafari does, so it can be shown inside the app. On update: the new address of a LINK document.", "type": "string", "example": "https://docs.google.com/document/d/1AbC/edit", "maxLength": 255 } }, "type": "object" }, "DocumentUploadInput": { "required": [ "name", "notes", "pdf" ], "properties": { "name": { "type": "string", "example": "Case study", "maxLength": 255 }, "notes": { "type": "string", "example": "For prospects in retail.", "maxLength": 5000 }, "public": { "description": "1 marks the document for sharing with customers (in a form, send 1 or 0, not true / false)", "type": "integer", "example": 0, "enum": [ 0, 1 ] }, "pdf": { "description": "The PDF file, 5 MB at most", "type": "string", "format": "binary" } }, "type": "object" }, "sequence_wait_unit_options": { "description": "Unit of wait. The longest wait is one year: 31536000 SECONDS, 525600 MINUTES, 8760 HOURS, 365 DAYS, 52 WEEKS or 12 MONTHS.", "type": "string", "example": "DAYS", "enum": [ "SECONDS", "MINUTES", "HOURS", "DAYS", "WEEKS", "MONTHS" ] }, "EmailSequenceEmail": { "properties": { "order": { "description": "Position of the email inside the sequence (starts at 0)", "type": "integer", "example": 1 }, "template_id": { "description": "UID of the email template sent at this step", "type": "integer", "example": 1 }, "wait": { "description": "How long after the previous email this one goes out. Not used for the first email: it goes out when the sequence is started.", "type": "integer", "example": 3 }, "wait_unit": { "$ref": "#/components/schemas/sequence_wait_unit_options" } }, "type": "object" }, "EmailSequence": { "properties": { "id": { "description": "Unique ID", "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Cold outreach" }, "description": { "type": "string", "example": "Three emails over a week", "nullable": true }, "emails": { "description": "The emails of the sequence, in the order they go out", "type": "array", "items": { "$ref": "#/components/schemas/EmailSequenceEmail" } }, "created_at": { "type": "string", "format": "date-time", "example": "2024-04-29T10:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2024-04-29T10:00:00Z" } }, "type": "object" }, "EmailSequenceEmailInput": { "required": [ "template_id" ], "properties": { "template_id": { "description": "UID of an email template you can use (see email_templates)", "type": "integer", "example": 1 }, "wait": { "description": "Required for every email after the first: how long after the previous email this one goes out. Ignored on the first email.", "type": "integer", "example": 3, "minimum": 0 }, "wait_unit": { "$ref": "#/components/schemas/sequence_wait_unit_options" } }, "type": "object" }, "EmailSequenceInput": { "required": [ "name", "description", "emails" ], "properties": { "name": { "type": "string", "example": "Cold outreach", "maxLength": 255 }, "description": { "type": "string", "example": "Three emails over a week", "maxLength": 1000 }, "emails": { "description": "All the emails of the sequence, in the order they go out. On update the list you send replaces the current one.", "type": "array", "items": { "$ref": "#/components/schemas/EmailSequenceEmailInput" }, "maxItems": 100, "minItems": 1 } }, "type": "object" }, "email_template_type_options": { "description": "TEXT_TEMPLATE: written as text, can be edited through the API. HTML_TEMPLATE: built with the visual editor of ProspectSafari. AI_TEMPLATE: instructions for the AI which writes the email.", "type": "string", "example": "TEXT_TEMPLATE", "enum": [ "TEXT_TEMPLATE", "HTML_TEMPLATE", "AI_TEMPLATE" ] }, "EmailTemplate": { "properties": { "id": { "description": "Unique ID", "type": "integer", "example": 1 }, "name": { "type": "string", "example": "First contact" }, "subject": { "type": "string", "example": "Quick question" }, "html": { "description": "Body of the email (HTML)", "type": "string", "example": "

Hi, I came across your company and...

" }, "notes": { "description": "Internal notes about the template, never sent", "type": "string", "example": "Use for cold outreach", "nullable": true }, "template_type": { "$ref": "#/components/schemas/email_template_type_options" }, "visual_editor": { "description": "True when the template was built with the visual editor. The html of such a template can't be changed through the API: the editor would overwrite it the next time the template is opened.", "type": "boolean", "example": false }, "workspace_share": { "description": "True: every team member can use the template. False: only its owner. Becomes true when the template is put in an email sequence.", "type": "boolean", "example": true }, "reply_to_address": { "type": "string", "format": "email", "example": "sales@samplecompany.com", "nullable": true }, "user_workspace_id": { "description": "UID of the team member who owns the template", "type": "integer", "example": 2, "nullable": true }, "has_pending_emails": { "description": "True when emails using this template are scheduled and not sent yet. Changing the template changes those emails.", "type": "boolean", "example": false }, "created_at": { "type": "string", "format": "date-time", "example": "2024-04-29T10:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2024-04-29T10:00:00Z" } }, "type": "object" }, "EmailTemplateInput": { "required": [ "name", "subject", "html" ], "properties": { "name": { "description": "Name of the template", "type": "string", "example": "First contact" }, "subject": { "description": "Subject of the email", "type": "string", "example": "Quick question" }, "html": { "description": "Body of the email (HTML)", "type": "string", "example": "

Hi, I came across your company and...

" }, "notes": { "description": "Internal notes about the template, never sent", "type": "string", "example": "Use for cold outreach", "nullable": true }, "workspace_share": { "description": "True: every team member can use the template. False if not defined on create. Only the owner of a template can change this.", "type": "boolean", "example": true }, "reply_to_address": { "type": "string", "format": "email", "example": "sales@samplecompany.com", "nullable": true } }, "type": "object" }, "CompanyList": { "properties": { "id": { "description": "Unique ID", "type": "integer", "example": 1 }, "name": { "type": "string", "example": "First list" }, "user_workspace_id": { "description": "UID of the team member who owns the list", "type": "integer", "example": 2, "nullable": true }, "companies_count": { "description": "Number of companies in the list", "type": "integer", "example": 120 }, "created_at": { "type": "string", "format": "date-time", "example": "2024-04-29T10:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2024-04-29T10:00:00Z" } }, "type": "object" }, "MessageType": { "properties": { "value": { "description": "This is the message_type used to log a message", "type": "string", "example": "WHATSAPP" }, "name": { "description": "Readable name", "type": "string", "example": "WhatsApp" } }, "type": "object" }, "quiz_question_type_options": { "description": "Type of the question, which decides the answers it accepts on a deal: 0 (Yes / Maybe / No: 100 / 50 / 0), 1 (Scale 1 to 5: 0, 25, 50, 75, 100), 2 (Evidence based: 5 descriptions of what you can observe, from least to most, answered 0, 25, 50, 75, 100), 3 (Strongly disagree to Strongly agree: 0, 25, 50, 75, 100).", "type": "integer", "example": 0, "enum": [ 0, 1, 2, 3 ] }, "QuizQuestion": { "properties": { "id": { "description": "Unique ID. The same id answers the question on a deal (PUT /deals/{id}/qualification/{question_id}).", "type": "integer", "example": 31 }, "number": { "description": "Position of the question in the whole quiz, starting at 1, as ProspectSafari numbers them", "type": "integer", "example": 1 }, "question": { "type": "string", "example": "Is the budget confirmed?" }, "explanation": { "description": "Html. What to look for, shown to the salesperson next to the question.", "type": "string", "example": "

Signed off by finance, not just mentioned.

", "nullable": true }, "type": { "$ref": "#/components/schemas/quiz_question_type_options" }, "evidence": { "description": "Only for type 2: the 5 descriptions, from least (answer 0) to most (answer 100). An empty one is shown as Evidence 1..5.", "type": "array", "items": { "type": "string", "nullable": true }, "example": [ "Never met", "Heard of", "Met once", "Engaged", "Sponsoring" ], "nullable": true }, "condition": { "description": "The question only applies to a deal when an earlier Yes / Maybe / No question got this answer. Null: it always applies.", "properties": { "question_id": { "description": "ID of the question it depends on", "type": "integer", "example": 31 }, "question_number": { "description": "Number of that question in the quiz (1 = the first question)", "type": "integer", "example": 1 }, "answer": { "description": "The answer it needs: 100 (Yes), 50 (Maybe) or 0 (No)", "type": "integer", "example": 100, "enum": [ 0, 50, 100 ] } }, "type": "object", "nullable": true }, "positive_weighting": { "description": "How much a high answer raises the win probability, 0 to 10000. ProspectSafari learns it from the won and lost deals of the workspace.", "type": "integer", "example": 2500 }, "negative_weighting": { "description": "How much a low answer lowers the win probability, 0 to 10000, learned the same way", "type": "integer", "example": 2500 } }, "type": "object" }, "QuizSection": { "properties": { "name": { "type": "string", "example": "Decision process" }, "order": { "description": "Position of the section in the quiz (starts at 0)", "type": "integer", "example": 0 }, "questions": { "type": "array", "items": { "$ref": "#/components/schemas/QuizQuestion" } } }, "type": "object" }, "Quiz": { "properties": { "id": { "description": "Unique ID", "type": "integer", "example": 2 }, "name": { "type": "string", "example": "B2B qualification" }, "description": { "type": "string", "example": "Qualify every deal before the proposal" }, "disabled": { "description": "True when the quiz can't be used or changed (usually after the subscription was downgraded)", "type": "boolean", "example": false }, "brier_skill_score": { "description": "How well the quiz has predicted the won and lost deals so far: 10000 = perfectly, 0 = no better than guessing, below 0 = worse. Null until it has been calculated once.", "type": "integer", "example": 3200, "nullable": true }, "deal_pipeline_ids": { "description": "The pipelines whose deals answer this quiz", "type": "array", "items": { "type": "integer" }, "example": [ 1 ] }, "sections": { "description": "The sections, in order, with their questions", "type": "array", "items": { "$ref": "#/components/schemas/QuizSection" } }, "created_at": { "type": "string", "format": "date-time", "example": "2024-04-29T10:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2024-04-29T10:00:00Z" } }, "type": "object" }, "QuizQuestionInput": { "properties": { "id": { "description": "Only on update: the id of an existing question to keep. It keeps the answers deals gave to it and its learned weights; its fields you don't send keep their value. Leave it out for a new question.", "type": "integer", "example": 31 }, "question": { "description": "Required for a new question", "type": "string", "example": "Is the budget confirmed?", "maxLength": 255 }, "explanation": { "description": "Html, cleaned before it is stored", "type": "string", "example": "

Signed off by finance, not just mentioned.

", "nullable": true, "maxLength": 3000 }, "type": { "$ref": "#/components/schemas/quiz_question_type_options" }, "evidence": { "description": "Only for type 2: up to 5 descriptions, from least to most", "type": "array", "items": { "type": "string", "maxLength": 255 }, "example": [ "Never met", "Heard of", "Met once", "Engaged", "Sponsoring" ], "nullable": true, "maxItems": 5 }, "condition": { "description": "Makes the question apply only when an earlier question got a certain answer. null removes the condition.", "properties": { "question_number": { "description": "Number of an earlier question of type 0 (Yes / Maybe / No) in the list you send, counting through all sections from 1", "type": "integer", "example": 1, "minimum": 1 }, "answer": { "description": "100 (Yes), 50 (Maybe) or 0 (No)", "type": "integer", "example": 100, "enum": [ 0, 50, 100 ] } }, "type": "object", "nullable": true } }, "type": "object" }, "QuizSectionInput": { "required": [ "name", "questions" ], "properties": { "name": { "type": "string", "example": "Decision process", "maxLength": 255 }, "questions": { "type": "array", "items": { "$ref": "#/components/schemas/QuizQuestionInput" }, "maxItems": 100, "minItems": 1 } }, "type": "object" }, "QuizInput": { "required": [ "name", "description", "sections" ], "properties": { "name": { "type": "string", "example": "B2B qualification", "maxLength": 255 }, "description": { "type": "string", "example": "Qualify every deal before the proposal", "maxLength": 3000 }, "sections": { "description": "All the sections with all their questions, in order (200 questions at most). On update the list you send replaces the current one: keep a question by sending its id, add one by leaving id out, delete one by leaving it out (the answers deals gave to it go too).", "type": "array", "items": { "$ref": "#/components/schemas/QuizSectionInput" }, "maxItems": 50, "minItems": 1 } }, "type": "object" }, "SendingAddress": { "properties": { "id": { "description": "Unique ID. This is the from_id used to create an email.", "type": "integer", "example": 5 }, "email": { "type": "string", "format": "email", "example": "jane@samplecompany.com" } }, "type": "object" }, "status_options": { "description": "Current lead status", "type": "string", "example": "NEW", "enum": [ "NONE", "NEW", "CONTACTED", "IN_PROGRESS", "OPEN_DEAL", "UNQUALIFIED", "ATTEMPTED_TO_CONTACT", "BAD_TIMING", "DEAL_WON", "DEAL_LOST", "NOT_INTERESTED" ] }, "origin_options": { "description": "Origin of the object", "type": "string", "example": "CSV_UPLOAD", "enum": [ "MANUAL", "CSV_UPLOAD", "API_REQUEST", "EXTENSION", "AUTOMATED_SEARCH", "HUBSPOT", "LIST_SHARE", "JUMPSTART", "TOMBA", "SCRAPED", "PROSPECTSAFARI_EMAIL_ADDON" ] }, "email_type_options": { "description": "Defines what type the email is.", "type": "string", "example": "TEMPORARY", "enum": [ "WEBMAIL", "TEMPORARY", "GENERIC", "BUSINESS" ] }, "email_status_options": { "description": "Defines the current delivery status of the email.", "type": "string", "example": "DELIVERED", "enum": [ "NONE", "DELIVERED", "OPENED", "CLICKED", "SOFT_BOUNCED", "BOUNCED", "RECEIVED", "UNSUBSCRIBED", "SPAM_COMPLAINT", "UNRESPONSIVE" ] }, "email_verification_status_options": { "description": "Defines the verification status of this email. This is independent from the delivery status.", "type": "string", "example": "VERY_RISKY", "enum": [ "INVALID", "VERY_RISKY", "RISKY", "VERIFIED", "UNKNOWN" ] }, "call_line_type_options": { "description": "Defines call line type (Direct line, Gatekeeper line, Menu or Invalid).", "type": "string", "example": "DIRECT", "enum": [ "UNKNOWN", "DIRECT", "GATEKEEPER", "MENU", "INVALID" ] }, "call_line_status_options": { "description": "Defines if the line is Verified or not.", "type": "string", "example": "VERIFIED", "enum": [ "NOT_VERIFIED", "VERIFIED", "BAD_NUMBER" ] }, "ValidationError": { "required": [ "message", "errors" ], "properties": { "message": { "description": "General error message explaining what went wrong during validation.", "type": "string", "example": "The given data was invalid." }, "errors": { "description": "Field-specific validation errors: one list of messages per field.", "type": "object", "example": { "website": [ "The website has already been taken." ] }, "additionalProperties": { "type": "array", "items": { "type": "string" }, "description": "List of specific validation errors for each field." } } }, "type": "object" }, "Error": { "required": [ "message" ], "properties": { "message": { "description": "Human readable explanation of what went wrong.", "type": "string", "example": "Deal not found" } }, "type": "object" }, "Pagination": { "properties": { "page": { "description": "Current page (starts at 1)", "type": "integer", "example": 1 }, "per_page": { "description": "Items per page", "type": "integer", "example": 25 }, "total": { "description": "Total items matching the filters", "type": "integer", "example": 240 }, "total_pages": { "description": "Total pages available", "type": "integer", "example": 10 } }, "type": "object" }, "TaskQueue": { "properties": { "id": { "description": "Unique ID", "type": "integer", "example": 1 }, "name": { "type": "string", "example": "Calls" }, "user_workspace_id": { "description": "UID of the team member who created the queue", "type": "integer", "example": 2, "nullable": true }, "created_at": { "type": "string", "format": "date-time", "example": "2024-04-29T10:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2024-04-29T10:00:00Z" } }, "type": "object" }, "TeamMember": { "properties": { "id": { "description": "Unique ID. This is the user_workspace_id used everywhere else in the API.", "type": "integer", "example": 2 }, "first_name": { "type": "string", "example": "Jane", "nullable": true }, "last_name": { "type": "string", "example": "Smith", "nullable": true }, "email": { "type": "string", "example": "jane@samplecompany.com", "nullable": true }, "admin": { "description": "Indicates if the team member is an admin of the workspace", "type": "boolean", "example": false }, "api_key_owner": { "description": "True on the team member who owns the API key of this request. It is the team member the API acts as.", "type": "boolean", "example": true } }, "type": "object" }, "timeline_item_type_options": { "description": "Type of the timeline item", "type": "string", "example": "notes", "enum": [ "emails", "phone_calls", "notes", "meetings", "tasks", "messages" ] }, "TimelineItem": { "properties": { "id": { "description": "Unique ID", "type": "integer", "example": 1 }, "type": { "$ref": "#/components/schemas/timeline_item_type_options" }, "sub_type": { "description": "Number of the sub type. Its meaning depends on the type, sub_type_name holds the readable name.", "type": "integer", "example": 0, "nullable": true }, "sub_type_name": { "description": "Readable name of the sub type. For notes: NORMAL, PINNED or RESOURCE.", "type": "string", "example": "NORMAL", "nullable": true }, "date_time": { "description": "Moment the item happened, or is due / scheduled.", "type": "string", "format": "date-time", "example": "2024-04-29T10:00:00Z" }, "content": { "description": "Text of the item (can contain HTML)", "type": "string", "example": "Spoke with John, call back in May.", "nullable": true }, "company_id": { "type": "integer", "example": 1, "nullable": true }, "contact_id": { "type": "integer", "example": 15, "nullable": true }, "deal_id": { "type": "integer", "example": 4, "nullable": true }, "user_workspace_id": { "description": "UID of the team member the item belongs to", "type": "integer", "example": 2, "nullable": true }, "created_at": { "type": "string", "format": "date-time", "example": "2024-04-29T10:00:00Z" }, "updated_at": { "type": "string", "format": "date-time", "example": "2024-04-29T10:00:00Z" }, "phone_call": { "description": "Only on items of type phone_calls, null on every other type.", "properties": { "contact_phone_number_id": { "description": "UID of the phone number which was called", "type": "integer", "example": 31, "nullable": true }, "phone_number": { "description": "The number as it was at the moment of the call", "type": "string", "example": "+1 123-456-7890" }, "attempt": { "description": "Which call attempt on this phone number this was", "type": "integer", "example": 2 } }, "type": "object", "nullable": true }, "task": { "description": "Only on items of type tasks, null on every other type. On a task date_time is the moment the task is due.", "properties": { "task_queue_id": { "description": "UID of the task queue the task sits in", "type": "integer", "example": 1 }, "priority": { "$ref": "#/components/schemas/task_priority_options" }, "completed": { "type": "boolean", "example": false }, "completed_on": { "type": "string", "format": "date-time", "example": "2024-04-30T09:00:00Z", "nullable": true } }, "type": "object", "nullable": true }, "email": { "description": "Only on items of type emails, null on every other type. sub_type_name tells where the email stands: EMAIL_SCHEDULED (waiting to be sent at date_time), EMAIL_SENT, EMAIL_RECEIVED, EMAIL_SCHEDULED_CANCELED or EMAIL_SCHEDULED_PAUSED.", "properties": { "from": { "type": "string", "example": "jane@samplecompany.com", "nullable": true }, "to": { "type": "string", "example": "john@example.com", "nullable": true }, "subject": { "type": "string", "example": "Quick question", "nullable": true } }, "type": "object", "nullable": true }, "message": { "description": "Only on items of type messages, null on every other type. sub_type 0 is a message you sent, 1 a message you received.", "properties": { "message_type": { "description": "Kind of message (see message_types)", "type": "string", "example": "WHATSAPP", "nullable": true }, "contact_phone_number_id": { "type": "integer", "example": 31, "nullable": true } }, "type": "object", "nullable": true }, "meeting": { "description": "Only on items of type meetings, null on every other type. On a meeting date_time is the moment it starts and sub_type how it is held: 0 (Phone call), 1 (Video call), 2 (Location).", "properties": { "title": { "type": "string", "example": "Intro call", "nullable": true }, "status": { "$ref": "#/components/schemas/meeting_status_options" }, "duration": { "description": "Minutes", "type": "integer", "example": 30, "nullable": true }, "meeting_link": { "type": "string", "example": "https://meet.google.com/abc-defg-hij", "nullable": true }, "contact_ids": { "description": "UIDs of the contacts attending: what you send as contact_ids when you create or update the meeting.", "type": "array", "items": { "type": "integer", "example": 15 } }, "calendar_synced": { "description": "True when the meeting was connected to a Google / Outlook calendar inside ProspectSafari. Such a meeting can't be changed or deleted through the API.", "type": "boolean", "example": false } }, "type": "object", "nullable": true } }, "type": "object" }, "meeting_status_options": { "description": "Where the meeting stands. When you move a SCHEDULED, CONFIRMED or ALL_DECLINED meeting to another date_time ProspectSafari sets it to RESCHEDULED by itself.", "type": "string", "example": "SCHEDULED", "enum": [ "SCHEDULED", "CONFIRMED", "RESCHEDULED", "CANCELLED", "NO_SHOW", "COMPLETED", "ALL_DECLINED" ] }, "MessageInput": { "required": [ "company_id", "contact_id", "message_type", "sub_type", "content" ], "properties": { "company_id": { "description": "UID of the company the message is about. Can't be changed after the message is created.", "type": "integer", "example": 1 }, "contact_id": { "description": "UID of the contact the message was exchanged with. Must be connected to the company.", "type": "integer", "example": 15 }, "message_type": { "description": "Kind of message: the value of one of the message_types", "type": "string", "example": "WHATSAPP" }, "sub_type": { "description": "0 (a message you sent), 1 (a message you received)", "type": "integer", "example": 0, "enum": [ 0, 1 ] }, "content": { "description": "Text of the message (can contain HTML)", "type": "string", "example": "Hi John, are you free for a call on Tuesday?" }, "contact_phone_number_id": { "description": "UID of the phone number the message went to / came from. Must be a phone number of the contact.", "type": "integer", "example": 31, "nullable": true }, "deal_id": { "description": "UID of the deal the message is about. Must be a deal of the company.", "type": "integer", "example": 4, "nullable": true }, "user_workspace_id": { "description": "UID of the team member the message belongs to. The owner of the API key if not defined on create.", "type": "integer", "example": 2 }, "date_time": { "description": "Moment of the message. Now if not defined on create.", "type": "string", "format": "date-time", "example": "2024-04-29T10:00:00Z" } }, "type": "object" }, "MeetingInput": { "required": [ "company_id", "sub_type", "date_time", "title", "duration" ], "properties": { "company_id": { "description": "UID of the company the meeting is with. Can't be changed after the meeting is created.", "type": "integer", "example": 1 }, "sub_type": { "description": "How the meeting is held: 0 (Phone call), 1 (Video call), 2 (Location)", "type": "integer", "example": 1, "enum": [ 0, 1, 2 ] }, "date_time": { "description": "Moment the meeting starts", "type": "string", "format": "date-time", "example": "2024-04-29T10:00:00Z" }, "title": { "type": "string", "example": "Intro call" }, "duration": { "description": "Minutes", "type": "integer", "example": 30 }, "status": { "$ref": "#/components/schemas/meeting_status_options" }, "meeting_link": { "description": "Link of the video call", "type": "string", "example": "https://meet.google.com/abc-defg-hij", "nullable": true }, "content": { "description": "Notes about the meeting (can contain HTML)", "type": "string", "example": "Agenda: pricing, next steps.", "nullable": true }, "contact_id": { "description": "UID of the main contact of the meeting. Must be connected to the company. Send null on update to remove it.", "type": "integer", "example": 15, "nullable": true }, "contact_ids": { "description": "UIDs of the contacts attending. On update this REPLACES the attendees. Don't send it to leave them as they are.", "type": "array", "items": { "type": "integer", "example": 15 }, "nullable": true }, "deal_id": { "description": "UID of the deal the meeting is about. Must be a deal of the company.", "type": "integer", "example": 4, "nullable": true }, "user_workspace_id": { "description": "UID of the team member who holds the meeting. The owner of the API key if not defined on create.", "type": "integer", "example": 2 } }, "type": "object" }, "SendEmailInput": { "required": [ "company_id", "contact_email_id", "from_id" ], "properties": { "company_id": { "description": "UID of the company the email is about", "type": "integer", "example": 1 }, "contact_email_id": { "description": "UID of the email address to send to (the id inside contact_emails of a contact). Must belong to a contact connected to the company, and must not be unsubscribed.", "type": "integer", "example": 3 }, "from_id": { "description": "UID of the address to send from. Must be one of the sending addresses of the owner of the API key (see sending_addresses).", "type": "integer", "example": 5 }, "template_id": { "description": "UID of the email template to send. Send either template_id, or subject + content. Never both.", "type": "integer", "example": 1, "nullable": true }, "subject": { "description": "Required when there is no template_id", "type": "string", "example": "Quick question", "nullable": true }, "content": { "description": "Body of the email (HTML). Required when there is no template_id.", "type": "string", "example": "

Hi ${first_name}, I came across ${company_name} and...

", "nullable": true }, "placeholders": { "description": "Values for your own ${...} placeholders inside the content or the template, as name: value. first_name, last_name, city and company_name are always filled in by ProspectSafari from the contact and the company. A placeholder without a value is removed from the email.", "type": "object", "example": { "product": "ProspectSafari" }, "nullable": true, "additionalProperties": { "type": "string" } }, "date_time": { "description": "Moment to send the email. Now if not defined.", "type": "string", "format": "date-time", "example": "2024-04-29T10:00:00Z", "nullable": true }, "deal_id": { "description": "UID of the deal the email is about. Must be a deal of the company.", "type": "integer", "example": 4, "nullable": true }, "cc": { "type": "array", "items": { "type": "string", "format": "email" }, "nullable": true }, "bcc": { "type": "array", "items": { "type": "string", "format": "email" }, "nullable": true }, "reply_to_address": { "type": "string", "format": "email", "example": "sales@samplecompany.com", "nullable": true }, "unsubscribe_button": { "description": "Add an unsubscribe link to the email. False if not defined.", "type": "boolean", "example": true, "nullable": true } }, "type": "object" }, "StartSequenceInput": { "description": "Same fields as SendEmailInput minus template_id, subject and content: every email of a sequence is one of its templates.", "required": [ "company_id", "contact_email_id", "from_id" ], "properties": { "company_id": { "description": "UID of the company the emails are about", "type": "integer", "example": 1 }, "contact_email_id": { "description": "UID of the email address to send to (the id inside contact_emails of a contact). Must belong to a contact connected to the company, and must not be unsubscribed.", "type": "integer", "example": 3 }, "from_id": { "description": "UID of the address to send from. Must be one of the sending addresses of the owner of the API key (see sending_addresses).", "type": "integer", "example": 5 }, "placeholders": { "description": "Values for the ${...} placeholders of the templates, as name: value. first_name, last_name, city and company_name are filled in by ProspectSafari. Every custom_text_1, custom_text_2, custom_text_3 the templates use is required (the app asks the salesperson to type it).", "type": "object", "example": { "custom_text_1": "Loved your talk at the Berlin expo." }, "nullable": true }, "date_time": { "description": "Moment the first email goes out. Now if not defined.", "type": "string", "format": "date-time", "example": "2024-04-29T10:00:00Z", "nullable": true }, "deal_id": { "description": "UID of the deal the emails are about. Must be a deal of the company.", "type": "integer", "example": 4, "nullable": true }, "cc": { "type": "array", "items": { "type": "string", "format": "email" }, "nullable": true }, "bcc": { "type": "array", "items": { "type": "string", "format": "email" }, "nullable": true }, "reply_to_address": { "type": "string", "format": "email", "example": "sales@samplecompany.com", "nullable": true }, "unsubscribe_button": { "description": "Add an unsubscribe link to every email. False if not defined.", "type": "boolean", "example": true, "nullable": true } }, "type": "object" }, "task_type_options": { "description": "What the task asks for: 0 (Email), 1 (Research note), 2 (Phone call), 3 (Other), 4 (Send message).", "type": "integer", "example": 2, "enum": [ 0, 1, 2, 3, 4 ] }, "task_priority_options": { "description": "Priority of the task: 0 (High), 1 (Medium), 3 (Low). There is no 2. A High priority task is also put in the calendar of its owner, if that team member connected a calendar to ProspectSafari.", "type": "integer", "example": 3, "enum": [ 0, 1, 3 ] }, "TaskInput": { "required": [ "company_id", "contact_id", "task_queue_id", "sub_type", "content", "date_time" ], "properties": { "company_id": { "description": "UID of the company the task is about. Can't be changed after the task is created.", "type": "integer", "example": 1 }, "contact_id": { "description": "UID of the contact the task is about. A task always has a contact, and it must be connected to the company.", "type": "integer", "example": 15 }, "task_queue_id": { "description": "UID of the task queue to put the task in", "type": "integer", "example": 1 }, "sub_type": { "$ref": "#/components/schemas/task_type_options" }, "content": { "description": "What needs to be done (can contain HTML)", "type": "string", "example": "Call John back about the proposal." }, "date_time": { "description": "Moment the task is due", "type": "string", "format": "date-time", "example": "2024-04-29T10:00:00Z" }, "priority": { "$ref": "#/components/schemas/task_priority_options" }, "deal_id": { "description": "UID of the deal the task is about. Must be a deal of the company.", "type": "integer", "example": 4, "nullable": true }, "user_workspace_id": { "description": "UID of the team member who has to do the task. The owner of the API key if not defined on create.", "type": "integer", "example": 2 } }, "type": "object" }, "phone_call_outcome_options": { "description": "Outcome of the call: 0 (Incoming call), 1 (Outgoing call, connected), 2 (Voicemail), 3 (No answer), 4 (Live message), 5 (Busy), 6 (Wrong number).", "type": "integer", "example": 1, "enum": [ 0, 1, 2, 3, 4, 5, 6 ] }, "PhoneCallInput": { "required": [ "company_id", "contact_phone_number_id", "sub_type", "content" ], "properties": { "company_id": { "description": "UID of the company which was called. Can't be changed after the call is created.", "type": "integer", "example": 1 }, "contact_phone_number_id": { "description": "UID of the phone number which was called (the id inside contact_phone_numbers of a contact). Must belong to a contact connected to the company. The contact of the call is the contact of this phone number.", "type": "integer", "example": 31 }, "sub_type": { "$ref": "#/components/schemas/phone_call_outcome_options" }, "content": { "description": "Notes about the call (can contain HTML)", "type": "string", "example": "Spoke with John, he asked for a proposal." }, "deal_id": { "description": "UID of the deal the call is about. Must be a deal of the company.", "type": "integer", "example": 4, "nullable": true }, "user_workspace_id": { "description": "UID of the team member who made the call. The owner of the API key if not defined on create.", "type": "integer", "example": 2 }, "date_time": { "description": "Moment of the call. Now if not defined on create.", "type": "string", "format": "date-time", "example": "2024-04-29T10:00:00Z" }, "call_line_type": { "$ref": "#/components/schemas/call_line_type_options" }, "call_line_status": { "$ref": "#/components/schemas/call_line_status_options" }, "call_line_note": { "description": "Note about the phone line (not about this call), e.g. 'Ask for extension 12'. Only used on create.", "type": "string", "example": "Ask for extension 12", "nullable": true } }, "type": "object" }, "NoteInput": { "required": [ "company_id", "content" ], "properties": { "company_id": { "description": "UID of the company the note is about. Can't be changed after the note is created.", "type": "integer", "example": 1 }, "content": { "description": "Text of the note (can contain HTML)", "type": "string", "example": "Spoke with John, call back in May." }, "sub_type": { "description": "0 (NORMAL), 1 (PINNED: stays on top of the timeline), 2 (RESOURCE: research note). 0 if not defined on create.", "type": "integer", "example": 0, "enum": [ 0, 1, 2 ] }, "contact_id": { "description": "UID of the contact the note is about. Must be connected to the company. Send null on update to remove it.", "type": "integer", "example": 15, "nullable": true }, "deal_id": { "description": "UID of the deal the note is about. Must be a deal of the company.", "type": "integer", "example": 4, "nullable": true }, "user_workspace_id": { "description": "UID of the team member the note belongs to. The owner of the API key if not defined on create.", "type": "integer", "example": 2 }, "date_time": { "description": "Moment of the note. Now if not defined on create.", "type": "string", "format": "date-time", "example": "2024-04-29T10:00:00Z" } }, "type": "object" } }, "parameters": { "page": { "name": "page", "in": "query", "description": "Page to return (starts at 1)", "required": false, "schema": { "type": "integer", "default": 1, "minimum": 1 } }, "per_page": { "name": "per_page", "in": "query", "description": "Items per page (max 100)", "required": false, "schema": { "type": "integer", "default": 25, "maximum": 100, "minimum": 1 } } }, "securitySchemes": { "X-API-Key": { "type": "apiKey", "description": "Your API key, from the Integrations page. Both headers are required on every call.", "name": "X-API-Key", "in": "header" }, "X-API-Secret": { "type": "apiKey", "description": "The secret shown once when the key was created.", "name": "X-API-Secret", "in": "header" } } }, "tags": [ { "name": "Company", "description": "The companies you prospect. Everything else hangs off a company." }, { "name": "Contact", "description": "The people at a company: names, emails, phone numbers, job title." }, { "name": "Deal", "description": "Deals on a pipeline: create them, move them through the stages, tick their checklist steps off." }, { "name": "Deal Pipeline", "description": "Your pipelines and their stages (the deal_stage_id a deal needs). Only admins can create and change them." }, { "name": "Checklist", "description": "The checklists of the sales coach and their steps, which turn into tasks on the deals of a stage. Only admins can change them. Ticking steps off happens on the deal." }, { "name": "Document", "description": "The documents of the sales coach (scripts, proposals, case studies...): text, a PDF or a link. Attached to a pipeline stage or a checklist step, they show up for the salesperson in the Resources tab of a deal. Only admins can change them." }, { "name": "Quiz", "description": "The qualification quizzes of the sales coach. Set one on a pipeline (quiz_id) and its deals are qualified with it, which gives them their win probability. Only admins can change them. Answering happens on the deal." }, { "name": "Timeline Item", "description": "What happened with a company or contact: notes, phone calls, tasks, emails, messages, meetings. POST emails is the only endpoint which reaches somebody outside ProspectSafari." }, { "name": "Email Template", "description": "Reusable emails (subject + html) to send with POST /timeline_items/emails." }, { "name": "Email Sequence", "description": "A series of email templates, each sent a set time after the one before. Managed here, started for a contact inside ProspectSafari." }, { "name": "Sending Address", "description": "Read only. The mailboxes of the key owner you can send email from (from_id)." }, { "name": "Message Type", "description": "Read only. The kinds of message you can log (message_type)." }, { "name": "Task Queue", "description": "Read only. The queues a task can go on (task_queue_id)." }, { "name": "List", "description": "Read only. The lists companies are grouped in (list_id)." }, { "name": "Team Member", "description": "Read only. The members of the workspace (user_workspace_id): the owners of companies, deals and timeline items." }, { "name": "Custom Field", "description": "Read only. The custom fields of the workspace for companies, contacts and deals, and their ids." }, { "name": "Webhooks", "description": "Not an endpoint you call: the payload ProspectSafari POSTs to the webhook URL set on the Integrations page." } ] }