Back to index

FOREST CRM - XML Opportunity API

This API provides the following services:

List opportunities

Request

The request format is:

https://app.forestcrm.hu/api/xml/<API KEY>/opportunities

Request parameters:

companyId (optional):
id of the company whose opportunities are queried,

If no parameters are supplied, all opportunities for the tenant are returned.

Example

https://app.forestcrm.hu/api/xml/demo/opportunities?companyId="5206"

Response

Response conforms the attached XSD.

Notes:

Example

<opportunities>
  <opportunity id="2462">
    <updated>2011-03-20T00:00:00+01:00</updated>
    <company id="8092">First Partner</company>
    <name>Sell goldfish in bars to hedge against inflation</name>
    <responsible>Mouse, The Grey</responsible>
    <comment/>
    <product>Brilliant Ideas</product>
    <rejected>false</rejected>
    <status>Lead</status>
    <probability/>
    <opportunity_date>2011-01-10</opportunity_date>
    <opportunity_total>
      <value>200000</value>
      <currency>USD</currency>
    </opportunity_total>
    <categories/>
    <external_ref>8A99B-D4</external_ref>
  </opportunity>
  <opportunity id="2463">
    <updated>2011-03-20T00:00:00+01:00</updated>
    <company id="8097">Sixth Partner</company>
    <name>Let's come up with an inflatable spaceship</name>
    <responsible>Bunny, The Brain</responsible>
    <comment/>
    <product>Successful(?) Projects</product>
    <rejected>false</rejected>
    <status>Contract expired</status>
    <probability>0.75</probability>
    <opportunity_date>2011-01-10</opportunity_date>
    <opportunity_total>
      <value>500000</value>
      <currency>USD</currency>
    </opportunity_total>
    <offer_date>2011-02-21</offer_date>
    <offer_total>
      <value>200000</value>
      <currency>USD</currency>
    </offer_total>
    <contract_date>2011-03-14</contract_date>
    <contract_expiration_date>2011-04-21</contract_expiration_date>
    <contract_total>
      <value>200000</value>
      <currency>USD</currency>
    </contract_total>
    <categories>
      <category>Manufacturing</category>
      <category>Service</category>
    </categories>
  </opportunity>
</opportunities>

Create new opportunity

Request

The request format is:

https://app.forestcrm.hu/api/xml/<API KEY>/opportunities

Request HTTP method: POST

Request parameters (optional params default to empty unless noted otherwise):

opportunity["name"]:
Name of the opportunity.
opportunity["salesrep_id"]:
The ID of the user (salesrep) who is assigned to the opportunity. Can be retrieved via the User API.
opportunity["company_id"]:
The ID of the company associated with the opportunity. Can be retrieved via the Company API.
opportunity["product_id"]:
The ID of the product associated with the opportunity. Can be retrieved via the Product API.
opportunity["turned_down"]:
True if the client declined the offer (or the contract). Optional, defaults to false.
opportunity["opportunity_date"]:
Date when we learned about the opportunity. Required.
opportunity["opportunity_total"]:
Total amount of the opportunity (integer). Optional.
opportunity["probability"]:
Probability the opportunity (integer, 0..100). Optional.
opportunity["offer_date"]:
Date when an offer has been sent to the partner. Optional, mandatory if offer_total has a value.
opportunity["offer_total"]:
Total amount of the offer (integer). Optional.
opportunity["contract_date"]:
Date when an contract has been sent to the partner. Optional, mandatory if contract_total has a value.
opportunity["contract_total"]:
Total amount of the contract (integer). Optional.
opportunity["auto_sum_contract_total"]:
Set to true if contract total should be calculated as the sum of invoices. Optional, defaults to false. Note that calculation result overrides manually set value.
opportunity["contract_expiration_date"]:
Date when an contract ends. Optional.
opportunity["comment"]:
Free comment text. Optional.
opportunity["project_manager_id"]:
The ID of the user (salesrep) who is associated with the opportunity as project manager. Can be retrieved via the User API. Optional.
opportunity["started_on"]:
Date when actual (project/delivery) work started. Optional.
opportunity["finished_on"]:
Date when actual (project/delivery) work finished. Optional.
opportunity["is_closed"]:
Set to true if delivery/project has been fully completed and should be removed from 'pending' reports. Optional, defaults to false.
opportunity["external_ref"]:
External reference to the entity. Optional.

Example

POST https://app.forestcrm.hu/api/xml/demo/opportunities

Header:

Content-Type: application/json

Body:

{
  "opportunity": {
    "name": "Selling Brillinace with Grace",
    "salesrep_id": 2400,
    "company_id": 14566,
    "product_id": 357,
    "offer_date": '2012-09-18',
    "offer_total": 60000
  }
}

Response

If the opportunity could be created the response is of status code 200 and the body contains the the ID of the opportunity created in XML format:

  <opportunity>
    <id type="integer">19373</id>
  </opportunity>

Errors are reported with a status code (422) and the response body contains the errors in XML format.

Update (modify) an existing opportunity

Request

The request format is:

https://app.forestcrm.hu/api/xml/<API KEY>/opportunities/<opportunity ID>
or 
https://app.forestcrm.hu/api/xml/<API KEY>/opportunities/<opportunity ID>?external_ref
external_ref
If present (with any value or without value), `id` is interpreted as an external reference ("external id").

Request HTTP method: PUT

Request parameters: same as in create

Note that the requested attributes get updated (overwritten), missing attributes don't change.

Example

PUT https://app.forestcrm.hu/api/xml/demo/opportunities/19373

Header:

Content-Type: application/json

Body:

{
  "opportunity": {
    "contract_date": '2012-09-20',
    "contract_total": 50000
  }
}

Response

If the opportunity could be updated the response is of status code 200.

Errors are reported with a status code (422) and the response body contains the errors in XML format.

Back to index