REST API

Authentication

This is an HTTPS-only API. Authentication will be performed based in the email address of the user and their respective API Key.

Email and API key should be passed via HTTP Basic Authentication. Email address as username and their respective API Key as password.

End Points

All API requests should be made to: https://{domain}.agilecrm.com/dev/

Status Codes

Code Description
200 Request succeeded
201 The request to POST or PUT a record was successful
400 The request was not formatted correctly
401 Invalid API Key
404 Resource not found
405 Invalid method type
415 Unsupported Media type
500 Server error

API Clients

Fields

Contact Fields
FieldName ValueType ReadOnly Mandatory Description
id Long No Yes, If request is to update a contact Unique id generated when contact is created
type String No Taken "PERSON" as default if not specified Sets type of contact "PERSON" or "COMPANY"
tags List No No Unique identifiers added to contact, for easy management of contacts
lead_score Integer No No Score of contact
star_value Short No No Rating of contact (Max value 5)
properties List of JSON objects No first_name and last_name mandatory in JSON properties Contact properties are represented by list of JSON objects, each JSON object should follow the prototype shown {name : <name of the property>, subtype:<work/home..>, value: <value of field>}

Example :

[
    {
        "count": 55,
        "id": 27001,
        "type": "PERSON",
        "created_time": 1349974226,
        "updated_time": 1364483386,
        "star_value": 0,
        "lead_score": 0,
        "tags": [
            "test",
            "Deal Closed"
        ],
        "properties": [
            {
                "type": "SYSTEM",
                "name": "first_name",
                "value": "Jagan"
            },
            {
                "type": "SYSTEM",
                "name": "last_name",
                "value": "Ganti"
            },
            {
                "type": "SYSTEM",
                "name": "company",
                "value": "Invox"
            },
            {
                "type": "SYSTEM",
                "name": "title",
                "value": "Evangelist"
            },
            {
                "type": "SYSTEM",
                "name": "email",
                "subtype": "",
                "value": "jagan@clickdesk.com"
            },
            {
                "type": "CUSTOM",
                "name": "image",
                "value": "https://twimg0-a.akamaihd.net/profile_images/3161039333/9d5d7d180b3d69a682d1d87516700c20_bigger.jpeg"
            }
        ],
        "widget_properties": "{\"Twitter\":\"11458852\"}",
        "domainUser": {
            "id": 314001,
            "domain": "test",
            "email": "chapalamadugu@me.com",
            "is_admin": true,
            "is_account_owner": false,
            "is_disabled": false,
            "name": "angel",
            "password": "PASSWORD",
            "info_json_string": "{\"logged_in_time\":1364879569,\"created_time\":1361958281}",
            "hashedString": "81dc9bdb52d04dc20036dbd8313ed055"
        }
    },
    {
        "id": 34001,
        "type": "PERSON",
        "created_time": 1350110744,
        "updated_time": 1361953347,
        "star_value": 0,
        "lead_score": 0,
        "tags": [
            "Deal Closed"
        ],
        "properties": [
            {
                "type": "SYSTEM",
                "name": "first_name",
                "value": "Manohar"
            },
            {
                "type": "SYSTEM",
                "name": "last_name",
                "value": "Ch"
            },
            {
                "type": "SYSTEM",
                "name": "company",
                "value": "invox"
            },
            {
                "type": "SYSTEM",
                "name": "title",
                "value": "CEO"
            },
            {
                "type": "SYSTEM",
                "name": "email",
                "subtype": "",
                "value": "manohar@invox.com"
            }
        ],
        "domainUser": {
            "id": 40001,
            "domain": "test",
            "email": "manohar@invox.com",
            "is_admin": true,
            "is_account_owner": false,
            "is_disabled": false,
            "name": "Manohar",
            "password": "PASSWORD",
            "info_json_string": "{\"logged_in_time\":1364880154,\"created_time\":1352204584}",
            "hashedString": "a313bc0bbe7f756a55f060928e6826e4"
        }
    }
]

List Contacts

REST Method : GET

URL : https://{domain}.agilecrm.com/dev/api/contacts

Accept : application/xml or application/json

Returns list of contacts in domain, which are ordered by created time

Using curl :

curl https://{domain}.agilecrm.com/dev/api/contacts \
-H "Accept : application/xml" \
-v -u {email}:{apikey}

Example XML response :

<?xml version="1.0" encoding="UTF-8" ?>
<contacts>
  <contact>
	<count>9</count>
	<id>40002</id>
	<type>PERSON</type>
	<created_time>1356589886</created_time>
	<updated_time>1357107323</updated_time>
	<star_value>0</star_value>
	<lead_score>93</lead_score>
	<tags>sales</tags>
	<tags>bruik</tags>
	<tags>walt</tags>
	<tags>los</tags>
	<tags>vo</tags>
	<tags>steady</tags>
	<properties>
		<type>SYSTEM</type>
		<name>first_name</name>
		<value>Los </value>
	</properties>
	<properties>
		<type>SYSTEM</type>
		<name>last_name</name>
		<value>Bruikheilmer</value>
	</properties>
	<properties>
		<type>SYSTEM</type>
		<name>company</name>
		<value>steady.inc</value>
	</properties>
	<properties>
		<type>SYSTEM</type>
		<name>title</name>
		<value>VP Sales</value>
	</properties>
	<properties>
		<type>SYSTEM</type>
		<name>email</name>
		<subtype>work</subtype>
		<value>bruik@walt.inc</value>
	</properties>
	<properties>
		<type>SYSTEM</type>
		<name>address</name>
		<value>{
			"address":"440 N",
			"city":"Wolfe Road",
			"state":"Sunnyvale",
			"zip":"",
			"country":"CA"
		  }
		</value>
	</properties>
	<domainUser>
		<id>106010</id>
		<domain>yaswanth</domain>
		<email>praveen@invox.com</email>
		<is_admin>true</is_admin>
		<is_account_owner>true</is_account_owner>
		<is_disabled>false</is_disabled>
		<name>yaswanth</name>
		<password>PASSWORD</password>
		<info_json_string>{
    		  	  "logged_in_time": 1359434638,
    		  	  "created_time": 1358831084
			}
		</info_json_string>
	</domainUser>
</contact>
<contact>
	<id>41002</id>
	<type>PERSON</type>
	<created_time>1356590542</created_time>
	<updated_time>1359367255</updated_time>
	<star_value>4</star_value>
	<lead_score>92</lead_score>
	<tags>president</tags>
	<tags>john</tags>
	<tags>doe</tags>
	<tags>cruzzetech</tags>
	<properties>
		<type>SYSTEM</type>
		<name>first_name</name>
		<value>John</value>
	</properties>
	<properties>
		<type>SYSTEM</type>
		<name>last_name</name>
		<value>Doe</value>
	</properties>
	<properties>
		<type>SYSTEM</type>
		<name>company</name>
		<value>cruzzetech.com</value>
	</properties>
	<properties>
		<type>SYSTEM</type>
		<name>email</name>
		<value>john@cruzzetech.com</value>
	</properties>
	<properties>
		<type>SYSTEM</type>
		<name>title</name>
		<value>President</value>
	</properties>
	<tags_with_time_json>
		{
			"president":1359365229885,
			"john":1359365229885,
			"doe":1359365229885,
			"cruzzetech":1359365229885
		}
		</tags_with_time_json>
	<domainUser>
		<id>106010</id>
		<domain>yaswanth</domain>
		<email>praveen@invox.com</email>
		<is_admin>true</is_admin>
		<is_account_owner>true</is_account_owner>
		<is_disabled>false</is_disabled>
		<name>yaswanth</name>
		<password>PASSWORD</password>
		<info_json_string>{
				"logged_in_time":1359434638,
				"created_time":1358831084
		}
		</info_json_string>
	</domainUser>
  </contact>
</contacts>
	

Using curl :

curl https://{domain}.agilecrm.com/dev/api/contacts \
-H "Accept : application/json" \
-v -u {email}:{apikey}

Example JSON response :

[
    {
        "count": "9",
        "id": "40002",
        "type": "PERSON",
        "created_time": "1356589886",
        "updated_time": "1357107323",
        "star_value": "0",
        "lead_score": "93",
        "tags": [
            "sales",
            "bruik",
            "walt",
            "los",
            "vo",
            "steady"
        ],
        "properties": [
            {
                "type": "SYSTEM",
                "name": "first_name",
                "value": "Los "
            },
            {
                "type": "SYSTEM",
                "name": "last_name",
                "value": "Bruikheilmer"
            },
            {
                "type": "SYSTEM",
                "name": "company",
                "value": "steady.inc"
            },
            {
                "type": "SYSTEM",
                "name": "title",
                "value": "VP Sales"
            },
            {
                "type": "SYSTEM",
                "name": "email",
                "subtype": "work",
                "value": "bruik@walt.inc"
            },
            {
                "type": "SYSTEM",
                "name": "address",
                "value": "{\"address\":\"\",\"city\":\"\",\"state\":\"\",\"zip\":\"\",\"country\":\"\"}"
            }
        ],
        "domainUser": {
            "id": "106010",
            "domain": "yaswanth",
            "email": "praveen@invox.com",
            "is_admin": "true",
            "is_account_owner": "true",
            "is_disabled": "false",
            "name": "yaswanth",
            "password": "PASSWORD",
            "info_json_string": "{\"logged_in_time\":1359434638,\"created_time\":1358831084}"
        }
    },
    {
        "id": "41002",
        "type": "PERSON",
        "created_time": "1356590542",
        "updated_time": "1359367255",
        "star_value": "4",
        "lead_score": "92",
        "tags": [
            "president",
            "john",
            "doe",
            "cruzzetech"
        ],
        "properties": [
            {
                "type": "SYSTEM",
                "name": "first_name",
                "value": "John"
            },
            {
                "type": "SYSTEM",
                "name": "last_name",
                "value": "Doe"
            },
            {
                "type": "SYSTEM",
                "name": "company",
                "value": "cruzzetech.com"
            },
            {
                "type": "SYSTEM",
                "name": "email",
                "value": "john@cruzzetech.com"
            },
            {
                "type": "SYSTEM",
                "name": "title",
                "value": "President"
            }
        ],
        "tags_with_time_json": "{\"president\":1359365229885,\"john\":1359365229885,\"doe\":1359365229885,\"cruzzetech\":1359365229885}",
        "domainUser": {
            "id": "106010",
            "domain": "yaswanth",
            "email": "praveen@invox.com",
            "is_admin": "true",
            "is_account_owner": "true",
            "is_disabled": "false",
            "name": "yaswanth",
            "password": "PASSWORD",
            "info_json_string": "{\"logged_in_time\":1359434638,\"created_time\":1358831084}"
        }
    }
]

Get contact by id

REST Method : GET

URL : https://{domain}.agilecrm.com/dev/api/contacts/{id}

Accept : application/xml or application/json

Returns contact object which is associated given id

Using curl :

curl https://{domain}.agilecrm.com/dev/api/contacts/{id} \
-H "Accept :application/xml" \
-v -u {email}:{apikey}

Example Response :

Returns created contact object with all parameters in it.

Create contact

REST Method : POST

URL : https://{domain}.agilecrm.com/dev/api/contacts

Accept : application/xml or application/json

Accepts contact JSON as post data along with the credentials of domain User (User name and API Key).

Using curl :

curl https://{domain}.agilecrm.com/dev/api/contacts \
-H "Content-Type: application/json" \
-d '{        
       "tags": [
	            "sales",
	            "bruik",
	            "walt",
	            "los",
	            "vo",
	            "steady"
       		],
        "properties": [
            {
                "type": "SYSTEM",
                "name": "first_name",
                "value": "Los "
            },
            {
                "type": "SYSTEM",
                "name": "last_name",
                "value": "Bruikheilmer"
            }
         ]
       }'\
-v -u test@example.com:4uet78u6atfn38m9dounnq9g4u -X POST 

Example Response :

Returns created contact object with all parameters in it.

Update contact

REST Method : PUT

URL : https://{domain}.agilecrm.com/dev/api/contacts

Accept : application/xml or application/json

Accepts contact object with valid id parameter in it, where 'id' refers the contact to be updated.

Using curl :

curl https://{domain}.agilecrm.com/dev/api/contacts \
 -H "Content-Type: application/json" \
 -d '{        
 "tags": [
       "sales",
       "bruik",
       "walt",
       "los",
       "vo",
       "steady"
 		],
  "properties": [
      {
          "type": "SYSTEM",
          "name": "first_name",
          "value": "Los "
      },
      {
          "type": "SYSTEM",
          "name": "last_name",
          "value": "Bruikheilmer"
      }
   ]
  }' \
 -v -u test@example.com:4uet78u6atfn38m9dounnq9g4u -X PUT

Example Response :

Returns updated contact object, it includes all the parameters.

Add Tags to contacts

REST Method : POST

URL : https://{domain}.agilecrm.com/dev/api/contacts/bulk/tags

Accept : application/xml or application/json

Accepts tags array ex : ["Paid in December" "Not paid in March" "Paid in April"], and accepts list of contact ids to update tags of specified contacts.

Using curl :

curl https://{domain}.agilecrm.com/dev/api/contacts/bulk/tags \
-d '{"tags":["Paid in December" "Not paid in March" "paid in April"], "contact_ids":[12, 23, 45]}' \
-v -u {email}:{apikey} -X POST

Example Response :

Status: 200 OK

Delete single contact

REST Method : DELETE

URL : https://{domain}.agilecrm.com/dev/api/contacts/{id}

Accept : application/xml or application/json

Deletes contact based on the id of the contact, which is sent in request url path.

Using curl :

curl https://{domain}.agilecrm.com/dev/api/contacts/{id}  \
-v -u {email}:{apikey} -X DELETE

Example Response :

Status: 204

Contacts bulk delete

REST Method : POST

URL : https://{domain}.agilecrm.com/dev/api/contacts/bulk

Accept : application/xml or application/json

Deletes list of contacts based on list of contact ids sent in request.

Using curl :

curl https://{domain}.agilecrm.com/dev/api/contacts/bulk \
    -d '{"model_ids" : [12, 23, 45]}' \
    -v -u {email}:{apikey}  -X POST

Example Response :

Status: 204

Fields

Deal Fields
FieldName ValueType ReadOnly Mandatory Description
id Integer No Yes, if request is to update an existing deal Unique id is assigned to every deal, when it is created
name String No Yes Name of the deal
subject String No Yes Subject of the note
description String No No Brief description about deal.
expected_value Long No Yes Estimated value of a deal.
milestone String No Yes Milestone of deal (won, progress, lost..)
probability Integer No Should be ranging between 0-100
close_date Long No Yes Close date of deal.
created_time Long Yes No, generated automatically on deal creation Created time of the deal. Returns time in seconds
owner_id String No, write access is provided to set owner of deal Yes owner_id represents id of domain user
prefs JSON string
contacts List of contact id. ex: ["122", 145,201] Write access to relate contacts, while returning contact jsons respective to ids set No Relates list of contacts to deal

Deal JSON Example :

{
    "id": "822",
    "name": "Game development",
    "description": "Visual 3D based Online Game.",
    "expected_value": "50000",
    "milestone": "progress",
    "probability ": "70",
    "close_date": "1349980200",
    "created_time": "1356325843",
    "entity_type": "deal",
    "Prefs": {
        "id": "984",
        "template": "blue",
        "currency": "USD",
        "signature": "- Powered by AgileCRM",
        "task_reminder": "true"
    }
}

List deals

REST Method : GET

URL : https://{domain}.agilecrm.comdev/api/opportunity

Accept : application/xml or application/json

Returns list of all "Deal" JSON in domain, which are ordered on created time

Using curl :

curl https://{domain}.agilecrm.com/dev/api/opportunity \
       -H  "Accept : application/json" \
       -v -u {email}:{API Key}

Example Response :

[
    {
        "id": 981,
        "name": "premium subscriptions",
        "contacts": [
            {
                "id": 2363,
                "type": "PERSON",
                "created_time": 1359033520,
                "updated_time": 1359033533,
                "star_value": 0,
                "lead_score": 0,
                "tags": [],
                "properties": [
                    {
                        "type": "SYSTEM",
                        "name": "first_name",
                        "value": "John"
                    },
                    {
                        "type": "SYSTEM",
                        "name": "last_name",
                        "value": "Olsen"
                    },
                    {
                        "type": "SYSTEM",
                        "name": "email",
                        "value": "john@example.com.com"
                    }
                ],
                "domainUser": {
                    "id": 516,
                    "email": "test@example.com",
                    "is_admin": true,
                    "is_account_owner": false,
                    "is_disabled": false,
                    "name": "ram",
                    "password": "PASSWORD",
                    "info_json_string": "{\"logged_in_time\":1360503513,\"created_time\":1353507148}"
                }
            }
        ],
        "description": "Deal premium plan subscription",
        "expected_value": 300,
        "milestone": "Open",
        "probability": 46,
        "close_date": 1371753000,
        "created_time": 1360503631,
        "entity_type": "deal",
        "owner": {
            "id": 516,
            "email": "test@example.com",
            "is_admin": true,
            "is_account_owner": false,
            "is_disabled": false,
            "name": "Test",
            "password": "PASSWORD",
            "info_json_string": "{\"logged_in_time\":1360503513,\"created_time\":1353507148}"
        },
        "prefs": {
            "id": 984,
            "pic": "",
            "template": "blue",
            "width": "",
            "currency": "USD",
            "signature": "- Powered by AgileCRM",
            "task_reminder": true,
            "currentDomainUserName": "?"
        },
        "pic": ""
    },
    {
        "id": 981,
        "name": "premium subscriptions",
        "contacts": []
    }
]

Get deal by its id

REST Method : GET

URL : https://{domain}.agilecrm.com/dev/api/opportunity/{id}

Accept : application/xml or application/json

Fetches deal by its id.

Using curl :

curl https://{domain}.agilecrm.com/dev/api/opportunity/981 \
      -H  "Accept : application/json" \
      -v -u {email}:{API Key}

Example Response :

{
    "id": 981,
    "name": "500 premium subscriptions",
    "contacts": [
        {
            "id": 2363,
            "type": "PERSON",
            "created_time": 1359033520,
            "updated_time": 1359033533,
            "star_value": 0,
            "lead_score": 0,
            "tags": [
                
            ],
            "properties": [
                {
                    "type": "SYSTEM",
                    "name": "first_name",
                    "value": "John"
                },
                {
                    "type": "SYSTEM",
                    "name": "last_name",
                    "value": "Olsen"
                },
                {
                    "type": "SYSTEM",
                    "name": "email",
                    "value": "john@example.com"
                },
                
            ],
            "domainUser": {
                "id": 516,
                "email": "test@example.com",
                "is_admin": true,
                "is_account_owner": false,
                "is_disabled": false,
                "name": "ram",
                "password": "PASSWORD",
                "info_json_string": "{\"logged_in_time\":1360503513,\"created_time\":1353507148}"
            }
        }
    ],
    "description": "Deal premium plan subscription",
    "expected_value": 300,
    "milestone": "Open",
    "probability": 46,
    "close_date": 1371753000,
    "created_time": 1360503631,
    "entity_type": "deal",
    "owner": {
        "id": 516,
        "email": "test@example.com",
        "is_admin": true,
        "is_account_owner": false,
        "is_disabled": false,
        "name": "ram",
        "password": "PASSWORD",
        "info_json_string": "{\"logged_in_time\":1360503513,\"created_time\":1353507148}"
    },
    "prefs": {
        "id": 984,
        "pic": "",
        "template": "blue",
        "width": "",
        "currency": "USD",
        "signature": "- Powered by AgileCRM",
        "task_reminder": true,
        "currentDomainUserName": "?"
    },
    "pic": ""
}

Create Deal

REST Method : POST

URL : https://{domain}.agilecrm.com/dev/api/opportunity

Accept : application/xml or application/json

Accepts deal JSON as data in post request to the url specified above, which creates new deal and returns the deal JSON with id field generated when new deal is created. If post data includes valid deal id, respective deal is updated with the data sent in request.

Using curl :

curl https://{domain}.agilecrm.com/dev/api/opportunity \
-H "Content-Type: application/json" \
-d '{"name" : "deal",  "contacts" : ["2358", "2356"] , "owner_id" : "516"}'\
-v -u test@example.com:4uet78u6atfn38m9dounnq9g4u -X POST 

Example Response :

{
    id: 882,
    created_time: 1356325843...
}

Update Deal

REST Method : PUT

URL : https://{domain}.agilecrm.com/dev/api/opportunity

Accept : application/xml or application/json

Accepts Deal JSON. Id parameter of the deal should be specified, it indicates which deal to be updated with the modified data sent.

Using curl :

curl https://{domain}.agilecrm.com/dev/api/opportunity \
       -H "Content-Type: application/json" \
       -d "{\"name\" : \"deal\",  \"contacts\" : [\"2358\",\"2356\"] , \"owner_id\" : \"516\"}" \
       -v -u test@example.com:4uet78u6atfn38m9dounnq9g4u -X PUT

Example Response :

Status: 200OK{
    name: dealname...
}

Delete Deal

REST Method : DELETE

URL : https://{domain}.agilecrm.com/dev/api/opportunity/{id}

Accept : application/xml or application/json

Deletes the deal based the id specified in the url.

Using curl :

curl https://{domain}.agilecrm.com/dev/api/opportunity/{id} \
       -H "Content-Type: application/json" \
       -v -u test@example.com:4uet78u6atfn38m9dounnq9g4u -X DELETE

Example Response :

Status: 200 OK

Bulk Delete

REST Method : POST

URL : https://{domain}.agilecrm.com/dev/api/opportunity/bulk

Accept : application/xml or application/json

Accepts list of deal ids in post request, and deletes all deals based on list of ids sent.

Using curl :

curl https://{domain}.agilecrm.com/dev/api/opportunity/bulk \
       -H "Content-Type: application/x-www-form-urlencoded" \
       -d '{"model_ids" : ["123", "234", "235"]}'  \
       -v -u {email}:{API Key} -X POST

Example Response :

Status: 200 OK

Fields

Note Fields
FieldName ValueType ReadOnly Mandatory Description
id Long No No Unique id generated when note is created
created_time Long Yes No Creation time of note
subject String No Yes Subject of the note
description String No Yes Description of note
contacts Contact (JSON) No No Related contact to note.

Create note and relate to contacts

REST Method : POST

URL : https://{domain}.agilecrm.com/dev/api/notes

Accept : application/xml or application/json

Creates a note and relates it to contacts. Contact ids should be specified in "contacts" to which notes are related.

Using curl :

curl https://{domain}.agilecrm.com/dev/api/notes/ \
    -H "Content-Type : application/json" \
    -H "Accept : application/json"
    -d '{"subject" : " Note subject" , "description" : "Note description", "contacts" : ["721001", "722001"] }' \
    -v -u {email} : {APi Key} -X POST

Example Response :

{
    "id": 80001,
    "created_time": 1360561958,
    "subject": "Notesubject",
    "description": "Notedescription",
    "contacts": [
        "721002"
    ],
    "entity_type": "note"
}

Get notes related to specific contact

REST Method : GET /dev/api/contacts/{contact_id}/notes

URL : https://{domain}.agilecrm.com/dev/api/contacts/{contact_id}/notes

Accept : application/xml or application/json

Returns list of note related to the contact.

Using curl :

curl https://{domain}.agilecrm.com/dev/api/contacts/710002/notes \
    -H "Accept : application/json" \
    -v -u {email} : {API Key}

Example Response :

[
    {
        "id": 79001,
        "created_time": 1360561958,
        "subject": "Notesubject1",
        "description": "Notedescription1",
        "contacts": [
            "721002"
        ],
        "entity_type": "note"
    },
    {
        "id": 80001"created_time": 1360561722,
        "subject": "Notesubject2",
        "description": "Notedescription2",
        "contacts": [
            "721002"
        ],
        "entity_type": "note"
    }
]

Delete a note from contact

REST Method : DELETE

URL : https://{domain}.agilecrm.com/dev/api/contacts/{contact_id}/notes/{note_id}

Accept : application/xml or application/json

Deletes a note from specific contact. Contact id and note id should be specified in the URL, so note with a given id is deleted from contact based on contact id in the URL.

Using curl :

curl https://{domain}.agilecrm.com/dev/api/contacts/{contact_id}/notes/{note_id} \
    -H "Accept : application/json" \
    -v -u {email} : {API Key} -X DELETE

Example Response :

status: 204