Opportunity

  • 15.5
This article is may not be up to date with the latest stable release of M4.

Description

The Opportunity endpoint provides the API consumer with access to methods pertaining to opportunities and related data objects. The endpoint allows consumers to load opportunity data, add new opportunities, and update opportunities.

Methods

URL base/CRM/Opportunity/Specification
Action GET
Description Returns a data dictionary that details the available web service methods related to the Opportunity endpoint.
Parameters None
 Returns  A JSON object with method descriptions
Sample Return Object 
[
    {
        "HttpAction": "Get",
        "MethodName": "GetOpportunity",
        "Description": "Returns the record for a single 'Opportunity' given the passed in ID value (see Path).",
        "Path": "/Opportunity/GetOpportunity/25032"
    },
    {
        "HttpAction": "Get",
        "MethodName": "GetOpportunityByEstimate",
        "Description": "Returns the record for a single 'Opportunity' given the passed in Estimate ID value (see Path).",
        "Path": "/Opportunity/GetOpportunityByEstimate/25032"
    },
    {
        "HttpAction": "Get",
        "MethodName": "GetOpportunitiesByLead",
        "Description": "Returns all 'Opportunity' records given the passed in Lead ID value (see Path).",
        "Path": "/Opportunity/GetOpportunitiesByLead/25032"
    },
    {
        "HttpAction": "Get",
        "MethodName": "GetOpportunitiesByContact",
        "Description": "Returns all 'Opportunity' records given the passed in Contact ID value (see Path).",
        "Path": "/Opportunity/GetOpportunitiesByContact/25032"
    },
    {
        "HttpAction": "Post",
        "MethodName": "AddOpportunity",
        "Description": "Creates the record for a single 'Opportunity' and returns the Opportunity object",
        "Format": {
            "Name": "John Smith",
            "Description": null,
            "LeadID": 107,
            "StatusID": 29,
            "MonthlyRevenue": 366.12,
            "InstallFee": 317.82,
            "ContactID": 944,
            "CreatedOn": "2018-06-13T11:08:36.052964-04:00",
            "CreatedBy": "Mapcom",
            "AssignedTo": 586
        }
    },
    {
        "HttpAction": "Post",
        "MethodName": "UpdateOpportunity",
        "Description": "Updates the record for a single 'Opportunity' and returns the Opportunity object",
        "Format": {
            "ID": 406,
            "Name": "John Smith",
            "Description": null,
            "LeadID": 788,
            "StatusID": 87,
            "MonthlyRevenue": 130.91,
            "InstallFee": 85.4,
            "ContactID": 950,
            "CreatedOn": "2018-06-13T11:08:36.0538769-04:00",
            "CreatedBy": "Mapcom",
            "AssignedTo": 824
        }
    },
    {
        "HttpAction": "Get",
        "MethodName": "DeleteOpportunity",
        "Description": "Deletes the record for a single 'Opportunity' given the passed in ID value (see Path).",
        "Path": "/Opportunity/DeleteOpportunity/25032"
    }
]
URL base/CRM/Opportunity/GetOpportunity/ID
Action GET
Description Returns an Opportunity object when given an ID of a valid opportuntiy in the M4 database.
Parameters
Name Required? Type Description
ID Yes Integer An integer value representing the ID of a opportunity in the M4 database.
Returns A JSON Opportunity data object
Sample Return Object 
{
     "ID": 308,
     "Name": "John Smith",
     "Description": null,
     "LeadID": 760,
     "StatusID": 297,
     "MonthlyRevenue": 397.97,
     "InstallFee": 209.71,
     "ContactID": 66,
     "CreatedOn": "2018-06-13T00:28:38.3184667-04:00",
     "CreatedBy": "Mapcom",
     "AssignedTo": 370
}
URL base/CRM/Opportunity/GetOpportunityByEstimate/ID
Action GET
Description Returns an Opportunity object when given an ID of a valid estimate in the M4 database.
Parameters
Name Required? Type Description
ID Yes Integer An integer value representing the ID of a estimate in the M4 database.
Returns A JSON Opportunity data object
Sample Return Object 
{
     "ID": 308,
     "Name": "John Smith",
     "Description": null,
     "LeadID": 760,
     "StatusID": 297,
     "MonthlyRevenue": 397.97,
     "InstallFee": 209.71,
     "ContactID": 66,
     "CreatedOn": "2018-06-13T00:28:38.3184667-04:00",
     "CreatedBy": "Mapcom",
     "AssignedTo": 370
}
URL base/CRM/Opportunity/GetOpportunitiesByLead/ID
Action GET
Description Returns a collection of Opportunity objects when given an ID of a valid lead in the M4 database.
Parameters
Name Required? Type Description
ID Yes Integer An integer value representing the ID of a lead in the M4 database.
Returns A list of JSON Opportunity data objects
Sample Return Object 
[
     {
          "ID": 308,
          "Name": "John Smith",
          "Description": null,
          "LeadID": 760,
          "StatusID": 297,
          "MonthlyRevenue": 397.97,
          "InstallFee": 209.71,
          "ContactID": 66,
          "CreatedOn": "2018-06-13T00:28:38.3184667-04:00",
          "CreatedBy": "Mapcom",
          "AssignedTo": 370
     }
]
URL base/CRM/Opportunity/GetOpportunitiesByContact/ID
Action GET
Description Returns a collection of Opportunity objects when given an ID of a valid Contact in the M4 database.
Parameters
Name Required? Type Description
ID Yes Integer An integer value representing the ID of a contact in the M4 database.
Returns A list of JSON Opportunity data objects
Sample Return Object 
[
     {
          "ID": 308,
          "Name": "John Smith",
          "Description": null,
          "LeadID": 760,
          "StatusID": 297,
          "MonthlyRevenue": 397.97,
          "InstallFee": 209.71,
          "ContactID": 66,
          "CreatedOn": "2018-06-13T00:28:38.3184667-04:00",
          "CreatedBy": "Mapcom",
          "AssignedTo": 370
     }
]
URL base/CRM/Opportunity/AddOpportunity
Action POST
Description Adds the specified opportunity object and returns a the newly created opportunity object.
Parameters
Name Required? Type Description
Name Yes String The full name of the opportunity.
Description No String The description of the opportunity.
LeadID Yes Integer The lead ID of the opportunity.
StatusID Yes Integer The status ID of the opportunity.
MonthlyRevenue No Decimal The monthly revenue of the opportunity.
InstallFee No Decimal The install fee of the opportunity.
ContactID No Integer The contact ID of the opportunity.
CreatedOn Yes DateTime The time the opportunity was created.
CreatedBy Yes String The user who created the opportunity.
AssignedTo Yes Integer The user ID that the opportunity is assigned to.
Sample JSON Package 
{
     "Name": "John Smith",
     "Description": null,
     "LeadID": 760,
     "StatusID": 297,
     "MonthlyRevenue": 397.97,
     "InstallFee": 209.71,
     "ContactID": 66,
     "CreatedOn": "2018-06-13T00:28:38.3184667-04:00",
     "CreatedBy": "Mapcom",
     "AssignedTo": 370
}
Returns A JSON Opportunity data object
Sample Return Object 
{
     "ID": 308,
     "Name": "John Smith",
     "Description": null,
     "LeadID": 760,
     "StatusID": 297,
     "MonthlyRevenue": 397.97,
     "InstallFee": 209.71,
     "ContactID": 66,
     "CreatedOn": "2018-06-13T00:28:38.3184667-04:00",
     "CreatedBy": "Mapcom",
     "AssignedTo": 370
}
Business Rules
Any violations of these business rules result in an appropriate error message being returned to the API consumer.
  • Name: must not be null
  • LeadID: must not be null
  • StatusID: must not be null
  • CreatedOn: must not be null
  • CreatedBy: must not be null
  • AssignedTo: must not be null
URL base/CRM/Opportunity/UpdateOpportunity
Action POST
Description Updates the specified opportunity object and returns a the newly updated opportunity object.
Parameters
Name Required? Type Description
ID Yes Integer The ID of the opportunity.
Name Yes String The full name of the opportunity.
Description No String The description of the opportunity.
LeadID Yes Integer The lead ID of the opportunity.
StatusID Yes Integer The status ID of the opportunity.
MonthlyRevenue No Decimal The monthly revenue of the opportunity.
InstallFee No Decimal The install fee of the opportunity.
ContactID No Integer The contact ID of the opportunity.
CreatedOn Yes DateTime The time the opportunitywas created.
CreatedBy Yes String The user who created the opportunity.
AssignedTo Yes Integer The user ID that the opportunity is assigned to.
Sample JSON Package 
{
     "ID": 308,
     "Name": "John Smith",
     "Description": null,
     "LeadID": 760,
     "StatusID": 297,
     "MonthlyRevenue": 397.97,
     "InstallFee": 209.71,
     "ContactID": 66,
     "CreatedOn": "2018-06-13T00:28:38.3184667-04:00",
     "CreatedBy": "Mapcom",
     "AssignedTo": 370
}
Returns A JSON Opportunity data object
Sample Return Object 
{
     "ID": 308,
     "Name": "John Smith",
     "Description": null,
     "LeadID": 760,
     "StatusID": 297,
     "MonthlyRevenue": 397.97,
     "InstallFee": 209.71,
     "ContactID": 66,
     "CreatedOn": "2018-06-13T00:28:38.3184667-04:00",
     "CreatedBy": "Mapcom",
     "AssignedTo": 370
}
Business Rules
Any violations of these business rules result in an appropriate error message being returned to the API consumer.
  • ID: must not be null
  • Name: must not be null
  • LeadID: must not be null
  • StatusID: must not be null
  • CreatedOn: must not be null
  • CreatedBy: must not be null
  • AssignedTo: must not be null
URL base/CRM/Opportunity/DeleteOpportunity/ID
Action GET
Description Deletes a Opportunity object when given an ID of a valid opportunity in the M4 database.
Parameters
Name Required? Type Description
ID Yes Integer An integer value representing the ID of a opportunity in the M4 database.
Returns A JSON data object
Sample Return Object 
{
  "Message": "The Opportunity with ID [55] was deleted successfully."
}

Was this article helpful?

Yes No

Related Articles