Sign Up and Get Started Today

Opportunities

  1. /opportunities
  2. /opportunities/view
  3. /opportunities/timeline
  4. /opportunities/save
  5. /opportunities/options
  6. /opportunities/add_tag

/opportunities

GET requests to /opportunities will return an array of objects representing Opportunities. Only opportunities that have not been archived will be returned.

Request

/opportunities?api_token=api_token_here

The following parameters can be included in the query-string of the request (in any order), anything else will be ignored.

Paging

limitA number between 1 and 100 (inclusive) that indicates how many results you want returned. Default is 30
pageA number that indicates which page to return

Filtering

created_before A date/timestamp that will act as an upper bound on the creation/updated times of opportunity. Anything parseable by PHP's strtotime method will be accepted, so '2009-03-01', '2009-03-01 12:30:12', '-7 days', 'last wednesday' are all acceptable. To avoid confusion, we reccomend you include a timezone if you are not in Europe/London.
created_after
updated_before
updated_after

Response

{
   "status":"success",
   "opportunities":[
      {
      	 "id": 1234,
         "name":"New Site Design",
         [...]
      },
      {
         "id":5678,
         "name":"Boating eCommerce Website",
         [...]
      }
   ],
   "cur_page":1,
   "num_pages":1,
   "per_page":30,
   "total":18
}
statusWill be 'success' or 'error'.
messagesIf status='error', then messages will contain an array of error messages (as strings).
opportunitiesIf status='success', then this will be an array of opportunities (as objects). If there are no opportunities returned, then the array will be empty.
cur_pageAn integer that shows which page of results has been returned (will be 1 unless you specified otherwise in your request).
num_pagesAn integer that shows how many pages of results are available to be returned, given the same constraints and value for per_page.
per_pageAn integer that shows how many results are being returned per request. On all but the last page, this will be the same as the number of items in the opportunities array.
totalAn integer that shows the total number of opportunities in the list. If no constraints are supplied, then this is the total number of opportunities in your account.

The fields returned for each opportunity are identical to those when using /opportunities/view, and are explained in more detail in that section.

/opportunities/view

GET requests to /opportunities/view/XYZ will return the Opportunity with ID XYZ.

Request

/opportunities/view/1234?api_token=api_token_here

This method takes no other parameters.

Response

{
   "status":"success",
   "opportunity":{
      "name":"Boating eCommerce Website",
      "description":"They're after a new website for selling boat accessories",
      "organisation":"Acme Boats Ltd.",
      "id":1234,
      "probability":70,
      "organisation_id":9876,
      "cost":100000,
      "archived":false,
      "status":"New",
      "type":null,
      "source":null,
      "owner":"paul",
      "assigned_to":"paul",
      "alteredby":"paul",
      "created":"2009-02-02T15:31:43+00:00",
      "lastupdated":"2009-02-02T15:31:43+00:00",
      "enddate":"2009-03-06",
      "person_id":87254,
      "person":"Bill Smith"
   }
}
statusWill be 'success' or 'error'.
messagesIf status='error', then messages will contain an array of error messages (as strings).
opportunityIf status='success', then this will be an object containing all the properties of the opportunity.

/opportunities/timeline

GET requests to /opportunities/timeline with an ID parameter will return an array of the Notes attached to the opportunity.

Request

/opportunities/timeline?api_token=api_token_here&id=1234

This method expects exactly one other parameter:

idThe ID of the opportunity you wish to get the timeline for

Response

{
   "status":"success",
   "timeline":[
      {
         "note":{
            "title":"Invoices Sent",
            "note":"They have never received the invoices so have resent them.",
            "opportunity":null,
            "opportunity":"Chase Invoices",
            "organisation":"Acme Corp.",
            "id":885,
            "opportunity_id":null,
            "opportunity_id":1234,
            "organisation_id":12676,
            "private":false,
            "owner":"george",
            "created":"2007-11-02T12:58:50+00:00",
            "lastupdated":"2007-11-02T12:58:50+00:00",
            "person_id":null,
            "person":null
         }
      }
   ]
}

A successful request will include an array of objects representing Notes and Emails)

statusWill be 'success' or 'error'.
messagesIf status='error', then messages will contain an array of error messages (as strings).
timelineIf status='success', then timeline will contain an array of notes and emails (as objects).

/opportunities/save

POST requests to /opportunities/save with a JSON representation of an Opportunity in the body will result in it being saved. If you include an ID then we'll assume you're attempting an update on an existing company, with no ID we'll attempt to create a new one. The ID of the company saved will be included in the response. For organisations, the name and enddate fields are compulsory, the other fields can be left out. Be sure to set the Content-Type header to application/json.

Request

POST /opportunities/save/?api_token=api_token_here HTTP/1.1
Host: sample.tactilecrm.com
Content-type: application/json

{"Opportunity":{"name":"Website Redesign", "assigned_to":"greg"}}

nameRequired.
descriptionA longer description of the opportunity
type_idA reference to the user-configurable id. See /opportunities/options for details
person_idThe ID of a Person to which the opportunity is related
organisation_idThe ID of an Organisation to which the opportunity is related
assigned_toA username. If omitted, the current-user will be assumed.
costA number (float) that indicates the cost/value of the opportunity.
probabilityAn multiple of 5 between 0 and 100 (inclusive) indicating the likelihood of winning.
status_idThe ID associated with the status of the opportunity. (see "options")
source_idThe ID associated with the source of the opportunity. (see "options")
type_idThe ID associated with the type of the opportunity. (see "options")
enddateRequired. A date ('YYYYY-MM-DD').

For 'todo' opportunities:

dateThe date on which the opportunity is due. Format as 'YYYY-MM-DD'.
timeThe time at which the opportunity is due. Only valid if a date is also supplied. Format as 'HH:MM'.
laterIf a date isn't supplied, this should be set to 'true' to indicate the 'todo' has no due-date.

For 'event' opportunities:

dateThe date on which the event starts. Format as 'YYYY-MM-DD'.
timeThe time at which the event starts. Only valid if a date is also supplied. Format as 'HH:MM'.
locationWhere the event is taking place.
end_dateThe date the opportunity ends.
end_timeThe time the opportunity ends, only valid if a date is supplied.

Response

{
   "status":"success",
   "id":12346
}

A successful request will return the ID of the opportunity that's been saved. You can use this with /opportunities/view to subsequently retrieve the details.

statusWill be 'success' or 'error'
messagesIf status='error', then messages will return an array of error messages.
idIf status='success', then id will contain the (integer) ID of the opportunity.

/opportunities/options

GET requests to /opportunities/options will return an array of objects containing the possible values for enumerated fields - those which it would make sense to display as an HTML Select element (or a 'Listbox').

Request

/organisations/options?api_token=api_token_here

This method takes no other parameters.

Response

{
   "status":"success",
   "opportunity_options":{
      "assigned_to":{
         "dave":"dave",
         "david":"david",
         [...]
      },
      "status":{
         "1":"New",
         "2":"Preliminaries",
         "3":"Discussion",
         "4":"Negotiation",
         "5":"Won",
         "6":"Lost",
         [...]
      },
      "type":{
         "1":"Exisiting Business",
         "2":"New Business"
      },
      "source":{
         "3":"Google",
         "17":"Newsletters",
         "8":" Website",
         "394":"Telemarketing (Internal)",
         "5":"Word of Mouth",
         "7":"Yellow Pages",
         [...]
      }
   }
}

assigned_to contains a list of users. The remaining keys contain maps of values for the status_id, type_id and source_id fields.

/opportunities/add_tag/

Adds a tag to an opportunity.

Request

/opportunities/add_tag/?api_token=api_token_here&id=opportunity_id&tag=tag_name

Response

{
	"status":"success", 
	"tag":"My Event"
}
idRequired. The ID of the opportunity to attach the tag to.
tagRequired. The name of the tag to add to the opportunity.