Sign Up and Get Started Today

People

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

Access to People 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 Person, or the Person's Organisation.

/people

Sending GET requests to https://sample.tactilecrm.com/people will give you access to a paginated array of People objects ordered alphabetically by First Name, Surname.

Request

/people/?api_token=your_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

limit Optional. Number (1 to 100 inclusive). Specifies the number of results to return per page. Default is 30.
page Optional. Number. Specifies which page of results to return.

Filtering

firstname, surname, and name are case-insensitive, and accept asterisks (*) as wildcards. e.g. firstname=dav* will match both 'Dave' and 'david'.

firstname Optional. String. Restrict results to only those which have a matching First Name.
surname Optional. String. Restrict results to only those which have a matching First Name.
name Optional. String. Restrict results to only those which have a matching First Name.
organisation_id Optional. Number. Return only the People under the specified Organisation.
created_before
created_after
updated_before
updated_after
Optional. Date/timestamp. 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.

Response

{
   "status":"success",
   "people":[
      {
         "name":"Arthur Jones",
         "description":"The big boss",
         [...]
         "reports_to":null
      },
      {
         "name":"David Smith",
         "description":"A pretty cool guy",
         [...]
         "reports_to_id":122512,
         "reports_to":"Arthur Jones"
      }
   ],
   "cur_page":1,
   "num_pages":4,
   "per_page":2,
   "total":8
}
status Will be 'success' or 'error'.
messages If status='error', then messages will contain an array of error messages (as strings).
people If status='success', then this will be an array of People (as objects). If there are no People 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 people array.
total An integer that shows the total number of People in the list. If no constraints are supplied, then this is the total number of People in your account (that you have permission to see).

/people/mine

Uses the same request and response structure as plain listing, but only returns People assigned to you.

Request

/people/mine/?api_token=your_token_here&key=value

See /people for a full list of accepted query parameters.

/people/view

Retrieve a single Person's data. For People with multiple contact methods (i.e. more than one phone, mobile, or email), only the first method for each type is returned.

Request

/people/view/122514?api_token=your_token_here

Response

{
   "status":"success",
   "person":{
      "name":"David Smith",
      "description":"A pretty cool guy",
      "title":"Mr",
      "firstname":"David",
      "surname":"Smith",
      "suffix":"Jr.",
      "jobtitle":"Captain",
      "language_code":"English",
      "id":122514,
      "can_call":true,
      "can_email":false,
      "owner":"george",
      "assigned_to":"george",
      "created":"2009-03-25T09:40:20+00:00",
      "lastupdated":"2009-03-25T09:40:20+00:00",
      "dob":"1983-07-19",
      "street1":"Business House",
      "street2":"Business Centre",
      "street3":"12 Business Road",
      "town":"BusyTown",
      "county":"Countyshire",
      "postcode":"AB1 2CD",
      "country":"United Kingdom",
      "organisation_id":99606,
      "organisation":"The Business Guys",
      "reports_to":122512
   }
}
status Will be 'success' or 'error'.
messages If status='error', then messages will contain an array of error messages (as strings).
person If status='success', then this will be a single Person (as an object).

/people/contact_methods

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

Request

/person/contact_methods/?api_token=your_token_here&id=1234
id Number. The ID of the Person you wish to get the contact methods for.

Response

{
   "status":"success",
   "contact_methods":[
      {
         "contact":"info@example.com",
         "type":"E",
         "name":"Main",
         "id":3,
         "person_id":1234
      },
      {
         "contact":"0789123456",
         "type":"M",
         "name":"Main",
         "id":4,
         "person_id":1234
      },
      {
         "contact":"02476 555 400",
         "type":"T",
         "name":"Main",
         "id":1,
         "person_id":1234
      }
   ]
}
status Will be 'success' or 'error'.
messages If status='error', then messages will contain an array of error messages (as strings).
contact_methods If 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', 'M', or 'E' (Telephone, Mobile and Email respectively).
name will be the user-entered name for the contact method.

/people/timeline

GET requests to /people/timeline with an id parameterwill return all of the Notes and Emails associated with the Person.

Request

/person/timeline/?api_token=your_token_here&id=122514
id Number. The ID of the Person you wish to get the timeline for.

Response

{
   "status":"success",
   "timeline":[
      {
         "note":{
            "title":"Regarding Dinner",
            "note":"Dave doesn't like prawns",
            "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":99606,
            "organisation":"The Business Guys",
            "person_id":122514,
            "person":"David Smith"
         }
      },
      {
         "email":{
            "subject":"Re: New Work",
            "body":"Hi David, Please ring us if you need any more information, the office is open all day. George",
            "email_from":"george.step@tactilecrm.com",
            "email_to":"dsmith@example.com",
            "person":"David Smith",
            "opportunity":null,
            "id":3985,
            "person_id":122514,
            "opportunity_id":null,
            "owner":"george",
            "received":"2009-01-13T15:56:00+00:00",
            "created":"2009-01-13T16:00:15+00:00",
            "person_id":122514
         }
      }
   ]
}
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).

/people/save

POST requests to /people/save with the body of the HTTP request containing correctly formatted JSON will save a new Person, or edit an existing one if a valid ID is supplied. The Content-type of the request should be application/json.

Request

POST /people/save/?api_token=your_token_here HTTP/1.1
Host: sample.tactilecrm.com
User-agent: Zend_Http_client (Tactile_Api::v1.0.0)
Content-type: application/json

{
   "Person":{
      "id":null,
      "title":"Mr.",
      "firstname":"Alfred",
      "surname":"Brown",
      "suffix":"Jr.",
      "description":"Son of Alfred Brown Sr.",
      "jobtitle":"CTO",
      "dob":"1983-07-17",
      "language_code":"EN",
      "can_call":true,
      "can_email":false,
      "organisation_id":2,
      "reports_to_id":122745,
	  "assigned_to":george,
      "street1":"Line 1",
      "street2":"Line 2",
      "street3":"Line 3",
      "town":"Town",
      "county":"County",
      "postcode":"AB1 2CD",
      "country_code":"GB"
   }
}
id Provide the ID of an existing Person to edit their details. Number.
firstname
surname
Required. Strings. Concatenated to create a Person's full name.
title
suffix
jobtitle
description
Optional. Strings.
dob Optional. Datestamp (YYYY-MM-DD). Person's Date of Birth.
lang Required. String. ISO 639-1 two-letter language code. See /people/options for details on obtaining a full list of valid values.
can_call
can_email
Optional. Booleans. Default to true.
organisation_id Optional. Number. ID of an Organisation to link this Person to.
reports_to_id Optional. Number. ID of a Person in the same Organisation to link this Person to.
assigned_to Optional. String. Must be a full username in the form of user//site_address. See /people/options for details on obtaining a full list of valid values.
phone
mobile
email
Optional. Objects.
id is the ID of an existing contact method, if editing.
contact is the string value of the number/address itself.
See /people/contact_methods for details on obtaining contact method IDs.

Response

{
   "status":"success",
   "id":25
}
status Will be 'success' or 'error'.
messages If status='error', then messages will contain an array of error messages (as strings).
id If status='success', then id will contain the id of the Person saved.

/people/options

Returns a series of valid values for various Person fields.

Request

/person/options/?api_token=your_token_here

Response

{
   "status":"success",
   "person_options":{
      "assigned":{
         "bob//sample":"bob",
         "dave//sample":"dave",
         "george//sample":"george",
         "paul//sample":"paul"
      },
      "language":{
         "AB":"Abkhazian",
         "AA":"Afar",
         "AF":"Afrikaans",
         "SQ":"Albanian",
         [...]
         "XH":"Xhosa",
         "JI":"Yiddish",
         "YO":"Yoruba",
         "ZU":"Zulu"
      }
   }
}
status Will be 'success' or 'error'.
messages If status='error', then messages will contain an array of error messages (as strings).
person_options If status='success', then person_options will contain:
assigned – Users suitable for the assigned_to field.
language – Languages suitable for the lang field.

/people/save_contact

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

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

{
  "person_id": 3,
  "contact": "0181 811 8181",
  "type":"T",
  "name":"Home Number"
}
person_idRequired. The ID of the person to attach the contact method to.
contactRequired. The 'value' of the contact method, i.e. the email-address or the phone or mobile number
typeRequired. One of "E", "M" or "T", for "Email", "Mobile" or "Telephone" respectively
nameA Name for the contact method. If omitted, "Main" will be used.

/people/add_tag/

Adds a tag to a person.

Request

/people/add_tag/?api_token=api_token_here&id=person_id&tag=tag_name

Response

{
	"status":"success", 
	"tag":"Lead"
}
idRequired. The ID of the person to attach the tag to.
tagRequired. The name of the tag to add to the person