V2: Opportunity (Put)

Description

Updates an existing opportunity with new information. Requires specifying the opportunity type (Pre or Post).

HTTP Method

put

URL

/api/v2/opportunities/{Id}

Query Parameters

Parameter	Type	Location	Required	Description
OpportunityId	integer	Route	Yes	The unique identifier of the opportunity defined by Nexus. This is not the CRM Opportunity ID(minimum value: 1)
opportunityType	string	Query	Yes	Type of opportunity: "Pre" or "Post"
LanguageId	integer	Query	No	Language ID for localized content (default: 1)

Request Body Structure

{
  "OpportunityName": "string",
  "OpportunityID": "string", 
  "CategoryName": "string",
  "StageName": "string",
  "AcctPotential": 0.00,
  "SalesRevenue": 0.00,
  "PendingCloseDate": "2024-12-31"
}

Request Body Fields

Field	Type	Required	Description
OpportunityName	string	No	Name/title of the opportunity
OpportunityID	string	No	External CRM opportunity identifier
CategoryName	string	No	Category name (must match existing category)
StageName	string	No	Stage name (must match existing stage)
AcctPotential	decimal	No	Account potential value
SalesRevenue	decimal	No	Expected sales revenue
PendingCloseDate	string	No	Expected close date (format: yyyy-MM-dd, MM/dd/yyyy, or dd/MM/yyyy)

Request Examples

# Update pre-visit opportunity
PUT /api/v2/opportunities/123?opportunityType=Pre
Authorization: Bearer {your-token}
Content-Type: application/json

{
  "OpportunityName": "Updated Product Launch",
  "CategoryName": "New Business",
  "StageName": "Qualified",
  "AcctPotential": 200000.00,
  "SalesRevenue": 100000.00,
  "PendingCloseDate": "2024-12-31"
}

# Update post-visit opportunity
PUT /api/v2/opportunities/456?opportunityType=Post&LanguageId=1
Authorization: Bearer {your-token}
Content-Type: application/json

{
  "StageName": "Closed Won",
  "SalesRevenue": 150000.00
}

Response Structure

Success Response (200 OK)

{
  "Type": "Pre",
  "ID": 123,
  "VisitID": 456,
  "CustomerID": 789,
  "OpportunityName": "Updated Product Launch",
  "OpportunityID": "OPP-2024-001",
  "OpportunityCategoryID": 1,
  "OpportunityStageID": 3,
  "OpportunityCompetitorID": null,
  "AcctPotential": 200000.00,
  "SalesRevenue": 100000.00,
  "PendingCloseDate": "2024-12-31",
  "VisitCustomerOpportunityID": null,
  "FollowUpSentDate": null
}

Validation Error Response (400 Bad Request)

{
  "ValidationMessage": "Category 'Invalid Category' not found. Please select from available categories.",
  "AvailableCategories": [
    {
      "CategoryID": 1,
      "CategoryName": "New Business"
    },
    {
      "CategoryID": 2,
      "CategoryName": "Existing Business"
    }
  ],
  "AvailableStages": [
    {
      "StageID": 1,
      "StageName": "Prospect"
    },
    {
      "StageID": 2,
      "StageName": "Qualified"
    },
    {
      "StageID": 3,
      "StageName": "Proposal"
    }
  ]
}

Response Codes

Code	Description	Response Type
200	Success	V2OpportunityPrePostFlat
400	Bad Request / Validation Error	V2OpportunityInvalidResponse
401	Not Authorized	string
404	Not Found	ObjectNotFoundResponse
500	Internal Server Error	InternalServerErrorResponse