Uploads deal history.

Method	`upload.deals_history`
API version	—
Description	Uploads deal history.

Available to: Agents and clients

Uploads deal history, including stage transitions and revenue.

To build the End-to-End Analytics report correctly, include at least the deal creation date and either contact details (creation date, email, or phone number) or both communication_id and communication_type. Include revenue when available.

CallGear uses main_contact_ext_id and contact_ext_ids to find communications associated with the contact, such as calls, offline messages, and chats.
communication_id and communication_type link the deal directly to a specific communication.
When contact IDs and communication identifiers are supplied together, communication_id and communication_type take precedence.
Communications created more than 30 days before the deal are excluded from attribution.
Contact or communication links can be changed only when modified_date_time or modified_stage_date_time advances. CallGear then recalculates the deal-to-communication association.

Limitations

Name	Description
`created_date_time`	Must not be in the future.
`modified_stage_date_time`	Must be on or after created_date_time and greater than or equal to the modified_stage_date_time of the most recently uploaded stage.
`closed_date_time`	Must not be earlier than created_date_time. Used in calculations only when the deal is in a success or failed stage.

If any deal record is invalid, the entire request fails. Correct the data and submit the complete request again.

Request parameters

Name	Type	Required	Description
`access_token`	string	yes	Access token used to authenticate the request.
`user_id`	number	no	Unique ID of the client user on whose behalf the agent is making the request. Required for agents. To retrieve a list of client users, use "get.customer_users".
`deals`	array	yes	Deal history records to upload. Maximum: 1,000 records per request.
`ext_id`	string	yes	External deal ID.
`name`	string	yes	Deal name.
`created_date_time`	iso8601	yes	Date and time when the deal was created, in YYYY-MM-DD hh:mm:ss format.
`modified_date_time`	iso8601	no	Date and time when the deal was last updated, in YYYY-MM-DD hh:mm:ss format. Defaults to the time of the API request.
`modified_stage_date_time`	iso8601	yes	Date and time when the deal entered the specified stage, in YYYY-MM-DD hh:mm:ss format.
`closed_date_time`	iso8601	no	Date and time when the deal was closed, in YYYY-MM-DD hh:mm:ss format.
`contact_ext_ids`	array	no	External IDs of contacts associated with the deal. Required when main_contact_ext_id is specified.
`main_contact_ext_id`	string	no	External ID of the deal's primary contact. The value must be included in contact_ext_ids. Required when contact_ext_ids is specified.
`employee_ext_id`	string	no	External ID of the deal owner.
`lead_ext_id`	string	no	External ID of the related lead.
`company_ext_id`	string	no	External IDs of related companies.
`revenue`	number	no	Deal revenue.
`sales_funnel_ext_id`	string	yes	External sales funnel ID.
`stage_ext_id`	string	yes	External sales funnel stage ID.
`comments`	string	no	Comment about the deal.
`source`	string	no	Deal source.
`communication_id`	number	no	ID of the communication associated with the deal. Required when communication_type is specified.
`communication_type`	string	no	Type of communication associated with the deal. Valid values: chat, offline_message, call, goal, email. Required when communication_id is specified.
`user_fields`	array	no	Custom deal fields. Create each field with "create.deal_user_field" before including it here.
`ext_id`	string	yes	External custom field ID.
`value`	string	yes	Custom field value.
`tags`	array	no	Deal tags.
`ext_id`	string	yes	External tag ID.
`name`	string	yes	Tag name.
`child_customer_id`	number	no	ID of the client account in which the deal is created. To retrieve client accounts, use "get.customers".

Example request

{
    "jsonrpc": "2.0",
    "id": "number",
    "method": "upload.deals_history",
    "params": {
        "access_token": "string",
        "user_id": "number",
        "deals": [
            {
                "ext_id": "string",
                "name": "string",
                "created_date_time": "iso8601",
                "modified_date_time":"iso8601",
                "modified_stage_date_time": "iso8601",
                "closed_date_time": "iso8601",
                "contact_ext_ids": [
                    "string"
                ],
                "main_contact_ext_id": "string",
                "employee_ext_id": "string",
                "lead_ext_id": "string",
                "revenue": "number",
                "sales_funnel_ext_id": "string",
                "stage_ext_id": "string",
                "comments": "string",
                "source": "string",
                "communication_id": "number",
                "communication_type": "string",
                "child_customer_id": "number",
                "tags":[
                     {
                        "name": "string",
                        "ext_id": "string"
                     },
                     {
                        "name": "string",
                        "ext_id": "string"
                     }
                ],
                "user_fields":[
                    {
                        "ext_id": "string",
                        "value": "string"
                    },
                    {
                        "ext_id": "string",
                        "value": "string"
                    }
                ]
            }
        ]
    }
}

Example response

{
    "jsonrpc": "2.0",
    "id": "number",
    "result": {
        "data": {},
        "metadata": "object"
    }
}

Possible errors

See the "Errors for upload methods" section.