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

limit	A number between 1 and 100 (inclusive) that indicates how many results you want returned. Default is 30
page	A 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
}

status	Will be 'success' or 'error'.
messages	If status='error', then messages will contain an array of error messages (as strings).
opportunities	If 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_page	An integer that shows which page of results has been returned (will be 1 unless you specified otherwise in your request).
num_pages	An integer that shows how many pages of results are available to be returned, given the same constraints and value for per_page.
per_page	An 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.
total	An 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"
   }
}

status	Will be 'success' or 'error'.
messages	If status='error', then messages will contain an array of error messages (as strings).
opportunity	If 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:

id	The 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)

status	Will be 'success' or 'error'.
messages	If status='error', then messages will contain an array of error messages (as strings).
timeline	If 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"}}

name	Required.
description	A longer description of the opportunity
type_id	A reference to the user-configurable id. See /opportunities/options for details
person_id	The ID of a Person to which the opportunity is related
organisation_id	The ID of an Organisation to which the opportunity is related
assigned_to	A username. If omitted, the current-user will be assumed.
cost	A number (float) that indicates the cost/value of the opportunity.
probability	An multiple of 5 between 0 and 100 (inclusive) indicating the likelihood of winning.
status_id	The ID associated with the status of the opportunity. (see "options")
source_id	The ID associated with the source of the opportunity. (see "options")
type_id	The ID associated with the type of the opportunity. (see "options")
enddate	Required. A date ('YYYYY-MM-DD').

For 'todo' opportunities:

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

For 'event' opportunities:

date	The date on which the event starts. Format as 'YYYY-MM-DD'.
time	The time at which the event starts. Only valid if a date is also supplied. Format as 'HH:MM'.
location	Where the event is taking place.
end_date	The date the opportunity ends.
end_time	The 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.

status	Will be 'success' or 'error'
messages	If status='error', then messages will return an array of error messages.
id	If 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"
}

id	Required. The ID of the opportunity to attach the tag to.
tag	Required. The name of the tag to add to the opportunity.