API Documentation

Activities

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

/activities

GET requests to /activities will return an array of objects representing Activities.

Request

/activities?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 activity. 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",
   "activities":[
      {
         "id": 1234,
         "name":"Call Raj",
         "location":null,
         "description":"Raj rang, he would like to talk to you about some call-quality issues they are having with Asterisk.",
         [...]
         "created":"2009-04-02T09:36:58+01:00",
         "lastupdated":"2009-04-02T09:36:58+01:00"
      },
      {
         "id": 5678
         "name":"Contact re Telephony Server",
         "location":null,
         "description":"Barry said that they'd be looking at mid March for the project to go ahead, so check back then",
         [...]
         "created":"2009-02-23T09:23:59+00:00",
         "lastupdated":"2009-02-23T09:23:59+00:00",
         "completed":"2009-03-12T09:01:31+00:00"
      },
      [...]
   ],
   "cur_page":1,
   "num_pages":46,
   "per_page":30,
   "total":1376
}

status	Will be 'success' or 'error'.
messages	If status='error', then messages will contain an array of error messages (as strings).
activities	If status='success', then this will be an array of activities (as objects). If there are no activities 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 activities array.
total	An integer that shows the total number of activities in the list. If no constraints are supplied, then this is the total number of activities in your account.

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

/activities/view

GET requests to /activities/view/XYZ will return the Activity with ID XYZ.

Request

/activities/view/1234?api_token=api_token_here

This method takes no other parameters.

Response

{
   "status":"success",
   "activity":{
      "name":"Call Raj",
      "description":"Raj rang, he would like to talk to you about some call-quality issues they are having with Asterisk.",
      "time":null,
      "type":"Call Back",
      "organisation":"Acme Ltd",
      "opportunity":null,
      "id":1234,
      "organisation_id":26085,
      "opportunity_id":null,
      "assigned_to":"matt",
      "assigned_by":"greg",
      "owner":"greg",
      "alteredby":"greg",
      "created":"2009-04-02T09:36:58+01:00",
      "lastupdated":"2009-04-02T09:36:58+01:00",
      "completed":"2009-04-02T10:32:20+01:00",
      "date":"2009-04-02",
      "person_id":78943,
      "person":"Raj Chapenari",
      "class": "todo"
   }
}

For activities with a class of 'event', there will also be fields for 'location', 'end_date' and 'end_time'.

status	Will be 'success' or 'error'.
messages	If status='error', then messages will contain an array of error messages (as strings).
activity	If status='success', then this will be an object containing all the properties of the activity.

/activities/timeline

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

Request

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

This method expects exactly one other parameter:

id	The ID of the activity 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,
            "activity":"Chase Invoices",
            "organisation":"Acme Corp.",
            "id":885,
            "opportunity_id":null,
            "activity_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. (Emails can't yet be attached to Activities.)

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 (as objects).

/activities/save

POST requests to /activities/save with a JSON representation of an Activity 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, only the name field is compulsory, the other fields can be left out. Be sure to set the Content-Type header to application/json.

Request

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

{"Activity":{"name":"Call Bill", "assigned_to":"greg","date":"2009-03-12", "time":"12:00"}}

There are two classes of Activity: "todo" and "event". They share most of their properties, but there are a few differences outlined below.

name	Required.
description	A longer description of the activity
type_id	A reference to the user-configurable id. See /activities/options for details
opportunity_id	The ID of an Opportunity to which the activity is related
person_id	The ID of a Person to which the activity is related
organisation_id	The ID of an Organisation to which the activity is related
assigned_to	A username. If omitted, the current-user will be assumed.
class	Either 'todo' or 'event'. If omitted, 'todo' will be assumed.

For 'todo' activities:

date	The date on which the activity is due. Format as 'YYYY-MM-DD'.
time	The time at which the activity 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' activities:

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 activity ends.
end_time	The time the activity ends, only valid if a date is supplied.

Response

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

A successful request will return the ID of the activity that's been saved. You can use this with /activities/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 activity.

/activities/options

GET requests to /activities/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",
   "activity_options":{
      "assigned_to":{
          "david":"david",
         "greg":"greg"
         [...]
      },
      "class":{
         "todo":"To Do",
         "event":"Event"
      },
      "type":{
         "1":"Email",
         "2":"Call",
         "3":"Other",
        [...]
      }
   }
}

assigned_to contains a list of users. class contains the values that can be sent for that property. type contains the IDs and string-values for the type_id property.

/activities/add_tag/

Adds a tag to an activity.

Request

/activities/add_tag/?api_token=api_token_here&id=activity_id&tag=tag_name

Response

{
	"status":"success", 
	"tag":"Call Back"
}

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