Sign Up and Get Started Today

Organisations

  1. /organisations
  2. /organisations/mine
  3. /organisations/view
  4. /organisations/contact_methods
  5. /organisations/timeline
  6. /organisations/save
  7. /organisations/save_contact
  8. /organisations/options
  9. /organisations/add_tag

Access to organisations via the API follows the same rules as when using a browser; i.e. Admins will be able to see everything while for other users it will depend on the permissions set against the organisation.

/organisations

Sending GET requests to https://sample.tactilecrm.com/organisations will give you access to an array of Organisation objects order alphabetically by name that can be paged through.

Request

/organisations?api_token=api_token_here&key=value

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

For name and accountnumber, *s will be treated as wildcards in search terms, so for example name=bob* will return all organisations with names beginning 'bob'. Comparisons are case-insensitive.

nameA string to match against the organisation name.
accountnumberA string to match against the account-number field.
created_before A date/timestamp that will act as an upper bound on the creation/updated times of organisations. 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",
   "organisations":[
      {
         "name":"Adam the Plumber",
         "description":null,
         "accountnumber":"ATP01",
         [...]
         "created":"2009-03-13T09:12:24+00:00",
         "lastupdated":"2009-03-16T13:48:22+00:00",
      },
      {
         "name":"Bob The Builder",
         "description":null,
         "accountnumber":"BTB01",
         [...]
         "created":"2009-03-16T13:49:02+00:00",
         "lastupdated":"2009-03-16T13:50:04+00:00",
      },
      [...]
   ],
   "cur_page":1,
   "num_pages":5,
   "per_page":30,
   "total":123
}
statusWill be 'success' or 'error'.
messagesIf status='error', then messages will contain an array of error messages (as strings).
organisationsIf status='success', then this will be an array of organisations (as objects). If there are no organisations 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 organisations array.
totalAn integer that shows the total number of organisations in the list. If no constraints are supplied, then this is the total number of organisations in your account (that you have permission to see).

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

/organisations/mine

GET requests to /organisations/mine will return only those organisations assigned to the user making the request. The request parameters and the form of the response are identical to /organisations, above.

/organisations/mine?api_token=api_token_here

/organisations/view

Sending GET requests to /organisations/view/XYZ will return details for the organisation with ID XYZ.

Request

/organisations/view/1234?api_token=api_token_here

This method takes no other parameters.

Response

{
   "status":"success",
   "organisation":{
      "name":"Bob the Builder",
      "description":"A Building company",
      "accountnumber":"BTB01",
      "vatnumber":"GB 793 814 324",
      "companynumber":"0441343",
      "website":"www.example.com",
      "id":1234,
      "employees":11,
      "creditlimit":2000,
      "parent_id":null,
      "owner":"george",
      "assigned":"george",
      "parent":null,
      "created":"2007-07-31T16:35:09+01:00",
      "lastupdated":"2009-03-17T11:13:15+00:00",
      "street1":"Business Innovation Centre",
      "street2":"Binley Business Park",
      "street3":null,
      "town":"Coventry",
      "county":null,
      "postcode":"CV3 2TX",
      "country":"United Kingdom",
      "status":null,
      "source":null,
      "classification":null,
      "rating":null,
      "industry":null,
      "type":null
   }
}
statusWill be 'success' or 'error'.
messagesIf status='error', then messages will contain an array of error messages (as strings).
organisationIf status='success', then this will be an object containing all the properties of the organisation.

/organisations/contact_methods

GET requests to /organisations/contact_methods with an id parameter will return all of the contact methods (phone numbers, fax numbers and email addresses) for the organisation.

Request

/organisations/contact_methods/?api_token=api_token_here&id=1234

This method expects exactly one other parameter:

idThe (integer) ID of the organisation you wish to get the contact-methods for

Response

{
   "status":"success",
   "contact_methods":[
      {
         "contact":"info@example.com",
         "type":"E",
         "name":"Main",
         "id":3,
         "organisation_id":1234
      },
      {
         "contact":"02476 555 401",
         "type":"F",
         "name":"Main",
         "id":4,
         "organisation_id":1234
      },
      {
         "contact":"02476 555 400",
         "type":"T",
         "name":"Main",
         "id":1,
         "organisation_id":1234
      }
   ]
}
statusWill be 'success' or 'error'.
messagesIf status='error', then messages will contain an array of error messages (as strings).
contact_methodsIf status='success', then contact_methods will contain an array of contact methods (as objects).
contact contains the number/address itself.
type will be one of 'T', 'F', or 'E' (Telephone, Fax and Email respectively).
name will be the user-entered name for the contact method.

/organisations/timeline

GET requests to /organisations/timeline with an id parameter will return all of the Notes and Emails associated with the organisation.

Request

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

This method expects exactly one other parameter:

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

Response

{
   "status":"success",
   "timeline":[
      {
         "note":{
            "title":"Bob Rang",
            "note":"He'd like details of the plumbing",
            "opportunity":null,
            "activity":null,
            "id":16936,
            "opportunity_id":null,
            "activity_id":null,
            "private":false,
            "owner":"george",
            "created":"2009-03-25T11:30:41+00:00",
            "lastupdated":"2009-03-25T11:30:41+00:00",
            "organisation_id":1234,
            "organisation":"Bob the Builder",
            "person_id":null,
            "person":null
         }
      },
      {
         "email":{
            "subject":"Re: New Work",
            "body":"Hi Bob, Please ring us if you need any more information, the office is open all day. George",
            "email_from":"george.step@tactilecrm.com",
            "email_to":"bob@example.com",
            "person":"Bob Builder",
            "opportunity":null,
            "id":3985,
            "person_id":105992,
            "opportunity_id":null,
            "owner":"george",
            "received":"2009-01-13T15:56:00+00:00",
            "created":"2009-01-13T16:00:15+00:00",
            "organisation_id":1234
         }
      }
   ]
}

A successful request will include an array of objects representing a mixture of 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).

/organisations/save

POST requests to /organisations/save with a JSON representation of an organisation as the body of the request 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 /organisations/save/?api_token=api_token_here HTTP/1.1
Host: sample.tactilecrm.com
Content-type: application/json

{"Organisation":{"name":"Acme Corp"}}

The basic properties of an Organisation that you can set at creation, or specify to be updated are:

nameRequired.
accountnumberMust be unique within your account.
description
creditlimitNumeric (integer/float) - don't include a currency symbol
vatnumber
companynumber
website
employeesThe number of employees the organisation has, should be an integer
assignedThe username of the user you wish to assign the organisation to (must exist, and be 'active').
parent_idThe ID of another company
street1The first line of the address
street2The 2nd line of the address
street3The 3rd line of the address
townThe town/city line of the address
countyThe county/state line of the address
postcodeThe postcode/ZIP line of the address
country_codeThe country-code (2-digit, e.g. GB, FR, DE etc.) for the address

In addition, there are a number of fields made available for classifying organisations and to set/change these, you should provide the ID of the appropriate value. The values for these fields are configurable by our users, and so what you send will depend on your account. The options method will return details of all of these configurable values.

{
   "Organisation":{
      "name":"Acme Corp",
      "status_id":12,
      "source_id":14,
      "classification_id":13,
      "rating_id":27,
      "industry_id":15,
      "type_id":20,
   }
}

Response

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

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

/organisations/save_contact

POST requests to /organisations/save_contact will allow you to attach contact-methods ('phone', 'fax' and 'email') to an existing organisation.

 POST /organisations/save_contact?api_token=api_token_here HTTP/1.1
Host: senokian.tactilecrm.com
Content-Type: application/json

{
  "organisation_id": 2,
  "contact": "foo@example.com",
  "type":"E",
  "name":"Alt."
}
organisation_idRequired. The ID of the organisation to attach the contact method to.
contactRequired. The 'value' of the contact method, i.e. the email-address or the phone or fax number
typeRequired. One of "E", "F" or "T", for "Email", "Fax" or "Telephone" respectively
nameA Name for the contact method. If omitted, "Main" will be used.

/organisations/options

GET requests to /organisations/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",
   "organisation_options":{
      "assigned_to":{
         "david":"david",
         "greg":"greg"
         [...]
      },
      "status":{
         "5":"Closed",
         "4":"Developed",
         "2":"Lead",
         "1":"Prospect",
         "3":"Qualified"
      },
      "source":{
         "8":"Telepohone",
         "7":"Website",
         "11":"Newsletters",
         "3":"Word of Mouth"
      },
      "classification":{
         "4":"Large",
         "3":"Medium",
         "1":"Micro",
         "5":"Multi-National",
         "6":"Public Sector",
         "2":"SME"
      },
      "rating":{
         "2":"Fair",
         "3":"Good",
         "1":"Poor"
      },
      "industry":{
         "4":"Consultancy",
         "2":"Design Agency",
         "3":"Software House",
         "5":"Utilities"
         [...]
      },
      "type":{
         "2":"Government Funded",
         "1":"Ltd",
         "3":"PLC"
      },
      "country_code":{
         "AF":"Afghanistan",
         "AL":"Albania",
         "DZ":"Algeria",
        [...]
         "ZM":"Zambia",
         "ZW":"Zimbabwe"
      }
   }
}

assigned_to contains a list of users. country_code contains a hash of country-codes as keys, with the name of the country as the corresponding value. The remaining keys (all shown in the sample) contain the user-configurable values along with their IDs.

/organisations/add_tag/

Adds a tag to an organisations.

Request

/organisations/add_tag/?api_token=api_token_here&id=organisation_id&tag=tag_name

Response

{
	"status":"success", 
	"tag":"Website Contact"
}
idRequired. The ID of the organisation to attach the tag to.
tagRequired. The name of the tag to add to the organisation.