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:

    {
  "@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:

    {
  "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