Freshworks Developer Platform Docs

onCpqDocumentCreate

The Configure, Price, Quote (CPQ) feature of Freshsales Suite enables organizations to configure and generate customer-specific quotes for products/services. As part of this feature, Freshsales Suite users can create standardized documents such as proposals, NDAs, MSAs, and so on by using pre-set templates. For more information, see CPQ add-on in Freshsales Suite.

The onCpqDocumentCreate event is triggered and the registered callback method is executed, when a new document is created in the Freshworks system.

Subscribe to the onCpqDocumentCreate event and register the callback by using the following sample manifest.json content.

manifest.json

"events": {
  "onCpqDocumentCreate": {
    "handler": "onCpqDocumentCreateCallback"
  }
}

Define the corresponding callback by using the following sample server.js content:

server.js

exports = {
  onCpqDocumentCreateCallback: function(payload) {
    console.log("Logging arguments from onCpqDocumentCreate event: " + JSON.stringify(payload));
  }
}

Attributes of the data object

actorobject
Information pertaining to the entity who triggered the onCpqDocumentCreate event in the Freshworks system.
- idinteger
  Identifier of the actor who triggered the product event.
  The value of this attribute is 0 when the value of actor.type is system.
- namestring
  Full name of the actor.
- typestring
  Name of the entity that triggered the onCpqDocumentCreate event.
  Possible value: system
associationsobject
All associated objects of the cpq document object, which specify additional information pertaining to the document created.
- cpq_document_product_associationsarray of objects
  Additional information pertaining to the products added to the deal for which the document is created.
  billing_cycleinteger
  Frequency of billing for the product added to the document.
  If the product has one-time billing, billing_cycle is null.
  billing_typeinteger
  Identifier of the billing type of the product added to the document.
  Possible values:
  1: monthly subscription
  2: quarterly subscription
  2: half-yearly subscription
  4: annual subscription
  For products with one-time billing, the value of billing_type is null.
  created_atstring
  Timestamp of when the product is created in the Freshworks system, specified in the UTC format.
  currency_codestring
  Currency in which the product’s value is expressed, specified in the ISO 4217 format.
  idinteger
  Identifier of product, auto-generated when the product is created in the Freshworks system.
  setup_feestring
  Setting up fees, if any, for the product added to the document.
  unit_priceinteger
  Price per unit of the product added to the document.
cpq_documentobject
Information pertaining to the document that is created in the Freshworks system.
- amountinteger
  Deal value, which is determined based on the unit price, quantity, and discount specified for the products added to the deal associated with the document.
- base_currency_amountstring
  Total value of the product(s) added to the document specified in the base currency configured for the Freshsales Suite account.
- billing_addressstring
  Address associated with the deal’s payment information.
- billing_citystring
  City, district, town, or any other similar component of the address associated with the deal’s payment information.
- billing_countrystring
  Country name in the address associated with the deal’s payment information.
- billing_statestring
  State, region, province, county, or any other sub component of the address associated with the deal’s payment information.
- billing_zipcodestring
  ZIP or postal code in the address associated with the deal’s payment information.
- contact_idinteger
  Identifier of the contact object, auto-generated when a contact is created in the Freshworks system.
  The value of contact_id identifies the primary contact associated with the deal for which the document is created.
- cpq_document_template_idinteger
  Identifier of the template based on which the document is created.
- cpq_document_template_namestring
  Organizations can standardize the various types of documents by configuring document templates in the Freshworks system.
  The value of cpq_document_template_name refers to the name of the template based on which the document is created.
- created_atstring
  Timestamp of when the document is created in the Freshworks system, specified in the UTC format.
- creator_idinteger
  Identifier of the user who created the document.
- currency_codestring
  Currency code indicating the currency in which the deal value is expressed the currency code is in the ISO 4217 format.
- custom_fieldsobject
  Document details specified through custom fields. Note: Custom fields can be configured to obtain additional information about the document. The custom_fields attribute contains the custom field names and corresponding values, as a valid JSON object of key (custom field name)-value (custom field’s value) pairs.
- deal_idinteger
  Identifier of the deal object, auto-generated when a deal is created in the Freshworks system.
  The value of deal_id identifies the deal for which the document is created.
- display_idinteger
  Numeric identifier used as part of the document_number that uniquely identifies a document.
- display_id_prefixstring
  Preconfigured prefix used as part of the document_number that uniquely identifies a document.
  Possible value: DOC
- display_namestring
  Name of the document created.
- document_numberstring
  Identifier of a document, auto-generated when the document is created in the Freshworks system.
  The value of this attribute is a combination of the values of cpq_document.display_id and cpq_document.display_id_prefix.
- document_typeinteger
  Type of the document created. For example, quote, proposal, Non-Disclosure Agreement (NDA), Master Service Agreement (MSA), and so on.
- idinteger
  Identifier of the document object, auto-generated when a document is created in the Freshworks system.
- is_deal_primaryboolean
  Specifies whether a deal is synced with the document created.
  A deal can be synced with a document to ensure that any updates to the products associated with the deal will be automatically synced with the document and vice-versa.
  For more information, see Auto-syncing of deals with documents.
  Possible values: true, false
- is_deletedboolean
  Specifies whether the document is deleted from the Freshworks system.
  Possible values: true, false
- owner_idinteger
  Identifier of the user who is assigned as the owner of the document.
  For onCpqDocumentCreate event, by default the value of this attribute is the same as the creator_id value.
- sales_account_idinteger
  Identifier of the sales account object, auto-generated when a new sales account is configured in the Freshworks system.
  The value of sales_account_id identifies the sales account associated with the deal for which the document is created.
- shipping_addressstring
  Address to which the product is shipped.
- shipping_citystring
  City, district, town, or any other similar component of the address to which the product is shipped.
- shipping_countrystring
  Country to which the product is shipped.
- shipping_statestring
  State, region, province, county, or any other sub component of the address to which the product is shipped.
- shipping_zipcodestring
  ZIP or postal code in the address to which the product is shipped.
- stageinteger
  Document stages can be configured in the Freshworks system based on the business process of the organization. The default document stages are,
  Draft
  Sent to customer
  Accepted
  Declined
  The value of stage is the identifier of the current document stage of the document. When a document is created in the Freshworks system, the document stage is set as draft automatically.
  For onCpqDocumentCreate event, the value of this attribute is the identifier of the Draft stage.
- territory_idinteger
  Identifier of the territory object, auto-generated when a territory is created in the Freshworks system.
  Territories can be configured to group users, so the users can focus on a particular set of customers and their sales activities can be monitored on territory basis.
  The value of territory_id identifies the territory to which the user who created the document is added.
- updated_atstring
  Timestamp of when the document is updated in the Freshworks system, specified in the UTC format.
  For onCpqDocumentCreate, the value of this attribute is the same as the created_at value.
- valid_tillstring
  Validity of the document, specified as a timestamp in the UTC format.

Sample payload

{
  "currentHost": {
    "subscribed_modules": [ "cpq_document" ],
    "endpoint_urls": {
      "freshworks_crm": "https://sample.myfreshworks.com",
      "freshsales": "https://sample.freshsales.io"
    }
  },
  "data": {
    "actor": {
      "id": 0,
      "name": "System",
      "type": "system"
    },
    "associations": {
      "cpq_document_product_associations": [
        {
          "billing_cycle": 1,
          "billing_type": 4,
          "created_at": "2022-10-21T04:29:49.000Z",
          "currency_code": "USD",
          "id": 70000010084,
          "setup_fee": "0.0",
          "unit_price": "13.0"
        },
        {
          "billing_cycle": 1,
          "billing_type": 4,
          "created_at": "2022-10-21T04:29:49.000Z",
          "currency_code": "USD",
          "id": 70000010085,
          "setup_fee": "0.0",
          "unit_price": "12.0"
        }
      ]
    },
    "cpq_document": {
      "amount": 677,
      "base_currency_amount": "677.0",
      "billing_address": "604-5854 Beckford St.",
      "billing_city": "Glendale",
      "billing_country": "USA",
      "billing_state": "Arizona",
      "billing_zipcode": "100652",
      "contact_id": 8441389,
      "cpq_document_template_id": 168209,
      "cpq_document_template_name": "Purchase agreement document",
      "created_at": "2022-09-07T09:12:39Z",
      "creator_id": 523562,
      "currency_code": "USD",
      "custom_fields": {
        "cf_number": 2,
        "cf_text": "Description"
      },
      "deal_id": 6796197,
      "display_id": 1,
      "display_id_prefix": "DOC",
      "display_name": "Purchase agreement",
      "document_number": "DOC-1",
      "document_type": 1019868749,
      "id": 153150,
      "is_deal_primary": false,
      "is_deleted": false,
      "owner_id": 523562,
      "sales_account_id": 5135558,
      "shipping_address": "chennai",
      "shipping_city": "chennai",
      "shipping_country": "India",
      "shipping_state": "Tamil Nadu",
      "shipping_zipcode": "600006",
      "stage": 1019868753,
      "territory_id": 818551,
      "updated_at": "2022-09-07T09:12:39Z",
      "valid_till": "2022-09-22T00:00:00Z"
    }
  },
  "event": "onCpqDocumentCreate",
  "region": "US",
  "timestamp": 1496400354326,
  "version": "2.0"
}

onCpqDocumentUpdate

The onCpqDocumentUpdate event is triggered when,

The details of the document are updated.
The details of the products associated with the document are modified.
The document is previewed or saved as a PDF file.
The document is soft deleted.

Subscribe to the onCpqDocumentUpdate event and register the callback by using the following sample manifest.json content.

manifest.json

"events": {
  "onCpqDocumentUpdate": {
    "handler": "onCpqDocumentUpdateCallback"
  }
}

Define the corresponding callback by using the following sample server.js content:

server.js

exports = {
  onCpqDocumentUpdateCallback: function(payload) {
    console.log("Logging arguments from onCpqDocumentUpdate event: " + JSON.stringify(payload));
  }
}

Attributes of the data object

actorobject
Information pertaining to the entity who triggered the onCpqDocumentUpdate event in the Freshales system.
- idinteger
  Identifier of the actor who triggered the product event.
  The value of this attribute is 0 when the value of actor.type is system.
- namestring
  Full name of the actor.
- typestring
  Name of the entity that triggered the onCpqDocumentUpdate event.
  Possible value: system
associationsobject
All associated objects of the cpq document object, which specify additional information pertaining to the document updated.
- cpq_document_product_associationsarray of objects
  Additional information pertaining to the products added to the deal for which the document is created.
  billing_cycleinteger
  Frequency of billing for the product added to the document.
  If the product has one-time billing, billing_cycle is null.
  billing_typeinteger
  Identifier of the billing type of the product added to the document.
  Possible values:
  1: monthly subscription
  2: quarterly subscription
  2: half-yearly subscription
  4: annual subscription
  For products with one-time billing, the value of billing_type is null.
  created_atstring
  Timestamp of when the product is created in the Freshworks system, specified in the UTC format.
  currency_codestring
  Currency in which the product’s value is expressed, specified in the ISO 4217 format.
  idinteger
  Identifier of product, auto-generated when the product is created in the Freshworks system.
  setup_feestring
  Setting up fees, if any, for the product added to the document.
  unit_priceinteger
  Price per unit of the product added to the document.

changesobject

Changes that triggered the onCpqDocumentUpdate event, specified as a JSON object of the following format:

"changes": {
  "model_changes": {
    //For non-array attributes
    "<cpq_document.attribute that changed>": ["New value", "Old value"]
  },
  "system_changes": {},
  "misc_changes": {}
}

Example

{
  "model_changes": {
    "deal_id": [
      6796197,
      6891801
    ],
    "sales_account_id": [
      5135558,
      5212715
    ],
    "base_currency_amount": [
      677,
      0
    ]
  }
  "system_changes": {},
  "misc_changes": {}
}

misc_changesobject
List of all miscellaneous database parameters whose values have changed, along with the old and modified values.
model_changesobject
List of all attributes whose values have changed along with the old and modified values of the attributes.
system_changesobject
List of all system-level parameters whose values have changed, along with the old and modified values.

cpq_documentobject
Information pertaining to the document that is created in the Freshworks system.
- amountinteger
  Deal value, which is determined based on the unit price, quantity, and discount specified for the products added to the deal associated with the document.
- base_currency_amountstring
  Total value of the product(s) added to the document specified in the base currency configured for the Freshsales Suite account.
- billing_addressstring
  Address associated with the deal’s payment information.
- billing_citystring
  City, district, town, or any other similar component of the address associated with the deal’s payment information.
- billing_countrystring
  Country name in the address associated with the deal’s payment information.
- billing_statestring
  State, region, province, county, or any other sub component of the address associated with the deal’s payment information.
- billing_zipcodestring
  ZIP or postal code in the address associated with the deal’s payment information.
- contact_idinteger
  Identifier of the contact object, auto-generated when a contact is created in the Freshworks system.
  The value of contact_id identifies the primary contact associated with the deal for which the document is created.
- cpq_document_template_idinteger
  Identifier of the template based on which the document is created.
- cpq_document_template_namestring
  Organizations can standardize the various types of documents by configuring document templates in the Freshworks system.
  The value of cpq_document_template_name refers to the name of the template based on which the document is created.
- created_atstring
  Timestamp of when the document is created in the Freshworks system, specified in the UTC format.
- creator_idinteger
  Identifier of the user who created the document.
- currency_codestring
  Currency code indicating the currency in which the deal value is expressed the currency code is in the ISO 4217 format.
- currency_codestring
  Currency code indicating the currency in which the deal value is expressed the currency code is in the ISO 4217 format.
- custom_fieldsobject
  Document details specified through custom fields. Note: Custom fields can be configured to obtain additional information about the document. The custom_fields attribute contains the custom field names and corresponding values, as a valid JSON object of key (custom field name)-value (custom field’s value) pairs.
- deal_idinteger
  Identifier of the deal object, auto-generated when a deal is created in the Freshworks system.
  The value of deal_id identifies the deal for which the document is created.
- display_idinteger
  Numeric identifier used as part of the document_number that uniquely identifies a document.
- display_id_prefixstring
  Preconfigured prefix used as part of the document_number that uniquely identifies a document.
  Possible value: DOC
- display_namestring
  Name of the document created.
- document_numberstring
  Identifier of a document, auto-generated when the document is created in the Freshworks system.
  The value of this attribute is a combination of the values of cpq_document.display_id and cpq_document.display_id_prefix.
- document_typeinteger
  Type of the document created. For example, quote, proposal, Non-Disclosure Agreement (NDA), Master Service Agreement (MSA), and so on.
- idinteger
  Identifier of the document object, auto-generated when a document is created in the Freshworks system.
- is_deal_primaryboolean
  Specifies whether a deal is synced with the document created.
  A deal can be synced with a document to ensure that any updates to the products associated with the deal will be automatically synced with the document and vice-versa.
  For more information, see Auto-syncing of deals with documents.
  Possible values: true, false
- is_deletedboolean
  Specifies whether the document is deleted from the Freshworks system.
  Possible values: true, false
- owner_idinteger
  Identifier of the user who is assigned as the owner of the document.
  For onCpqDocumentCreate event, by default the value of this attribute is the same as the creator_id value.
- sales_account_idinteger
  Identifier of the sales account object, auto-generated when a new sales account is configured in the Freshworks system.
  The value of sales_account_id identifies the sales account associated with the deal for which the document is created.
- shipping_addressstring
  Address to which the product is shipped.
- shipping_citystring
  City, district, town, or any other similar component of the address to which the product is shipped.
- shipping_countrystring
  Country to which the product is shipped.
- shipping_statestring
  State, region, province, county, or any other sub component of the address to which the product is shipped.
- shipping_zipcodestring
  ZIP or postal code in the address to which the product is shipped.
- stageinteger
  Document stages can be configured in the Freshworks system based on the business process of the organization. The default document stages are,
  Draft
  Sent to customer
  Accepted
  Declined
  The value of stage is the identifier of the current document stage of the document. When a document is created in the Freshworks system, the document stage is set as draft automatically.
  For onCpqDocumentCreate event, the value of this attribute is the identifier of the Draft stage.
- territory_idinteger
  Identifier of the territory object, auto-generated when a territory is created in the Freshworks system.
  Territories can be configured to group users, so the users can focus on a particular set of customers and their sales activities can be monitored on territory basis.
  The value of territory_id identifies the territory to which the user who created the document is added.
- updated_atstring
  Timestamp of when the document is updated in the Freshworks system, specified in the UTC format.
  For onCpqDocumentCreate, the value of this attribute is the same as the created_at value.
- valid_tillstring
  Validity of the document, specified as a timestamp in the UTC format.

Sample payload

{
  "currentHost": {
    "subscribed_modules": [ "cpq_document" ],
    "endpoint_urls": {
      "freshworks_crm": "https://sample.myfreshworks.com",
      "freshsales": "https://sample.freshsales.io"
    }
  },
  "data": {
    "actor": {
      "id": 0,
      "name": "System",
      "type": "system"
    },
    "associations": {
      "cpq_document_product_associations": [
        {
          "billing_cycle": 1,
          "billing_type": 4,
          "created_at": "2022-10-21T04:29:49.000Z",
          "currency_code": "USD",
          "id": 70000010084,
          "setup_fee": "0.0",
          "unit_price": "13.0"
        },
        {
          "billing_cycle": 1,
          "billing_type": 4,
          "created_at": "2022-10-21T04:29:49.000Z",
          "currency_code": "USD",
          "id": 70000010085,
          "setup_fee": "0.0",
          "unit_price": "12.0"
        }
      ]
    },
    "changes": {
      "misc_changes": {},
      "model_changes": {
        "amount": [
          0,
          677
        ],
        "base_currency_amount": [
          0,
          677
        ],
        "billing_address": [
          "604-5854 Beckford St.",
          null
        ],
        "billing_city": [
          "Glendale",
          null
        ],
        "billing_country": [
          "USA",
          null
        ],
        "billing_state": [
          "Arizona",
          null
        ],
        "billing_zipcode": [
          "100652",
          null
        ],
        "contact_id": [
          8441389,
          8597857
        ],
        "deal_id": [
          6796197,
          6891801
        ],
        "sales_account_id": [
          5135558,
          5212715
        ],
        "updated_at": [
          "2022-09-07T09:12:39Z",
          "2022-09-07T09:15:51Z"
        ],
        "updater_id": [
          523562,
          null
        ],
        "valid_till": [
          "2022-09-22T00:00:00Z",
          "2022-09-30T00:00:00Z"
        ]
      },
      "system_changes": {}
    },
    "cpq_document": {
      "amount": 677,
      "base_currency_amount": "677.0",
      "billing_address": "604-5854 Beckford St.",
      "billing_city": "Glendale",
      "billing_country": "USA",
      "billing_state": "Arizona",
      "billing_zipcode": "100652",
      "contact_id": 8441389,
      "cpq_document_template_id": 168209,
      "cpq_document_template_name": "document copy",
      "created_at": "2022-09-07T09:12:39Z",
      "creator_id": 523562,
      "currency_code": "USD",
      "custom_fields": {
        "cf_number": 2,
        "cf_text": "Hello"
      },
      "deal_id": 6796197,
      "display_id": 1,
      "display_id_prefix": "DOC",
      "display_name": "new doc",
      "document_number": "DOC-1",
      "document_type": 1019868749,
      "id": 153150,
      "is_deal_primary": false,
      "is_deleted": false,
      "owner_id": 523562,
      "sales_account_id": 5135558,
      "shipping_address": "chennai",
      "shipping_city": "chennai",
      "shipping_country": "India",
      "shipping_state": "Tamil Nadu",
      "shipping_zipcode": "600006",
      "stage": 1019868753,
      "territory_id": 818551,
      "updated_at": "2022-09-07T09:12:39Z",
      "valid_till": "2022-09-22T00:00:00Z"
    }
  },
  "event": "onCpqDocumentUpdate",
  "region": "US",
  "timestamp": 1496400354326,
  "version": "2.0"
}

onCpqDocumentDelete

The onCpqDocumentDelete event is triggered and the registered callback method is executed, when a document is deleted from the Freshworks system.

Subscribe to the onCpqDocumentDelete event and register the callback by using the following sample manifest.json content.

manifest.json

"events": {
  "onCpqDocumentDelete": {
    "handler": "onCpqDocumentDeleteCallback"
  }
}

Define the corresponding callback by using the following sample server.js content:

server.js

exports = {
  onCpqDocumentDeleteCallback: function(payload) {
    console.log("Logging arguments from onCpqDocumentDelete event: " + JSON.stringify(payload));
  }
}

Attributes of the data object

actorobject
Information pertaining to the entity who triggered the onCpqDocumentCreate event in the Freshworks system.
- idinteger
  Identifier of the actor who triggered the product event. The value of this attribute is 0 when the value of actor.type is system.
- namestring
  Full name of the actor.
- typestring
  Name of the entity that triggered the onCpqDocumentDelete event.
  Possible value: system
cpq_documentobject
Information pertaining to the document that is deleted from the Freshworks system.
- idstring
  Identifier of the document object, auto-generated when a document is created in the Freshworks system.
- cpq_document_product_association_idsarray of integers
  Identifiers of the products/services associated with the document. This identifier helps purge the system of any association created between the document and the corresponding products, when the onCpqDocumentDelete event deletes a document from the Freshworks system.

Sample payload

{
  "currentHost": {
    "subscribed_modules": [ "cpq_document" ],
    "endpoint_urls": {
      "freshworks_crm": "https://sample.myfreshworks.com",
      "freshsales": "https://sample.freshsales.io"
    }
  },
  "data": {
    "actor": {
      "id": 0,
      "name": "System",
      "type": "system"
    },
    "cpq_document": {
      "cpq_document_product_association_ids": [
        50000002674
      ],
      "id": 50000002175
    }
  },
  "event": "onCpqDocumentDelete",
  "region": "US",
  "timestamp": 1496400354326,
  "version": "2.0"
}

Configure onCpqDocumentCreate, onCpqDocumentUpdate, and onCpqDocumentDeleteOn this page

onCpqDocumentCreate

Attributes of the data object

onCpqDocumentUpdate

Attributes of the data object

onCpqDocumentDelete

Attributes of the data object

Configure onCpqDocumentCreate, onCpqDocumentUpdate, and onCpqDocumentDelete