REST API Contacts

Listing contacts

GET /contacts.xml

Returns a paginated list of contacts.

Parameters:

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

Examples:

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

Response:

<contacts type="array" offset="0" limit="20" total_count="5">
<contact>
  <id>11</id>
  <avatar attachment_id="39"/>
  <is_company>true</is_company>
  <first_name>Apple Inc.</first_name>
  <last_name/>
  <middle_name/>
  <company/>
  <address>
    <full_address>Calle Valencia, 87-89, Barcelona, 08029, Spain</full_address>
    <street>Calle Valencia, 87-89</street>
    <city>Barcelona</city>
    <region/>
    <country>Spain</country>
    <country_code>ES</country_code>
    <postcode>08029</postcode>
  </address>
  <website>http://www.apple.com</website>
  <skype_name/>
  <birthday/>
  <job_title>Personal computers</job_title>
  <background>
      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
  </background>
  <author name="Bezrukov Kirill" id="4"/>
  <phones type="array">
    <phone>+1 003 322 43 23</phone>
  </phones>
  <emails type="array">
    <email>info@apple.com</email>
  </emails>
  <tags>vip, referral, cold call</tags>
  <custom_fields type="array">
    <custom_field name="License" id="1">
       <value/>
    </custom_field>
    <custom_field name="Purchase date" id="3">
      <value/>
    </custom_field>
  </custom_fields>
  <created_on>2011-09-07T10:13:18+04:00</created_on>
  <updated_on>2011-09-07T10:30:13+04:00</updated_on>
  </contact>
  <contact>
    ...
  </contact>
</contacts>

Showing a contact

GET /contacts/[id].xml

Parameters:

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

Examples:

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]

Parameters:

• 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)

Examples:

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

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

Parameters:

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

Examples:

POST /contacts/123/projects.xml
<project>
  <id>support</id>
</project>

Remove contact from project

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

Parameters:

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

Examples:

DELETE /contacts/123/projects/1.xml

Web-form example

<form accept-charset="UTF-8" action="http://demo.redminecrm.com/contacts.json" 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"> 
</form>

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