Add or Update Opportunity

Add or Update Opportunity

POST [PlatformAddress]/api/1.0/venue?action=addOrUpdateOpportunity

200

{
  "success": true,
  "id": 755
}

Opportunity

Property	Type	Required	Description
id	integer	optional	The unique identifier of opportunity. A new opportunity will be created if this parameter is not present.
venueId	integer	required	The unique id of the venue to which the opportunity belongs.
name	string	optional	The name for the opportunity (Required when id is missing).
description	string	optional	The description for the opportunity.
companyId	integer	optional	The unique id of the company to assign to the opportunity. See assigning a company/contact to the opportunity.
company	object	optional	The data array of company. See addOrUpdateCompany API in contact namespace for parameters.
companyLeadContactId	integer	optional	The unique id of the company contact to assign to the opportunity See assigning a company/contact to the opportunity.
contactId	integer	optional	The unique id of the contact to assign to the opportunity See assigning a company/contact to the opportunity.
contact	object	optional	The data array of contact. See addOrUpdateContact API in contact namespace for parameters.
qualityId	integer	optional	The unique id of the quality.
industryId	integer	optional	The unique id of industry.
sourceId	integer	optional	The unique id of source (Required when the ID parameter is missing)
ownerUserId	integer	optional	The id of the sales person user assigned to the opportunity. The privileges of the user assigned to the api key may prevent this from being changed.
typeId	integer	optional	The unique id of type (Required when id is missing).
stageId	integer	optional	The unique id of stage.
stageReasonId	integer	optional	The unique stage reason id of opportunity.
channelId	integer	optional	The unique id of channel.
utmSource	string	optional	The source of the campaign. (only when adding)
utmMedium	string	optional	What medium the campaign used/uses. (only when adding)
utmCampaign	string	optional	The name of the campaign. (only when adding)
utmTerm	string	optional	The Term of the campaign. (only when adding)
utmContent	string	optional	Any content about the campaign.
referralContactId	integer	optional	The contact Id of referral for "Referral Program" source. (Required when the source is Referral Program and referralContact parameter is missing)
referralContact	object	optional	The data array of contact. See addOrUpdateContact API in contact namespace for parameters.
referralCompanyId	integer	optional	The company Id of referral for "Referral Program" source. (Required when the source is Referral Program and referralCompany parameter is missing)
referralCompany	object	optional	The data array of company. See addOrUpdateCompany API in contact namespace for parameters.
confirmedQuoteId	integer	optional	The unique if of confirmed quote to which the opportunity belongs.
confirmedQuoteStatus	integer	optional	The status of the confirmed quote to which the opportunity belongs.
cancelledQuoteId	integer	optional	The unique id of cancelled quote to which the opportunity belongs.
lostToCompetition	integer	optional	The unique id of lost reason.
closedDate	date	optional	The close date of the opportunity.
customFields	array	optional	The custom field values of the opportunity. A custom field value might be required depending on how it has been configured in the venue's account. See Custom Field
externalUrls	array	optional	This is an array of External URL field objects of the opportunity (a maximum of 3 objects allowed). When set to null, it will remove all externalUrls from the opportunity. See External Url
## Custom Field

A opportunity custom field is an object with the following details.

Property	Type	Required	Description
fieldId	integer	required	The unique id of the opportunity custom field
fieldValue	mixed	required	The value of the opportunity custom field. Depends on the type of custom field value.

External URL Field

An External URL field is an object with the following details.

Property	Type	Required	Description
ref	string	required	The unique reference key of the external URL
url	string	optional	The url link (https) scheme eg. https://example.com When the value is null, the external url record will be removed based on the provided reference key.
label	string	optional	The label of the URL to display.

Special Considerations

Assigning a company/contact to the opportunity

The contact type of a opportunity is either a company or a contact. When companyId or company is present in the request then the contact type of the opportunity is set to company, and the companyLeadContactId or contact must be a contact that belongs to that company. Otherwise the contact type of the opportunity is set to contact and contactId can be any valid contact in the venue's account.

If contact and company are present in request then it will link given contact to company.

Example Request

Add Opportunity

{
  "venueId": "107",
  "name": "Lead By API",
  "company" : {
    "businessName": "Business Name",
    "updateIfExists": true
  },
  "contact" : {
    "firstName" : "First",
    "lastName" : "Last",
    "email" : "[e-mail]",
    "updateIfExists" : true
  },
  "typeId": "18",
  "sourceId": "25",
  "stageId": "69",
  "industryId": "77",
  "stageReasonId": "127",
  "closedDate": "2017-05-05",
  "referralCompany": {
    "businessName": "Business",
    "primaryContact": {
      "firstName": "Test",
      "lastName": "Test",
      "email": "[e-mail]"
    }
  },
  "referralContact": {
    "firstName": "Test",
    "lastName": "Test",
    "email": "[e-mail]"
  }
}

Update Opportunity

{
  "id": 755,
  "venueId": "107",
  "name": "Updated Name"
}

Returns

Property	Description
success	Whether or not the opportunity was added to the venue
id	The unique id of the opportunity

Throws

Code	Description
Specific Code: 24221	The request is empty
Specific Code: 24222	The opportunity does not exist
Specific Code: 24224	The opportunity details are invalid

This call takes values for a opportunity, and either

1. Updates the values for that opportunity (after you have provided an id in the parameters), or

2. Adds the opportunity to the system (if the id parameter is missing)

The result of this call will contain the status of the result (either true or false) and the opportunity identifier of the updated or newly