REST API Contacts

Listing contacts

GET /contacts.xml

Returns a paginated list of contacts.


Parameter Type Description
project_id integer/string get contacts from the project with the given id
assigned_to_id integer get contacts from the user with the given id
search string get contacts with the given search string
tags string get contacts with the given tag


GET /contacts.xml 
GET /contacts.xml?project_id=2 
GET /contacts.xml?tags=vip&assigned_to_id=1 
GET /contacts.xml?search=tom 

Paging example: 
GET /contacts.xml?project_id=testproject&page=1
GET /contacts.xml?project_id=testproject&page=2


<contacts type="array" offset="0" limit="20" total_count="5">
  <avatar attachment_id="39"/>
  <first_name>Apple Inc.</first_name>
    <full_address>Calle Valencia, 87-89, Barcelona, 08029, Spain</full_address>
    <street>Calle Valencia, 87-89</street>
  <job_title>Personal computers</job_title>
      Established on April 1, 1976 in Cupertino, California, and incorporated January 3, 1977,[8] the 
      company was previously named Apple Computer, Inc., for its first 30 years, but removed the word
       "Computer" on January 9, 2007,  [9] to reflect the company's ongoing expansion into the consumer
  <author name="Bezrukov Kirill" id="4"/>
  <phones type="array">
    <phone>+1 003 322 43 23</phone>
  <emails type="array">
  <tags>vip, referral, cold call</tags>
  <custom_fields type="array">
    <custom_field name="License" id="1">
    <custom_field name="Purchase date" id="3">

Showing a contact

GET /contacts/[id].xml


  • include: fetch associated data (optional, use comma to fetch multiple associations). Possible values:
    • notes
    • contacts
    • deals
    • tickets


GET /contacts/2.xml
GET /contacts/2.json

GET /contacts/2.xml
GET /contacts/2.xml?include=notes
GET /contacts/2.xml?include=notes,tickets,deals

Creating a contact

POST /contacts.[format]


  • contact - A hash of the contact attributes:
    • project_id
    • first_name
    • company - Company name string
    • phone
    • email
    • website
    • skype_name
    • birthday
    • last_name
    • middle_name
    • background
    • job_title
    • tag_list
    • is_company
    • address_attributes - Address lines data
    • assigned_to_id - ID of the user to assign the contact to (currently no mechanism to assign by name)
    • custom_fields - See Custom fields
    • visibility - ("0" - Project, "1" - Public, "2" - Private)


POST /contacts.xml
<?xml version="1.0"?>
    <street1>12, Street</street1>
  <tag_list>vip,cold call</tag_list>
POST /contacts.json
  "contact": {
    "project_id": 1,
    "first_name": "John",
    "address_attributes": {"street1": "12, Street", "city": "Moscow", "country_code": "RU"},
    "tag_list": "vip,cold call" 

Contact projects

Add contact to project

POST /contacts/:contact_id/projects.xml


  • contact_id - Current contact ID
  • project
    • id - Adding project ID


POST /contacts/123/projects.xml

Remove contact from project

DELETE /contacts/:contact_id/projects/:id.xml


  • contact_id - Current contact ID
  • id - Removing project ID


DELETE /contacts/123/projects/1.xml

Web-form example

<form accept-charset="UTF-8" action="" enctype="multipart/form-data" method="post">
    <input name="key" type="hidden" value="9a13f31770b80767a57d753961acbd3a18eb1370">
    <input name="project_id" type="hidden" value="contacts-plugin">
    <p><label>First name:</label><input name="contact[first_name]" type="text"></p>
    <p><label>Last name:</label><input name="contact[last_name]" type="text"></p>
    <p><label>Company:</label><input name="contact[company]" type="text"></p>
    <p><label>Phone:</label><input name="contact[phone]" type="text"></p>
    <p><label>Email:</label><input name="contact[email]" type="text"></p>
    <p><label>Tags:</label><input name="contact[tag_list]" type="text"></p>

    <input name="contact[custom_fields][][id]" type="hidden" value="1">
    <p><label>License:</label><input name="contact[custom_fields][][value]" type="text"></p>
    <input name="commit" type="submit" value="Save"> 

Curl examples

Update contact

curl -v -H “Accept: application/json” -H "Content-Type: application/json" -X PUT http://localhost:3000/contacts/1 -u admin:admin -d "{\"contact\": {\"first_name\":\"John\",\"last_name\":\"Smith\"}}" 

Create contact

curl -v -H "Content-Type: application/xml" -X POST -d "<contact><first_name>API contact name</first_name><is_company>true</is_company><project_id>support</project_id></contact>" -u admin:admin http://localhost:3000/contacts.xml
Was this article helpful? Yes  No
177 from 206 found this helpful