Opportunity


Table of contents

Overview

Opportunity endpoint can be used to view or add new opportunities in ARM module. To call the opportunity endpoint, use one of the URLs from the following table:

URL GET PUT POST DELETE
https://api.mypcorp.com/opportunity ✔ ✔
https://api.mypcorp.com/opportunity/{OpportunityId} ✔

NB: Currently, the MYP API accepts GET and POST requests. PUT requests will be available in the future.

Get

The following table illustrates which fields can be included when receiving a GET response.

NB: Nested properties are hidden by default. To expand all nested properties, add a query parameter $expand=* to the URL.

Opportunity
Field Description
OpportunityId
integer (Identifier)		 Opportunity id.
Name
string		 The name of the opportunity.
Source
string		 The type of source where this opportunity originated from. If this field is not null, then field ‘SourceDetails’ becomes available. If the value of ‘OpportunitySource’ is ‘Referral’, then ‘SourceDetails’ is not available, but instead ‘ReferrerEmail’, ‘ReferrerOrganisation’, ‘ReferrerFirstName’ and ‘ReferrerLastName’ become available.
Possible values are:
“CallCold”
“CallWarm”
“ClientCustomer”
“EMarketing”
“MarketingEvent”
“Referral”
“SearchEngine”
“Training”
“SocialMedia”
“Other”
SourceDetails
string		 This is a description of where this opportunity originated from. This field is only available if ‘OpportunitySource’ field is not null. If a value of ‘Referral’ is set to ‘OpportunitySource’, then this field is not available.
ReferrerEmail
string 		Email of the person who referred this opportunity. This field is only available if ‘OpportunitySource’ field has a value of ‘Referral’.
ReferrerFirstName
string		 First name of the person who referred this opportunity. This field is only available ‘OpportunitySource’ field has a value of ‘Referral’.
ReferrerLastName
string		 Last name of the person who referred this opportunity. This field is only available ‘OpportunitySource’ field has a value of ‘Referral’.
ReferrerOrganisation
string		 Organisation that referred this opportunity. This field is only available ‘OpportunitySource’ field has a value of ‘Referral’.
Outcome
string		 The outcome of the opportunity. It is only enabled when the ‘OpportunityStage’ value is ‘Result’.
Possible values are:
“Deferred”
“SaleSuccessful”
“SaleUnsuccessful”
OutcomeDate
date		 Date when the ‘Outcome’ has been either successful or unsuccessful. It must be in the past. If the ‘Outcome’ is ‘Deferred’, then this field is disabled.
AddEMarketingContactList
boolean		 Should EMarketing contact list be added to this opportunity. This field is only available if your subscription has access to EMarketing module and if ‘Outcome‘ field has value of ‘Deferred’ or ‘SaleUnsuccessful’.
UpfrontValueOfSale
decimal		 The upfront value of sale in AUD.
ChanceOfSales
decimal		 Percentage change of sales.
RecurringAnnualValue
decimal		 The recurring annual value in AUD.
ExpiryDate
date		 When does this opportunity expire. It must be in the future.
FollowUpDate
date		 Date and time when this opportunity should be followed up. It must be in the future.
ExpectedDate
date		 Date and time when this opportunity is expected to be completed. It must be in the future.
CreationDate
datetime		 The date the Opportunity record was created.
ModifyDate
datetime		 The date when the Opportunity record was last modified.
ArchiveDate
datetime		 Date when the Opportunity was archived, if it has been archived.
OpportunityOwner
object		 Staff member who owns this opportunity.
PrimaryContact
object		 Staff member as the primary contact for this opportunity.
Team
object 		The team to which this opportunity belongs to.
Type
object 		The type of opportunity this is. E.g. ‘Business’, ‘Partner’, ‘Training’, etc.
Stage
object 		The stage where this opportunity is at.
FollowUpStaff
object 		Staff member to follow up.
OutcomeReason
object 		If ‘Outcome’ is a ‘Result’, then outcome reason represents the ‘Reason’ check box area from the front end. If the check box is ticked, it will be in this list.

Example JSON response format:

Plain text
Copy to clipboard
Open code in new window
EnlighterJS 3 Syntax Highlighter
{
"@odata.context": "https://api.mypcorp.com/$metadata#Opportunity(OpportunityOwner(),PrimaryContact(),Team(),OpportunityType(),OpportunityStage(),FollowUpStaff(),OpportunityOutcomeReason())",
"value": [
{
"OpportunityId": 12345,
"Name": "Community Services Client",
"Source": "ClientCustomer",
"SourceDetails": "Client introduced this opportunity",
"ReferrerEmail": "lskywalker@yahoo.com",
"ReferrerFirstName": "Luke",
"ReferrerLastName": "Skywalker",
"ReferrerOrganisation": "Muller Inc",
"Outcome": "SaleSuccessful",
"OutcomeDate": "2022-08-25",
"AddEMarketingContactList": false,
"UpfrontValueOfSale": 100.0,
"ChanceOfSales": 0.5,
"RecurringAnnualValue": 50.0,
"ExpiryDate": "2022-10-25",
"FollowUpDate": "2022-09-01",
"ExpectedDate": "2022-10-20",
"CreationDate": "2022-08-25T00:00:00+10:00",
"ModifyDate": "2022-08-25T00:00:00+10:00",
"ArchiveDate": null,
"OpportunityOwner": {
"StaffGuid": "B6DFFC66-48A5-4540-A747-9D38630E0371",
"FirstName": "Bruce",
"LastName": "Wayne",
"ArchiveDate": null
},
"PrimaryContact": {
"StaffGuid": "90EB386B-D880-419A-A757-C6127D674C6C",
"FirstName": "Johnny",
"LastName": "Lawrence",
"ArchiveDate": null
},
"Team": {
"TeamId": 164,
"Name": "Executive",
"ArchiveDate": null
},
"Type": {
"TypeId": 42,
"Name": "Plan management",
"ArchiveDate": null
},
"Stage": {
"StageId": 42,
"Name": "Proposal",
"ArchiveDate": null
},
"FollowUpStaff": {
"StaffGuid": "00CF9FC0-711F-4DDD-B18E-0640F63E5DDA",
"FirstName": "Morticia",
"LastName": "Addams",
"ArchiveDate": null
},
"OutcomeReason": [
{
"OutcomeReasonId": 3000,
"Name": "Understood needs",
"ArchiveDate": null
}
]
}
]
}
{ "@odata.context": "https://api.mypcorp.com/$metadata#Opportunity(OpportunityOwner(),PrimaryContact(),Team(),OpportunityType(),OpportunityStage(),FollowUpStaff(),OpportunityOutcomeReason())", "value": [ { "OpportunityId": 12345, "Name": "Community Services Client", "Source": "ClientCustomer", "SourceDetails": "Client introduced this opportunity", "ReferrerEmail": "lskywalker@yahoo.com", "ReferrerFirstName": "Luke", "ReferrerLastName": "Skywalker", "ReferrerOrganisation": "Muller Inc", "Outcome": "SaleSuccessful", "OutcomeDate": "2022-08-25", "AddEMarketingContactList": false, "UpfrontValueOfSale": 100.0, "ChanceOfSales": 0.5, "RecurringAnnualValue": 50.0, "ExpiryDate": "2022-10-25", "FollowUpDate": "2022-09-01", "ExpectedDate": "2022-10-20", "CreationDate": "2022-08-25T00:00:00+10:00", "ModifyDate": "2022-08-25T00:00:00+10:00", "ArchiveDate": null, "OpportunityOwner": { "StaffGuid": "B6DFFC66-48A5-4540-A747-9D38630E0371", "FirstName": "Bruce", "LastName": "Wayne", "ArchiveDate": null }, "PrimaryContact": { "StaffGuid": "90EB386B-D880-419A-A757-C6127D674C6C", "FirstName": "Johnny", "LastName": "Lawrence", "ArchiveDate": null }, "Team": { "TeamId": 164, "Name": "Executive", "ArchiveDate": null }, "Type": { "TypeId": 42, "Name": "Plan management", "ArchiveDate": null }, "Stage": { "StageId": 42, "Name": "Proposal", "ArchiveDate": null }, "FollowUpStaff": { "StaffGuid": "00CF9FC0-711F-4DDD-B18E-0640F63E5DDA", "FirstName": "Morticia", "LastName": "Addams", "ArchiveDate": null }, "OutcomeReason": [ { "OutcomeReasonId": 3000, "Name": "Understood needs", "ArchiveDate": null } ] } ] }
{
  "@odata.context": "https://api.mypcorp.com/$metadata#Opportunity(OpportunityOwner(),PrimaryContact(),Team(),OpportunityType(),OpportunityStage(),FollowUpStaff(),OpportunityOutcomeReason())",
  "value": [
    {
      "OpportunityId": 12345,
      "Name": "Community Services Client",
      "Source": "ClientCustomer",
      "SourceDetails": "Client introduced this opportunity",
      "ReferrerEmail": "lskywalker@yahoo.com",
      "ReferrerFirstName": "Luke",
      "ReferrerLastName": "Skywalker",
      "ReferrerOrganisation": "Muller Inc",
      "Outcome": "SaleSuccessful",
      "OutcomeDate": "2022-08-25",
      "AddEMarketingContactList": false,
      "UpfrontValueOfSale": 100.0,
      "ChanceOfSales": 0.5,
      "RecurringAnnualValue": 50.0,
      "ExpiryDate": "2022-10-25",
      "FollowUpDate": "2022-09-01",
      "ExpectedDate": "2022-10-20",
      "CreationDate": "2022-08-25T00:00:00+10:00",
      "ModifyDate": "2022-08-25T00:00:00+10:00",
      "ArchiveDate": null,
      "OpportunityOwner": {
        "StaffGuid": "B6DFFC66-48A5-4540-A747-9D38630E0371",
        "FirstName": "Bruce",
        "LastName": "Wayne",
        "ArchiveDate": null
      },
      "PrimaryContact": {
        "StaffGuid": "90EB386B-D880-419A-A757-C6127D674C6C",
        "FirstName": "Johnny",
        "LastName": "Lawrence",
        "ArchiveDate": null
      },
      "Team": {
        "TeamId": 164,
        "Name": "Executive",
        "ArchiveDate": null
      },
      "Type": {
        "TypeId": 42,
        "Name": "Plan management",
        "ArchiveDate": null
      },
      "Stage": {
        "StageId": 42,
        "Name": "Proposal",
        "ArchiveDate": null
      },
      "FollowUpStaff": {
        "StaffGuid": "00CF9FC0-711F-4DDD-B18E-0640F63E5DDA",
        "FirstName": "Morticia",
        "LastName": "Addams",
        "ArchiveDate": null
      },
      "OutcomeReason": [
        {
          "OutcomeReasonId": 3000,
          "Name": "Understood needs",
          "ArchiveDate": null
        }
      ]
    }
  ]
}

Post

New Opportunities can be added by using a POST request. An example of POST URL is:

POST https://api.mypcorp.com/opportunity

The following table illustrates which fields can be included when sending a POST request. A number next to the data type (e.g. string (500)), is the maximum number of characters for this field. All required fields must be included in the request body to get a successful response. Dates must be set in the format YYYY-MM-DD hh:mm:ss[.nnn].

Opportunity
ield Description Required
TemplateGuid
Guid		 This is an id for OpportunityTemplate. If it is provided, then values from the template are used to populate the fields. If other values are provided in the request, these fields will override the values from the template. Optional
Name
string (100)		 The name of the opportunity. Required
Source
string 		The type of source where this opportunity originated from. If this field is not null, then field ‘SourceDetails‘ becomes available. If the value of ‘OpportunitySource‘ is ‘Referral’, then ‘SourceDetails‘ is not available, but instead ‘ReferrerEmail‘, ‘ReferrerOrganisation‘, ‘ReferrerFirstName‘ and ‘ReferrerLastName‘ become available.
Possible values are:
“CallCold”
“CallWarm”
“ClientCustomer”
“EMarketing”
“MarketingEvent”
“Referral”
“SearchEngine”
“Training”
“SocialMedia”
“Other”		 Optional
SourceDetails
string (90) 		This is a description of where this opportunity originated from. This field is only available if ‘OpportunitySource‘ field is not null. If a value of ‘Referral’ is set to ‘OpportunitySource‘, then this field is not available. Optional
ReferrerEmail
string (90)		 Email of the person who referred this opportunity. This field is only available if ‘OpportunitySource‘ field has a value of ‘Referral’. Optional
ReferrerFirstName
string (90)		 First name of the person who referred this opportunity. This field is only available ‘OpportunitySource‘ field has a value of ‘Referral’. Optional
ReferrerLastName
string (90)		 Last name of the person who referred this opportunity. This field is only available ‘OpportunitySource‘ field has a value of ‘Referral’. Optional
ReferrerOrganisation
string (90)		 Organisation that referred this opportunity. This field is only available ‘OpportunitySource‘ field has a value of ‘Referral’. Optional
Outcome
string		 The outcome of the opportunity. It is only enabled when the ‘OpportunityStage‘ value is ‘Result’. Required for POST requests if the field is active. If no value is provided, a default value of ‘Deferred’ is set in the POST request.
Possible values are:
“Deferred”
“SaleSuccessful”
“SaleUnsuccessful”		 Required
(conditional)
OutcomeDate
datetime		 Date when the ‘Outcome‘ has been either successful or unsuccessful. It must be in the past. If the ‘Outcome‘ is ‘Deferred’, then this field is disabled. If no value is provided and the field is set as required, a default value of the current datetime is set in the POST request. Optional
AddEMarketingContactList
boolean		 Should EMarketing contact list be added to this opportunity. This field is only available if your subscription has access to EMarketing module and if ‘Outcome‘ field has value of ‘Deferred’ or ‘SaleUnsuccessful’. If no value is provided, a default value of ‘false’ is set in the POST request. Optional
UpfrontValueOfSale
decimal		 The upfront value of sale in AUD. Optional
ChanceOfSales
decimal		 Percentage change of sales. Optional
RecurringAnnualValue
decimal		 The recurring annual value in AUD. Optional
ExpiryDate
datetime		 When does this opportunity expire. It must be in the future. Optional
FollowUpDate
datetime		 Date and time when this opportunity should be followed up. It must be in the future. Optional
ExpectedDate
datetime		 Date and time when this opportunity is expected to be completed. It must be in the future. Optional
OpportunityOwner
object		 Staff member who owns this opportunity. Required
PrimaryContact
object		 Staff member as the primary contact for this opportunity. Optional
Team
object		 The team to which this opportunity belongs to. Required for POST requests if the field is active and if opportunity owner is part of at least 1 team. Required
(conditional)
Type
object		 The type of opportunity this is. E.g. ‘Business’, ‘Partner’, ‘Training’, etc. Optional
Stage
object		 The stage where this opportunity is at. Required
FollowUpStaff
object		 Staff member to follow up. Required for POST requests if the field is active. Required
(conditional)
OutcomeReason
object		 If ‘Outcome‘ is a ‘Result’, then outcome reason represents the ‘Reason’ check box area from the front end. If the check box is ticked, it will be in this list. Optional

Example JSON request format:

Plain text
Copy to clipboard
Open code in new window
EnlighterJS 3 Syntax Highlighter
{
"value": [
{
"TemplateGuid": "6F1F78DD-D933-4E91-B2C7-114362C1D436",
"Name": "Community Services Client",
"Source": "ClientCustomer",
"SourceDetails": "Client introduced this opportunity",
"ReferrerEmail": "lskywalker@yahoo.com",
"ReferrerFirstName": "Luke",
"ReferrerLastName": "Skywalker",
"ReferrerOrganisation": "Muller Inc",
"Outcome": "SaleSuccessful",
"OutcomeDate": "2022-08-25T00:00:00+10:00",
"AddEMarketingContactList": false,
"UpfrontValueOfSale": 100.0,
"ChanceOfSales": 0.5,
"RecurringAnnualValue": 50.0,
"ExpiryDate": "2022-10-25T00:00:00+10:00",
"FollowUpDate": "2022-09-01T00:00:00+10:00",
"ExpectedDate": "2022-10-20T00:00:00+10:00",
"OpportunityOwner": {
"StaffGuid": "B6DFFC66-48A5-4540-A747-9D38630E0371"
},
"PrimaryContact": {
"StaffGuid": "90EB386B-D880-419A-A757-C6127D674C6C"
},
"Team": {
"TeamId": 164
},
"Type": {
"TypeId": 42
},
"Stage": {
"StageId": 42
},
"FollowUpStaff": {
"StaffGuid": "00CF9FC0-711F-4DDD-B18E-0640F63E5DDA"
},
"OutcomeReason": [
{
"OutcomeReasonId": 3000
}
]
}
]
}
{ "value": [ { "TemplateGuid": "6F1F78DD-D933-4E91-B2C7-114362C1D436", "Name": "Community Services Client", "Source": "ClientCustomer", "SourceDetails": "Client introduced this opportunity", "ReferrerEmail": "lskywalker@yahoo.com", "ReferrerFirstName": "Luke", "ReferrerLastName": "Skywalker", "ReferrerOrganisation": "Muller Inc", "Outcome": "SaleSuccessful", "OutcomeDate": "2022-08-25T00:00:00+10:00", "AddEMarketingContactList": false, "UpfrontValueOfSale": 100.0, "ChanceOfSales": 0.5, "RecurringAnnualValue": 50.0, "ExpiryDate": "2022-10-25T00:00:00+10:00", "FollowUpDate": "2022-09-01T00:00:00+10:00", "ExpectedDate": "2022-10-20T00:00:00+10:00", "OpportunityOwner": { "StaffGuid": "B6DFFC66-48A5-4540-A747-9D38630E0371" }, "PrimaryContact": { "StaffGuid": "90EB386B-D880-419A-A757-C6127D674C6C" }, "Team": { "TeamId": 164 }, "Type": { "TypeId": 42 }, "Stage": { "StageId": 42 }, "FollowUpStaff": { "StaffGuid": "00CF9FC0-711F-4DDD-B18E-0640F63E5DDA" }, "OutcomeReason": [ { "OutcomeReasonId": 3000 } ] } ] }
{
  "value": [
    {
      "TemplateGuid": "6F1F78DD-D933-4E91-B2C7-114362C1D436",
      "Name": "Community Services Client",
      "Source": "ClientCustomer",
      "SourceDetails": "Client introduced this opportunity",
      "ReferrerEmail": "lskywalker@yahoo.com",
      "ReferrerFirstName": "Luke",
      "ReferrerLastName": "Skywalker",
      "ReferrerOrganisation": "Muller Inc",
      "Outcome": "SaleSuccessful",
      "OutcomeDate": "2022-08-25T00:00:00+10:00",
      "AddEMarketingContactList": false,
      "UpfrontValueOfSale": 100.0,
      "ChanceOfSales": 0.5,
      "RecurringAnnualValue": 50.0,
      "ExpiryDate": "2022-10-25T00:00:00+10:00",
      "FollowUpDate": "2022-09-01T00:00:00+10:00",
      "ExpectedDate": "2022-10-20T00:00:00+10:00",
      "OpportunityOwner": {
        "StaffGuid": "B6DFFC66-48A5-4540-A747-9D38630E0371"
      },
      "PrimaryContact": {
        "StaffGuid": "90EB386B-D880-419A-A757-C6127D674C6C"
      },
      "Team": {
        "TeamId": 164
      },
      "Type": {
        "TypeId": 42
      },
      "Stage": {
        "StageId": 42
      },
      "FollowUpStaff": {
        "StaffGuid": "00CF9FC0-711F-4DDD-B18E-0640F63E5DDA"
      },
      "OutcomeReason": [
        {
          "OutcomeReasonId": 3000
        }
      ]
    }
  ]
}

Previous article Next article