Freshsales MCP by usefulapi

List the saved contact views (filters) of the account, e.g. 'My Contacts', 'New Contacts', 'All Contacts'. A view id is needed by freshsales_list_contacts; ids differ per account. GET /contacts/filters.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List the contacts in a view (get view_id from freshsales_list_contact_views), 25 per page with name, email, phone numbers, job title, lead score, open deals amount and last contacted. Pages: use next_page. GET /contacts/view/{view_id}.

{
  "type": "object",
  "properties": {
    "view_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Contact view id (freshsales_list_contact_views)."
    },
    "sort": {
      "description": "Sort field.",
      "type": "string",
      "enum": [
        "lead_score",
        "created_at",
        "updated_at",
        "open_deals_amount",
        "last_contacted"
      ]
    },
    "sort_type": {
      "description": "Sort direction (default: the view's own order).",
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ]
    },
    "page": {
      "default": 1,
      "description": "Page number, 1-based (25 records per page).",
      "type": "integer",
      "minimum": 1,
      "maximum": 10000
    }
  },
  "required": [
    "view_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One contact by id with all its fields, optionally with related records embedded via include (notes, tasks, appointments, deals, sales_accounts, owner, sales_activities...). GET /contacts/{id}.

{
  "type": "object",
  "properties": {
    "contact_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Contact id."
    },
    "include": {
      "description": "Related records to embed.",
      "maxItems": 12,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "sales_activities",
          "owner",
          "creater",
          "updater",
          "source",
          "campaign",
          "tasks",
          "appointments",
          "notes",
          "deals",
          "sales_accounts",
          "territory"
        ]
      }
    }
  },
  "required": [
    "contact_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Search by name/email text across one record type: contact, sales_account (company), deal or user. Returns id, type, name and email for the matches (up to per_page, default 10). Use the id with the get tools. GET /search.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Text to search for (name, email, ...)."
    },
    "entity": {
      "default": "contact",
      "description": "Record type to search (singular).",
      "type": "string",
      "enum": [
        "contact",
        "sales_account",
        "deal",
        "user"
      ]
    },
    "per_page": {
      "description": "Results to return (1-100, default 10).",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "required": [
    "query"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Exact-match lookup of contacts, companies or deals by one field, e.g. a contact by email address. field is 'email' (contacts), 'name', or a custom field name (cf_...). Returns the full records. GET /lookup.

{
  "type": "object",
  "properties": {
    "value": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "The exact value to find, e.g. [email protected]."
    },
    "field": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "Field to match: email, name, or a custom field name (cf_...)."
    },
    "entity": {
      "default": "contact",
      "description": "Record type.",
      "type": "string",
      "enum": [
        "contact",
        "sales_account",
        "deal"
      ]
    }
  },
  "required": [
    "value",
    "field"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List the saved account (company) views of the account, e.g. 'My Accounts'. A view id is needed by freshsales_list_accounts. GET /sales_accounts/filters.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List the accounts (companies) in a view (view_id from freshsales_list_account_views), 25 per page, with name, location, open deals amount and last contacted. GET /sales_accounts/view/{view_id}.

{
  "type": "object",
  "properties": {
    "view_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Account view id (freshsales_list_account_views)."
    },
    "sort": {
      "description": "Sort field.",
      "type": "string",
      "enum": [
        "open_deals_amount",
        "created_at",
        "updated_at",
        "last_contacted"
      ]
    },
    "sort_type": {
      "description": "Sort direction (default: the view's own order).",
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ]
    },
    "page": {
      "default": 1,
      "description": "Page number, 1-based (25 records per page).",
      "type": "integer",
      "minimum": 1,
      "maximum": 10000
    }
  },
  "required": [
    "view_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One account (company) by id with its fields, optionally with related records embedded (contacts, deals, tasks, appointments, owner...). GET /sales_accounts/{id}.

{
  "type": "object",
  "properties": {
    "account_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Account (sales account) id."
    },
    "include": {
      "description": "Related records to embed.",
      "maxItems": 11,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "owner",
          "creater",
          "updater",
          "territory",
          "business_type",
          "tasks",
          "appointments",
          "contacts",
          "deals",
          "industry_type",
          "child_sales_accounts"
        ]
      }
    }
  },
  "required": [
    "account_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List the saved deal views of the account, e.g. 'Open Deals'. A view id is needed by freshsales_list_deals. GET /deals/filters.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List the deals in a view (view_id from freshsales_list_deal_views), 25 per page, with name, amount, expected close, probability and age. GET /deals/view/{view_id}.

{
  "type": "object",
  "properties": {
    "view_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Deal view id (freshsales_list_deal_views)."
    },
    "sort": {
      "description": "Sort field.",
      "type": "string",
      "enum": [
        "amount",
        "expected_close",
        "created_at",
        "updated_at",
        "last_contacted"
      ]
    },
    "sort_type": {
      "description": "Sort direction (default: the view's own order).",
      "type": "string",
      "enum": [
        "asc",
        "desc"
      ]
    },
    "page": {
      "default": 1,
      "description": "Page number, 1-based (25 records per page).",
      "type": "integer",
      "minimum": 1,
      "maximum": 10000
    }
  },
  "required": [
    "view_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One deal by id with amount, expected close, probability and ids of its stage, pipeline and owner, optionally with related records embedded (contacts, sales_account, deal_stage, owner, notes via sales_activities...). GET /deals/{id}.

{
  "type": "object",
  "properties": {
    "deal_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Deal id."
    },
    "include": {
      "description": "Related records to embed.",
      "maxItems": 14,
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "sales_activities",
          "owner",
          "creater",
          "updater",
          "source",
          "contacts",
          "sales_account",
          "deal_stage",
          "deal_type",
          "deal_reason",
          "campaign",
          "deal_payment_status",
          "deal_product",
          "currency"
        ]
      }
    }
  },
  "required": [
    "deal_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List tasks by status filter: open, due_today, due_tomorrow, overdue or completed (one filter per call). Returns title, due date, owner and status. GET /tasks.

{
  "type": "object",
  "properties": {
    "filter": {
      "default": "open",
      "description": "Which tasks to list.",
      "type": "string",
      "enum": [
        "open",
        "due_today",
        "due_tomorrow",
        "overdue",
        "completed"
      ]
    },
    "page": {
      "default": 1,
      "description": "Page number, 1-based (25 records per page).",
      "type": "integer",
      "minimum": 1,
      "maximum": 10000
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One task by id. GET /tasks/{id}.

{
  "type": "object",
  "properties": {
    "task_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Task id."
    }
  },
  "required": [
    "task_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List appointments that are open (upcoming) or complete (one filter per call), with title, time, location and creator. GET /appointments.

{
  "type": "object",
  "properties": {
    "filter": {
      "default": "open",
      "description": "Which appointments to list.",
      "type": "string",
      "enum": [
        "open",
        "complete"
      ]
    },
    "page": {
      "default": 1,
      "description": "Page number, 1-based (25 records per page).",
      "type": "integer",
      "minimum": 1,
      "maximum": 10000
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

One appointment by id with its attendees. GET /appointments/{id}.

{
  "type": "object",
  "properties": {
    "appointment_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Appointment id."
    }
  },
  "required": [
    "appointment_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List logged sales activities (calls, meetings, emails...) of the account. GET /sales_activities.

{
  "type": "object",
  "properties": {
    "page": {
      "default": 1,
      "description": "Page number, 1-based (25 records per page).",
      "type": "integer",
      "minimum": 1,
      "maximum": 10000
    },
    "per_page": {
      "default": 25,
      "description": "Records per page (1-100).",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List the users of the account (id and name). Use the id as owner_id when creating or updating records. GET /selector/owners.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List the deal pipelines (id, name). GET /selector/deal_pipelines.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List deal stages (id, name, deal_pipeline_id): those of the default pipeline, or of the pipeline given by pipeline_id. Use the id as deal_stage_id. GET /selector/deal_stages or /selector/deal_pipelines/{id}/deal_stages.

{
  "type": "object",
  "properties": {
    "pipeline_id": {
      "description": "Pipeline id (freshsales_list_deal_pipelines); default pipeline when omitted.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List the configured choices (id and name) for a field: lead_sources, contact_statuses, lifecycle_stages, deal_types, deal_reasons, deal_products, deal_payment_statuses, territories, currencies, industry_types, business_types, campaigns, sales_activity_types, sales_activity_outcomes. Use the ids in the *_id fields of the write tools. GET /selector/{kind}.

{
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "enum": [
        "deal_types",
        "lead_sources",
        "contact_statuses",
        "lifecycle_stages",
        "territories",
        "currencies",
        "deal_reasons",
        "industry_types",
        "business_types",
        "campaigns",
        "deal_payment_statuses",
        "deal_products",
        "sales_activity_types",
        "sales_activity_outcomes"
      ],
      "description": "Which list of choices."
    }
  },
  "required": [
    "kind"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: create a contact. Freshsales requires an email or a mobile number. It may create a duplicate of an existing contact: search first (freshsales_lookup by email). POST /contacts.

{
  "type": "object",
  "properties": {
    "first_name": {
      "description": "First name.",
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "last_name": {
      "description": "Last name.",
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "email": {
      "description": "Primary email address.",
      "type": "string",
      "maxLength": 254,
      "format": "email",
      "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
    },
    "mobile_number": {
      "description": "Mobile number.",
      "type": "string",
      "minLength": 1,
      "maxLength": 40
    },
    "work_number": {
      "description": "Work phone number.",
      "type": "string",
      "minLength": 1,
      "maxLength": 40
    },
    "job_title": {
      "description": "Job title.",
      "type": "string",
      "minLength": 1,
      "maxLength": 150
    },
    "owner_id": {
      "description": "Owner user id (freshsales_list_owners).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "lead_source_id": {
      "description": "Lead source id (freshsales_list_options lead_sources).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "contact_status_id": {
      "description": "Contact status id (freshsales_list_options contact_statuses).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "lifecycle_stage_id": {
      "description": "Lifecycle stage id (freshsales_list_options lifecycle_stages).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "address": {
      "description": "Street address.",
      "type": "string",
      "minLength": 1,
      "maxLength": 300
    },
    "city": {
      "description": "City.",
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "state": {
      "description": "State or region.",
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "zipcode": {
      "description": "Postal code.",
      "type": "string",
      "minLength": 1,
      "maxLength": 30
    },
    "country": {
      "description": "Country.",
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "sales_accounts": {
      "description": "Companies the contact belongs to: [{id, is_primary}], at most 10, exactly one primary.",
      "minItems": 1,
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "exclusiveMinimum": 0,
            "maximum": 9007199254740991
          },
          "is_primary": {
            "type": "boolean"
          }
        },
        "required": [
          "id",
          "is_primary"
        ]
      }
    },
    "custom_field": {
      "description": "Custom field values keyed by field name, e.g. {\"cf_is_active\": true}. Field names start with cf_.",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: change fields of an existing contact; only the fields you pass are changed (passing sales_accounts replaces the associated companies). PUT /contacts/{id}.

{
  "type": "object",
  "properties": {
    "contact_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Contact id."
    },
    "first_name": {
      "description": "First name.",
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "last_name": {
      "description": "Last name.",
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "email": {
      "description": "Primary email address.",
      "type": "string",
      "maxLength": 254,
      "format": "email",
      "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
    },
    "mobile_number": {
      "description": "Mobile number.",
      "type": "string",
      "minLength": 1,
      "maxLength": 40
    },
    "work_number": {
      "description": "Work phone number.",
      "type": "string",
      "minLength": 1,
      "maxLength": 40
    },
    "job_title": {
      "description": "Job title.",
      "type": "string",
      "minLength": 1,
      "maxLength": 150
    },
    "owner_id": {
      "description": "Owner user id (freshsales_list_owners).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "lead_source_id": {
      "description": "Lead source id (freshsales_list_options lead_sources).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "contact_status_id": {
      "description": "Contact status id (freshsales_list_options contact_statuses).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "lifecycle_stage_id": {
      "description": "Lifecycle stage id (freshsales_list_options lifecycle_stages).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "address": {
      "description": "Street address.",
      "type": "string",
      "minLength": 1,
      "maxLength": 300
    },
    "city": {
      "description": "City.",
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "state": {
      "description": "State or region.",
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "zipcode": {
      "description": "Postal code.",
      "type": "string",
      "minLength": 1,
      "maxLength": 30
    },
    "country": {
      "description": "Country.",
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "sales_accounts": {
      "description": "Companies the contact belongs to: [{id, is_primary}], at most 10, exactly one primary.",
      "minItems": 1,
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "exclusiveMinimum": 0,
            "maximum": 9007199254740991
          },
          "is_primary": {
            "type": "boolean"
          }
        },
        "required": [
          "id",
          "is_primary"
        ]
      }
    },
    "custom_field": {
      "description": "Custom field values keyed by field name, e.g. {\"cf_is_active\": true}. Field names start with cf_.",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    }
  },
  "required": [
    "contact_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: create an account (company). name is required. It may duplicate an existing company: search first (freshsales_search). POST /sales_accounts.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Company name."
    },
    "address": {
      "description": "Street address.",
      "type": "string",
      "minLength": 1,
      "maxLength": 300
    },
    "city": {
      "description": "City.",
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "state": {
      "description": "State or region.",
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "zipcode": {
      "description": "Postal code.",
      "type": "string",
      "minLength": 1,
      "maxLength": 30
    },
    "country": {
      "description": "Country.",
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "website": {
      "description": "Website.",
      "type": "string",
      "minLength": 1,
      "maxLength": 300
    },
    "phone": {
      "description": "Phone number.",
      "type": "string",
      "minLength": 1,
      "maxLength": 40
    },
    "number_of_employees": {
      "description": "Company size bucket code (not a headcount): 1 = 1-10, 11 = 11-50, 51 = 51-200, 201 = 201-500, 501 = 501-1000, 1001 = 1001-5000, 5001 = 5001-10000, 10001 = 10000+.",
      "anyOf": [
        {
          "type": "number",
          "const": 1
        },
        {
          "type": "number",
          "const": 11
        },
        {
          "type": "number",
          "const": 51
        },
        {
          "type": "number",
          "const": 201
        },
        {
          "type": "number",
          "const": 501
        },
        {
          "type": "number",
          "const": 1001
        },
        {
          "type": "number",
          "const": 5001
        },
        {
          "type": "number",
          "const": 10001
        }
      ]
    },
    "annual_revenue": {
      "description": "Annual revenue.",
      "type": "number",
      "minimum": 0
    },
    "owner_id": {
      "description": "Owner user id (freshsales_list_owners).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "industry_type_id": {
      "description": "Industry id (freshsales_list_options industry_types).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "business_type_id": {
      "description": "Business type id (freshsales_list_options business_types).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "custom_field": {
      "description": "Custom field values keyed by field name, e.g. {\"cf_is_active\": true}. Field names start with cf_.",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    }
  },
  "required": [
    "name"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: change fields of an existing account (company); only the fields you pass are changed. PUT /sales_accounts/{id}.

{
  "type": "object",
  "properties": {
    "account_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Account (sales account) id."
    },
    "name": {
      "description": "Company name.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "address": {
      "description": "Street address.",
      "type": "string",
      "minLength": 1,
      "maxLength": 300
    },
    "city": {
      "description": "City.",
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "state": {
      "description": "State or region.",
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "zipcode": {
      "description": "Postal code.",
      "type": "string",
      "minLength": 1,
      "maxLength": 30
    },
    "country": {
      "description": "Country.",
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "website": {
      "description": "Website.",
      "type": "string",
      "minLength": 1,
      "maxLength": 300
    },
    "phone": {
      "description": "Phone number.",
      "type": "string",
      "minLength": 1,
      "maxLength": 40
    },
    "number_of_employees": {
      "description": "Company size bucket code (not a headcount): 1 = 1-10, 11 = 11-50, 51 = 51-200, 201 = 201-500, 501 = 501-1000, 1001 = 1001-5000, 5001 = 5001-10000, 10001 = 10000+.",
      "anyOf": [
        {
          "type": "number",
          "const": 1
        },
        {
          "type": "number",
          "const": 11
        },
        {
          "type": "number",
          "const": 51
        },
        {
          "type": "number",
          "const": 201
        },
        {
          "type": "number",
          "const": 501
        },
        {
          "type": "number",
          "const": 1001
        },
        {
          "type": "number",
          "const": 5001
        },
        {
          "type": "number",
          "const": 10001
        }
      ]
    },
    "annual_revenue": {
      "description": "Annual revenue.",
      "type": "number",
      "minimum": 0
    },
    "owner_id": {
      "description": "Owner user id (freshsales_list_owners).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "industry_type_id": {
      "description": "Industry id (freshsales_list_options industry_types).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "business_type_id": {
      "description": "Business type id (freshsales_list_options business_types).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "custom_field": {
      "description": "Custom field values keyed by field name, e.g. {\"cf_is_active\": true}. Field names start with cf_.",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    }
  },
  "required": [
    "account_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: create a deal. name, amount and sales_account_id are required; contact_ids attach existing contacts. Stage and pipeline default to the first of the default pipeline. POST /deals.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Deal name."
    },
    "amount": {
      "type": "number",
      "minimum": 0,
      "maximum": 10000000000000,
      "description": "Deal value in the account's default currency."
    },
    "sales_account_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Company the deal belongs to."
    },
    "deal_stage_id": {
      "description": "Stage id (freshsales_list_deal_stages).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "deal_pipeline_id": {
      "description": "Pipeline id (freshsales_list_deal_pipelines).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "owner_id": {
      "description": "Owner user id (freshsales_list_owners).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "expected_close": {
      "description": "Expected close date, YYYY-MM-DD.",
      "type": "string",
      "format": "date",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"
    },
    "probability": {
      "description": "Win probability, 0-100.",
      "type": "integer",
      "minimum": 0,
      "maximum": 100
    },
    "deal_type_id": {
      "description": "Deal type id (freshsales_list_options deal_types).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "lead_source_id": {
      "description": "Lead source id (freshsales_list_options lead_sources).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "custom_field": {
      "description": "Custom field values keyed by field name, e.g. {\"cf_is_active\": true}. Field names start with cf_.",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "contact_ids": {
      "description": "Existing contact ids to attach to the deal.",
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "integer",
        "exclusiveMinimum": 0,
        "maximum": 9007199254740991
      }
    }
  },
  "required": [
    "name",
    "amount",
    "sales_account_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: change fields of an existing deal, e.g. move it to another stage (deal_stage_id), change amount or expected close; only the fields you pass are changed. PUT /deals/{id}.

{
  "type": "object",
  "properties": {
    "deal_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Deal id."
    },
    "name": {
      "description": "Deal name.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "amount": {
      "description": "Deal value in the deal's own currency (a multi-currency account: freshsales_get_deal shows the deal's currency first when updating).",
      "type": "number",
      "minimum": 0,
      "maximum": 10000000000000
    },
    "sales_account_id": {
      "description": "Company the deal belongs to (freshsales_search sales_account).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "deal_stage_id": {
      "description": "Stage id (freshsales_list_deal_stages).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "deal_pipeline_id": {
      "description": "Pipeline id (freshsales_list_deal_pipelines).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "owner_id": {
      "description": "Owner user id (freshsales_list_owners).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "expected_close": {
      "description": "Expected close date, YYYY-MM-DD.",
      "type": "string",
      "format": "date",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"
    },
    "probability": {
      "description": "Win probability, 0-100.",
      "type": "integer",
      "minimum": 0,
      "maximum": 100
    },
    "deal_type_id": {
      "description": "Deal type id (freshsales_list_options deal_types).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "lead_source_id": {
      "description": "Lead source id (freshsales_list_options lead_sources).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "custom_field": {
      "description": "Custom field values keyed by field name, e.g. {\"cf_is_active\": true}. Field names start with cf_.",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    },
    "add_contact_ids": {
      "description": "Existing contact ids to attach.",
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "integer",
        "exclusiveMinimum": 0,
        "maximum": 9007199254740991
      }
    },
    "remove_contact_ids": {
      "description": "Contact ids to detach from the deal.",
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "integer",
        "exclusiveMinimum": 0,
        "maximum": 9007199254740991
      }
    }
  },
  "required": [
    "deal_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: add a note to a contact, account or deal. Visible to your team on the record. POST /notes.

{
  "type": "object",
  "properties": {
    "target_type": {
      "type": "string",
      "enum": [
        "Contact",
        "SalesAccount",
        "Deal"
      ],
      "description": "What the record is attached to: Contact, SalesAccount (company) or Deal."
    },
    "target_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Id of the contact, account or deal."
    },
    "description": {
      "type": "string",
      "minLength": 1,
      "maxLength": 10000,
      "description": "The note text."
    }
  },
  "required": [
    "target_type",
    "target_id",
    "description"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: replace the text of an existing note. PUT /notes/{id}.

{
  "type": "object",
  "properties": {
    "note_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Note id."
    },
    "description": {
      "type": "string",
      "minLength": 1,
      "maxLength": 10000,
      "description": "The new note text."
    }
  },
  "required": [
    "note_id",
    "description"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: create a task (to-do) attached to a contact, account or deal. title, due_date, owner_id and the target are required. POST /tasks.

{
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 300,
      "description": "Task title."
    },
    "due_date": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
      "description": "Due date and time, ISO 8601 with a timezone, e.g. 2026-11-02T09:00:00Z."
    },
    "owner_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "User who owns the task (freshsales_list_owners)."
    },
    "target_type": {
      "type": "string",
      "enum": [
        "Contact",
        "SalesAccount",
        "Deal"
      ],
      "description": "What the record is attached to: Contact, SalesAccount (company) or Deal."
    },
    "target_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Id of the contact, account or deal."
    },
    "description": {
      "description": "Details.",
      "type": "string",
      "minLength": 1,
      "maxLength": 5000
    }
  },
  "required": [
    "title",
    "due_date",
    "owner_id",
    "target_type",
    "target_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: change a task: title, details, due date, owner, or mark it completed (status 1) or open (status 0). PUT /tasks/{id}.

{
  "type": "object",
  "properties": {
    "task_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991,
      "description": "Task id."
    },
    "title": {
      "description": "New title.",
      "type": "string",
      "minLength": 1,
      "maxLength": 300
    },
    "description": {
      "description": "New details.",
      "type": "string",
      "minLength": 1,
      "maxLength": 5000
    },
    "due_date": {
      "description": "New due date and time, ISO 8601 with a timezone.",
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
    },
    "owner_id": {
      "description": "New owner user id.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "status": {
      "description": "0 = open, 1 = completed.",
      "anyOf": [
        {
          "type": "number",
          "const": 0
        },
        {
          "type": "number",
          "const": 1
        }
      ]
    }
  },
  "required": [
    "task_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: create an appointment (meeting) with a start and end, optionally attached to a contact, account or deal and with attendees. Attendees may be notified by Freshsales. POST /appointments.

{
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 300,
      "description": "Appointment title."
    },
    "from_date": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
      "description": "Start, ISO 8601 with a timezone, e.g. 2026-11-02T09:00:00Z."
    },
    "end_date": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
      "description": "End, ISO 8601 with a timezone; after from_date."
    },
    "time_zone": {
      "description": "Time zone name, e.g. Europe/Prague.",
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "location": {
      "description": "Location.",
      "type": "string",
      "minLength": 1,
      "maxLength": 300
    },
    "description": {
      "description": "Details.",
      "type": "string",
      "minLength": 1,
      "maxLength": 5000
    },
    "target_type": {
      "type": "string",
      "enum": [
        "Contact",
        "SalesAccount",
        "Deal"
      ],
      "description": "What the record is attached to: Contact, SalesAccount (company) or Deal."
    },
    "target_id": {
      "description": "Id of the contact, account or deal (with target_type).",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "attendee_user_ids": {
      "description": "User ids (freshsales_list_owners) attending.",
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "integer",
        "exclusiveMinimum": 0,
        "maximum": 9007199254740991
      }
    },
    "attendee_contact_ids": {
      "description": "Contact ids attending.",
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "integer",
        "exclusiveMinimum": 0,
        "maximum": 9007199254740991
      }
    }
  },
  "required": [
    "title",
    "from_date",
    "end_date"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}