karmaCRM Api Docs

Authentication

Sign in with api token

Signs in to karma using api token

Definition

You can authenticate to the karmaCRM api with your user's API token. All API requests must be made over HTTPS. Calls made over plain HTTP will fail. You must authenticate for all requests. api_token is a required parameter for all API requests. Find your api_key by going to "Settings >> My Settings >> Current Organzation >> api_key"

Sign in with email/password

Signs in to karma using email and password

Definition

POST https://app.karmacrm.com/accounts/sign_in

Example Request

curl -H 'Content-Type: application/json' -H 'Accept: application/json' \
-X POST https://app.karmacrm.com/accounts/sign_in \
-d '{"account":{"email":"test@example.com","password":"test"}}' -c cookie

Example Response

A user record

Contacts

Arguments
id: integer
first_name: string
last_name: string
position: string - currently "title" in karma
background: string
Used to house any detailed information about how you met the contact
lead_process_id: integer - maps to contact_stage_id
lead_status_id: integer - maps to contact_status_id
referral_source_id: integer
department: string
avatar: string
The avatar file
industry_id: integer
user_id: integer
tag_list: string
List of comma-separated tags
phone_numbers: array
List of phone numbers
emails: array
List of email addresses
websites: array
List of websites
addresses: array
List of addresses
social_accounts: array
List of social accounts
field_values: array
List of custom fields
permissions: array
List of permissions
private: boolean
set to true if permissions are specified
Returns

A contact record

Creating a New Contact

Creates a new contact object.

Arguments
first_name: optional
last_name: optional
position: optional - currently "title" in karma
lead_process_id: optional - maps to contact_stage_id
lead_status_id: optional - maps to contact_status_id
background: optional
Used to house any detailed information about how you met the contact
referral_source_id: optional
phone_numbers: optional
List of phone numbers
emails: optional
List of email addresses
department: optional
avatar: optional
The avatar file
industry_id: optional
tag_list: optional
List of comma-separated tags
websites: optional
List of websites
addresses: optional
List of addresses
social_accounts: optional
List of social accounts
field_values: optional
List of custom fields
permissions: optional
List of permissions
private: optional
set to true if permissions are specified
user_id: optional
Returns

Returns a contact object if the call succeeded.

Definition

POST https://app.karmacrm.com/api/v2/contacts.json

Example Request

curl -H "Accept: application/json" \
-H "Content-type: application/json" \
-X POST https://app.karmacrm.com/api/v2/contacts.json?\
api_token=FDGz79n8D2Cz2bjqB7BB \
-d '{
   "contact":{
      "first_name":"John",
      "last_name":"Smith",
      "position":"developer",
      "background":"Good developer with 3+ years of experience",
      "lead_process_id":32637,
      "lead_status_id":79223,
      "referral_source_id":42264,
      "department":"Development",
      "industry_id":4739,
      "company":{
         "id":975797,
         "name":"Microsoft"
      },
      "tag_list":"development, usa",
      "addresses":[
         {
            "street":"South St",
            "city":"Chicago",
            "state":"Illinois",
            "country":"USA",
            "postal_code":"60667",
            "address_type":2
         }
      ],
      "phone_numbers":[
         {
            "number":"+7 902 4321 2123",
            "phone_number_type_id":2
         }
      ],
      "emails":[
         {
            "email":"john.smith@example.com",
            "secondary_email_type_id":2
         }
      ],
      "social_accounts":[
         {
            "name":"john_smith",
            "social_account_type_id":1
         }
      ],
      "websites":[
         {
            "url":"example.com",
            "secondary_website_type_id":1
         }
      ],
      "field_values":[
         {
            "field_id":"102360",
            "field_type_id":5,
            "value":"Red"
         },
         {
            "field_id":"102363",
            "field_parent_id":"102361",
            "field_type_id":2,
            "value":"102363"
         }
      ],
      "private":true,
      "permissions":[
         {
            "accessor_id":12793,
            "accessor_type":"User",
            "permission":"1"
         }
      ]
   }
}'

Example Response

{
   "id":8733,
   "first_name":"John",
   "last_name":"Smith",
   "background":"Good developer with 3+ years of experience",
   "position":"developer",
   "avatar_url":"/assets/person_thumb.png",
   "private_notes":null,
   "department":"Development",
   "cached_tag_list":null,
   "organization_id":1,
   "group_id":null,
   "lead_status_id":79223,
   "lead_process_id":32637,
   "referral_source_id":42264,
   "user_id":1,
   "created_by_id":1,
   "created_at":"2013-07-12T08:36:48Z",
   "updated_at":"2013-07-12T08:36:48Z",
   "note_last_added_at":null,
   "note_last_added_id":null,
   "industry_id":4739,
   "private":true,
   "permission":1,
   "company":{
      "id":3203,
      "name":"Microsoft"
   },
   "emails":[
      {
         "id":8741,
         "email":"john.smith@example.com",
         "secondary_email_type_id":2
      }
   ],
   "websites":[
      {
         "id":5,
         "url":"example.com",
         "secondary_website_type_id":1
      }
   ],
   "addresses":[
      {
         "id":6,
         "street":"South St",
         "street_2":null,
         "city":"Chicago",
         "state":"Illinois",
         "country":"US",
         "postal_code":"60667",
         "address_type":2
      }
   ],
   "social_accounts":[
      {
         "id":5,
         "name":"john_smith",
         "social_account_type_id":1
      }
   ],
   "field_values":[
      {
         "id":10,
         "value":"Red",
         "field_type_id":5,
         "field_parent_id":null,
         "field_id":102360
      },
      {
         "id":11,
         "value":"102363",
         "field_type_id":2,
         "field_parent_id":102361,
         "field_id":102363
      }
   ],
   "permissions":[
         "id": 1,
         "accessor_id":12793,
         "accessor_type":"User",
         "permission":"1"
   ]
}

Retrieving a Contact

Retrieves the details of an existing contact. You need only supply the unique contact identifier that was returned upon contact creation.

Returns

Returns a contact object if a valid identifier was provided.

Definition

GET https://app.karmacrm.com/api/v2/contacts/{CONTACT_ID}.json

Example Request

curl -G https://app.karmacrm.com/api/v2/contacts/813135.json \
-d api_token=FDGz79n8D2Cz2bjqB7BB

Example Response

{
   "id":8733,
   "first_name":"John",
   "last_name":"Smith",
   "background":"Good developer with 3+ years of experience",
   "position":"developer",
   "avatar_url":"/assets/person_thumb.png",
   "private_notes":null,
   "department":"Development",
   "cached_tag_list":null,
   "organization_id":1,
   "group_id":null,
   "lead_status_id":79223,
   "lead_process_id":32637,
   "referral_source_id":42264,
   "user_id":1,
   "created_by_id":1,
   "created_at":"2013-07-12T08:36:48Z",
   "updated_at":"2013-07-12T08:36:48Z",
   "note_last_added_at":null,
   "note_last_added_id":null,
   "industry_id":4739,
   "private":true,
   "permission":1,
   "company":{
      "id":3203,
      "name":"Microsoft"
   },
   "emails":[
      {
         "id":8741,
         "email":"john.smith@example.com",
         "secondary_email_type_id":2
      }
   ],
   "websites":[
      {
         "id":5,
         "url":"example.com",
         "secondary_website_type_id":1
      }
   ],
   "addresses":[
      {
         "id":6,
         "street":"South St",
         "street_2":null,
         "city":"Chicago",
         "state":"Illinois",
         "country":"US",
         "postal_code":"60667",
         "address_type":2
      }
   ],
   "social_accounts":[
      {
         "id":5,
         "name":"john_smith",
         "social_account_type_id":1
      }
   ],
   "field_values":[
      {
         "id":10,
         "value":"Red",
         "field_type_id":5,
         "field_parent_id":null,
         "field_id":102360
      },
      {
         "id":11,
         "value":"102363",
         "field_type_id":2,
         "field_parent_id":102361,
         "field_id":102363
      }
   ],
   "permissions":[
         "id": 1,
         "accessor_id":12793,
         "accessor_type":"User",
         "permission":"1"
   ]
}

Updating a Contact

Updates a Contact

Arguments
first_name: optional
last_name: optional
position: optional - currently "title" in karma
lead_process_id: optional - maps to contact_stage_id
lead_status_id: optional - maps to contact_status_id
background: optional
Used to house any detailed information about how you met the contact
referral_source_id: optional
phone_numbers: optional
List of phone numbers
emails: optional
List of email addresses
department: optional
avatar: optional
The avatar file
industry_id: optional
tag_list: optional
List of comma-separated tags
websites: optional
List of websites
addresses: optional
List of addresses
social_accounts: optional
List of social accounts
field_values: optional
List of custom fields
permissions: optional
List of permissions
private: optional
set to true if permissions are specified
user_id: optional
Returns

Returns a contact object if the call succeeded.

Definition

PUT https://app.karmacrm.com/api/v2/contacts/{CONTACT_ID}.json

Example Request

curl -H "Accept: application/json" \
-H "Content-type: application/json" \
-X PUT https://app.karmacrm.com/api/v2/contacts/813135.json?\
api_token=FDGz79n8D2Cz2bjqB7BB \
-d '{
   "contact":{
      "first_name":"Bob",
      "last_name":"Smith",
      "position":"developer",
      "background":"Good developer with 3+ years of experience",
      "lead_process_id":32637,
      "lead_status_id":79223,
      "referral_source_id":42264,
      "department":"Development",
      "industry_id":4739,
      "company":{
         "id":975797,
         "name":"Microsoft"
      },
      "tag_list":"development, usa",
      "addresses":[
         {
            "street":"South St",
            "city":"Chicago",
            "state":"Illinois",
            "country":"USA",
            "postal_code":"60667",
            "address_type":2
         }
      ],
      "phone_numbers":[
         {
            "id": 889494,
            "number":"+7 902 4321 2123",
            "phone_number_type_id":2
         }
      ],
      "emails":[
         {
            "id":629990,
            "email":"john.smith@example.com",
            "secondary_email_type_id":2
         }
      ],
      "social_accounts":[
         {
            "id":29035,
            "name":"john_smith",
            "social_account_type_id":1
         }
      ],
      "websites":[
         {
            "id":212228,
            "url":"example.com",
            "secondary_website_type_id":1
         }
      ],
      "field_values":[
         {
            "field_id":"102360",
            "field_type_id":5,
            "value":"Red"
         },
         {
            "field_id":"102363",
            "field_parent_id":"102361",
            "field_type_id":2,
            "value":"102363"
         }
      ],
      "private":true,
      "permissions":[
         {
            "id":207523,
            "accessor_id":12793,
            "accessor_type":"User",
            "permission":"1"
         }
      ]
   }
}'


Note: add _destroy: true to any object of array 
to remove particular object. 
Add new object to array to create new object.

Deleting a Contact

Permanently deletes a contact. It cannot be undone.

Returns

Returns nothing. If the contact ID does not exist, an error is returned.

Definition

DELETE https://app.karmacrm.com/api/v2/contacts/{CONTACT_ID}.json

Example Request

curl -X DELETE -G \
https://app.karmacrm.com/api/v2/contacts/813130.json \
-d api_token=FDGz79n8D2Cz2bjqB7BB

List of Contacts

List of contacts you can see.

Returns

A dictionary with a results property that contains an array of up to count contacts, starting at index offset. Each entry in the array is a separate contact object. If no more contacts are available, the resulting array will be empty. This request should never return an error.

Definition

GET http://app.karmacrm.com/api/v2/contacts.json?page={PAGE_NUMBER}

Example Request

curl -G https://app.karmacrm.com/api/v2/contacts.json \
-d api_token=FDGz79n8D2Cz2bjqB7BB \
-d page=1

Example Response

{
   "results":[
      {
         "id":8733,
         "first_name":"John",
         "last_name":"Smith",
         "background":"Good developer with 3+ years of experience",
         "position":"developer",
         "avatar_url":"/assets/person_thumb.png",
         "private_notes":null,
         "department":"Development",
         "cached_tag_list":null,
         "organization_id":1,
         "group_id":null,
         "lead_status_id":79223,
         "lead_process_id":32637,
         "referral_source_id":42264,
         "user_id":1,
         "created_by_id":1,
         "created_at":"2013-07-12T08:36:48Z",
         "updated_at":"2013-07-12T08:36:48Z",
         "note_last_added_at":null,
         "note_last_added_id":null,
         "industry_id":4739,
         "private":true,
         "permission":1,
         "company":{
            "id":3203,
            "name":"Microsoft"
         },
         "emails":[
            {
               "id":8741,
               "email":"john.smith@example.com",
               "secondary_email_type_id":2
            }
         ],
         "websites":[
            {
               "id":5,
               "url":"example.com",
               "secondary_website_type_id":1
            }
         ],
         "addresses":[
            {
               "id":6,
               "street":"South St",
               "street_2":null,
               "city":"Chicago",
               "state":"Illinois",
               "country":"US",
               "postal_code":"60667",
               "address_type":2
            }
         ],
         "social_accounts":[
            {
               "id":5,
               "name":"john_smith",
               "social_account_type_id":1
            }
         ],
         "field_values":[
            {
               "id":10,
               "value":"Red",
               "field_type_id":5,
               "field_parent_id":null,
               "field_id":102360
            },
            {
               "id":11,
               "value":"102363",
               "field_type_id":2,
               "field_parent_id":102361,
               "field_id":102363
            }
         ],
         "permissions":[
               "id": 1,
               "accessor_id":12793,
               "accessor_type":"User",
               "permission":"1"
         ]
      }
   ],
   "total_count":1,
}

List of Contact with filters

You can filter contacts by fields, just add parameters at the end of the url

For date fields one can use datetime in the format YYYYMMDDTHHMMSSZ either shortcuts "tomorrow", "today", "yesterday", "this_week", "this_month", "last_month". Aloowed values for operator are 'and', 'not', 'gte', 'lte', 'between', 'between_gt_left_lt_right', 'between_gt_left', 'between_lt_right'.

Definition

GET https://app.karmacrm.com/api/v2/contacts?page={PAGE}&result_type=backbone&dirty=true&report_id={REPORT_ID&columns[]=first_name&columns[]=last_name&columns[]={custom_field_{FIELD_ID}}&filters[advanced]=true&filters[first_name][values]=FIRST_NAME&filters[last_name][values]=LAST_NAME&filters[position][values]=TITLE&filters[department][values]=DEPARTMENT&filters[company][values]=COMPANY&filters[phone_numbers][values]=PHONE_NUMBER&filters[secondary_emails][values]=EMAIL&filters[secondary_websites][values]=WEBSITE&filters[social_accounts][values]=SOCIAL_ACCOUNT&filters[addresses][values][street]=ADDRESS&filters[addresses][values][city]=CITY&filters[addresses][values][state]=STATE&filters[addresses][values][postal_code]=POSTAL_CODE&filters[addresses][values][country]=US&filters[background][values]=BACKGROUND&filters[user_id][operator]=not&filters[user_id][values][]={USER_ID}&filters[private_notes][values]=PRIVATE_NOTES&filters[lead_process_id][operator]=or&filters[lead_process_id][values][]={CONTACT_STAGE_ID}&filters[lead_status_id][operator]=or&filters[lead_status_id][values][]={CONTACT_STATUS_ID}&filters[referral_source_id][operator]=or&filters[referral_source_id][values][]={REFERRAL_SOURCE_ID}&filters[industry_id][operator]=or&filters[industry_id][values][]={INDUSTRY_ID}&filters[custom_field_{FIELD_ID}][operator]=or&filters[custom_field_{FIELD_ID}][values][]={FIELD_VALUE_ID}&filters[created_at][operator]=between&filters[created_at][values]=yesterday&filters[updated_at][operator]=between&filters[updated_at][values]=this_month

Example Request

curl -G https://app.karmacrm.com/api/v2/contacts.json \
-d api_token=FDGz79n8D2Cz2bjqB7BB&page=1 \
-d filters[first_name]=John \
-d filter[last_name]=Snow

Example Response

{
   "results":[
      {
         "id":8733,
         "first_name":"John",
         "last_name":"Smith",
         "background":"Good developer with 3+ years of experience",
         "position":"developer",
         "avatar_url":"/assets/person_thumb.png",
         "private_notes":null,
         "department":"Development",
         "cached_tag_list":null,
         "organization_id":1,
         "group_id":null,
         "lead_status_id":79223,
         "lead_process_id":32637,
         "referral_source_id":42264,
         "user_id":1,
         "created_by_id":1,
         "created_at":"2013-07-12T08:36:48Z",
         "updated_at":"2013-07-12T08:36:48Z",
         "note_last_added_at":null,
         "note_last_added_id":null,
         "industry_id":4739,
         "private":true,
         "permission":1,
         "company":{
            "id":3203,
            "name":"Microsoft"
         },
         "emails":[
            {
               "id":8741,
               "email":"john.smith@example.com",
               "secondary_email_type_id":2
            }
         ],
         "websites":[
            {
               "id":5,
               "url":"example.com",
               "secondary_website_type_id":1
            }
         ],
         "addresses":[
            {
               "id":6,
               "street":"South St",
               "street_2":null,
               "city":"Chicago",
               "state":"Illinois",
               "country":"US",
               "postal_code":"60667",
               "address_type":2
            }
         ],
         "social_accounts":[
            {
               "id":5,
               "name":"john_smith",
               "social_account_type_id":1
            }
         ],
         "field_values":[
            {
               "id":10,
               "value":"Red",
               "field_type_id":5,
               "field_parent_id":null,
               "field_id":102360
            },
            {
               "id":11,
               "value":"102363",
               "field_type_id":2,
               "field_parent_id":102361,
               "field_id":102363
            }
         ],
         "permissions":[
               "id": 1,
               "accessor_id":12793,
               "accessor_type":"User",
               "permission":"1"
         ]
      }
   ],
   "total_count":1,
}

List of Company Contacts

Definition

GET http://app.karmacrm.com/api/v2/companies/{COMPANY_ID}/contacts.json?page={PAGE_NUMBER}

Example Request

curl -G https://app.karmacrm.com/api/v2/companies/1/contacts.json \
-d api_token=FDGz79n8D2Cz2bjqB7BB \
-d page=1

Example Response

{
  "results": [
    {
      "id": "8733",
      "first_name": "John",
      "last_name": "Smith",
      "background": "Good developer with 3+ years of experience",
      "position": "developer",
      "avatar_url": "/assets/person_thumb.png",
      "private_notes": null,
      "department": "Development",
      "cached_tag_list": null,
      "organization_id": 1,
      "group_id": null,
      "lead_status_id": 79223,
      "lead_process_id": 32637,
      "referral_source_id": 42264,
      "user_id": 1,
      "created_at": "2013-07-12T08:36:48Z",
      "updated_at": "2013-07-12T08:36:48Z",
      "created_by_id": 1,
      "note_last_added_at": null,
      "note_last_added_id": null,
      "industry_id": 4739,
      "private": true,
      "permission": 1,
      "company": {
        "id": 3203,
        "name": "Microsoft"
      },
      "emails": [
        {
          "id": 8741,
          "email": "john.smith@example.com",
          "secondary_email_type_id": 2
        }
      ],
      "websites": [
        {
          "id": 5,
          "url": "example.com",
          "secondary_website_type_id": 1
        }
      ],
      "addresses": [
        {
          "id": 6,
          "street": "South St",
          "street_2": null,
          "city": "Chicago",
          "state": "Illinois",
          "country": "US",
          "postal_code": "60667",
          "address_type": 2
        }
      ],
      "social_accounts": [
        {
          "id": 5,
          "name": "john_smith",
          "social_account_type_id": 1
        }
      ],
      "field_values": [
        {
          "id": 10,
          "value": "Red",
          "field_type_id": 5,
          "field_parent_id": null,
          "field_id": 102360
        },
        {
          "id": 11,
          "value": "102363",
          "field_type_id": 2,
          "field_parent_id": 102361,
          "field_id": 102363
        }
      ],
      "permissions": [

      ]
    }
  ],
  "total_count": 1
}

Companies

Creates a new company object.

Arguments
id: integer
name: string
background: string
Used to house any detailed information about company
referral_source_id: integer
industry_id: integer
user_id: integer
tag_list: string
List of comma-separated tags
phone_numbers: array
List of phone numbers
emails: array
List of email addresses
websites: array
List of websites
addresses: array
List of addresses
social_accounts: array
List of social accounts
field_values: array
List of custom fields
permissions: array
List of permissions
private: boolean
set to true if permissions are specified
Returns

Returns a company object if the call succeeded.

Creating a New Company

Arguments
name: required
background: optional
Used to house any detailed information about company
referral_source_id: optional
industry_id: optional
phone_numbers: optional
List of phone numbers
emails: optional
List of email addresses
tag_list: optional
List of comma-separated tags
websites: optional
List of websites
addresses: optional
List of addresses
social_accounts: optional
List of social accounts
field_values: optional
List of custom fields
permissions: optional
List of permissions
private: required
set to true if permissions are specified
user_id: optional
Returns

A company record

Definition

POST https://app.karmacrm.com/api/v2/companies.json

Example Request

curl -H "Accept: application/json" \
-H "Content-type: application/json" \
-X POST https://app.karmacrm.com/api/v2/companies.json?\
api_token=FDGz79n8D2Cz2bjqB7BB \
-d '{
   "company":{
      "name":"Widgets LLC",
      "background":"Small company with inteligent employees",
      "referral_source_id":42264,
      "industry_id":4739,
      "tag_list":"development, usa",
      "addresses":[
         {
            "street":"South St",
            "city":"Chicago",
            "state":"Illinois",
            "country":"USA",
            "postal_code":"60667",
            "address_type":2
         }
      ],
      "phone_numbers":[
         {
            "number":"+7 902 4321 2123",
            "phone_number_type_id":2
         }
      ],
      "secondary_emails":[
         {
            "email":"widgets@example.com",
            "secondary_email_type_id":1
         }
      ],
      "social_accounts":[
         {
            "name":"widgets_llc",
            "social_account_type_id":1
         }
      ],
      "secondary_websites":[
         {
            "url":"widgetsllc.com",
            "secondary_website_type_id":1
         }
      ],
      "field_values":[
         {
           "field_id":"102395",
           "field_type_id":7,
           "value": "02/15/2012"
         },
         {
           "field_id":"102400",
           "field_parent_id":"102396",
           "field_type_id": 2,
           "value":"102400"
         }
      ],
      "private":true,
      "permissions":[
         {
            "accessor_id":12793,
            "accessor_type":"User",
            "permission":"1"
         }
      ]
   }
}'

Example Response

{
   "id":3204,
   "name":"Widgets LLC",
   "background":"Small company with inteligent employees",
   "private_notes":null,
   "organization_id":1,
   "cached_tag_list":null,
   "referral_source_id":42264,
   "group_id":null,
   "industry_id":4739,
   "user_id":1,
   "created_by_id":1,
   "note_last_added_at":null,
   "note_last_added_id":null,
   "created_at":"2013-07-12T08:34:16Z",
   "updated_at":"2013-07-12T08:34:17Z",
   "private":true,
   "avatar_url":"/assets/company_thumb.jpg",
   "emails":[
      {
         "id":8740,
         "email":"widgets@example.com",
         "secondary_email_type_id":1
      }
   ],
   "websites":[
      {
         "id":4,
         "url":"widgetsllc.com",
         "secondary_website_type_id":1
      }
   ],
   "addresses":[
      {
         "id":5,
         "street":"South St",
         "street_2":null,
         "city":"Chicago",
         "state":"Illinois",
         "country":"US",
         "postal_code":"60667",
         "address_type":2
      }
   ],
   "social_accounts":[
      {
         "id":4,
         "name":"widgets_llc",
         "social_account_type_id":1
      }
   ],
   "field_values":[
      {
         "id":8,
         "value":"02/15/2012",
         "field_type_id":7,
         "field_parent_id":null,
         "field_id":102395
      },
      {
         "id":9,
         "value":"102400",
         "field_type_id":2,
         "field_parent_id":102396,
         "field_id":102400
      }
   ],
   "permissions":[
         "id": 1,
         "accessor_id":12793,
         "accessor_type":"User",
         "permission":"1"
   ]
}

Retrieving a Company

Retrieves the details of an existing company. You need only supply the unique company identifier that was returned upon company creation.

Returns

Returns a company object if a valid identifier was provided.

Definition

GET https://app.karmacrm.com/api/v2/companies/{COMPANY_ID}.json

Example Request

curl -G https://app.karmacrm.com/api/v2/companies/976621.json \
-d api_token=FDGz79n8D2Cz2bjqB7BB

Example Response

{
   "id":3204,
   "name":"Widgets LLC",
   "background":"Small company with inteligent employees",
   "private_notes":null,
   "organization_id":1,
   "cached_tag_list":null,
   "referral_source_id":42264,
   "group_id":null,
   "industry_id":4739,
   "user_id":1,
   "created_by_id":1,
   "note_last_added_at":null,
   "note_last_added_id":null,
   "created_at":"2013-07-12T08:34:16Z",
   "updated_at":"2013-07-12T08:34:17Z",
   "private":true,
   "avatar_url":"/assets/company_thumb.jpg",
   "emails":[
      {
         "id":8740,
         "email":"widgets@example.com",
         "secondary_email_type_id":1
      }
   ],
   "websites":[
      {
         "id":4,
         "url":"widgetsllc.com",
         "secondary_website_type_id":1
      }
   ],
   "addresses":[
      {
         "id":5,
         "street":"South St",
         "street_2":null,
         "city":"Chicago",
         "state":"Illinois",
         "country":"US",
         "postal_code":"60667",
         "address_type":2
      }
   ],
   "social_accounts":[
      {
         "id":4,
         "name":"widgets_llc",
         "social_account_type_id":1
      }
   ],
   "field_values":[
      {
         "id":8,
         "value":"02/15/2012",
         "field_type_id":7,
         "field_parent_id":null,
         "field_id":102395
      },
      {
         "id":9,
         "value":"102400",
         "field_type_id":2,
         "field_parent_id":102396,
         "field_id":102400
      }
   ],
   "permissions":[
         "id": 1,
         "accessor_id":12793,
         "accessor_type":"User",
         "permission":"1"
   ]
}

Updating a Company

Updates a Contact

Arguments
name: required
background: optional
Used to house any detailed information about company
referral_source_id: optional
industry_id: optional
phone_numbers: optional
List of phone numbers
emails: optional
List of email addresses
tag_list: optional
List of comma-separated tags
websites: optional
List of websites
addresses: optional
List of addresses
social_accounts: optional
List of social accounts
field_values: optional
List of custom fields
permissions: optional
List of permissions
private: required
set to true if permissions are specified
user_id: optional
Returns

Returns a contact object if the call succeeded.

Definition

PUT https://app.karmacrm.com/api/v2/companies/{COMPANY_ID}.json

Example Request

curl -H "Accept: application/json" \
-H "Content-type: application/json" \
-X PUT https://app.karmacrm.com/api/v2/companies/976621.json?\
api_token=FDGz79n8D2Cz2bjqB7BB \
-d '{
   "company":{
      "name":"Widgets LLC",
      "background":"Small company with inteligent employees",
      "referral_source_id":42264,
      "industry_id":4739,
      "tag_list":"development, usa",
      "addresses":[
         {
            "id":1016852,
            "street":"South St",
            "city":"Chicago",
            "state":"Illinois",
            "country":"USA",
            "postal_code":"60667",
            "address_type":2
         }
      ],
      "phone_numbers":[
         {
            "id":893111,
            "number":"+7 902 4321 2123",
            "phone_number_type_id":2
         }
      ],
      "secondary_emails":[
         {
            "id":634496,
            "email":"widgets@example.com",
            "secondary_email_type_id":1
         }
      ],
      "social_accounts":[
         {
            "id":29199,
            "name":"widgets_llc",
            "social_account_type_id":1
         }
      ],
      "secondary_websites":[
         {
            "id":212770,
            "url":"widgetsllc.com",
            "secondary_website_type_id":1
         }
      ],
      "field_values":[
         {
           "id":2017619,
           "field_id":"102395",
           "field_type_id":7,
           "value": "02/15/2012"
         },
         {
           "id":2017620,
           "field_id":"102400",
           "field_parent_id":"102396",
           "field_type_id": 2,
           "value":"102400"
         }
      ],
      "private":true,
      "permissions":[
         {
            "id":207546,
            "accessor_id":12793,
            "accessor_type":"User",
            "permission":"1"
         }
      ]
   }
}'

Deleting a Company

Permanently deletes a company. It cannot be undone.

Returns

Returns nothing. If the company ID does not exist, an error is returned.

Definition

DELETE https://app.karmacrm.com/api/v2/companies/{COMPANY_ID}.json

Example Request

curl -X DELETE -G \
https://app.karmacrm.com/api/v2/companies/813130.json \
-d api_token=FDGz79n8D2Cz2bjqB7BB

List of Companies

List of contacts you can see.

Returns

A dictionary with a results property that contains an array of up to count companies, starting at index offset. Each entry in the array is a separate company object. If no more companies are available, the resulting array will be empty. This request should never return an error.

Definition

GET http://app.karmacrm.com/api/v2/companies.json?page={PAGE_NUMBER}

Example Request

curl -G https://app.karmacrm.com/api/v2/companies.json \
-d api_token=FDGz79n8D2Cz2bjqB7BB \
-d page=1

Example Response

{
   "results":[
      {
         "id":"976621",
         "name":"Widgets LLC",
         "organization_id":1213,
         "user_id":12793,
         "created_at":"2013-07-09T07:49:32Z",
         "updated_at":"2013-07-09T07:56:54Z",
         "referral_source_id":42264,
         "industry_id":4739,
         "background":"Small company with inteligent employees",
         "private":true,
         "created_by_id":12793,
         "group_id":null,
         "note_last_added_at":null,
         "note_last_added_id":null,
         "avatar_url":"/assets/company_thumb-dd391a.jpg",
         "private_notes":null,
         "tag_list":"development, usa",
         "class_name":"Company",
          "emails":[

           ],
           "websites":[

           ],
           "addresses":[

           ],
           "social_accounts":[

           ],
           "field_values":[

           ],
           "permissions":[

           ]
      },
      {
         "id":"975797",
         "name":"Microsoft",
         "organization_id":1213,
         "user_id":12793,
         "created_at":"2013-07-08T06:57:45Z",
         "updated_at":"2013-07-09T07:47:32Z",
         "referral_source_id":null,
         "industry_id":null,
         "background":"",
         "private":true,
         "created_by_id":12793,
         "group_id":null,
         "note_last_added_at":null,
         "note_last_added_id":null,
         "avatar_url":"/assets/company_thumb-dd39122.jpg",
         "private_notes":null,
         "tag_list":"",
          "emails":[

           ],
           "websites":[

           ],
           "addresses":[

           ],
           "social_accounts":[

           ],
           "field_values":[

           ],
           "permissions":[

           ]
       }
   ],
   "total_count":2,
   "filter":""
}

List of Companies with filters

You can filter companies by fields, just add parameters at the end of the url

Definition

GET http://app.karmacrm.com/api/v2/companies.json?page={PAGE_NUMBER}&filters[name]={COMPANY_NAME}

Example Request

curl -G https://app.karmacrm.com/api/v2/companies.json \
-d api_token=FDGz79n8D2Cz2bjqB7BB&page=1 \
-d filters[name]=Microsoft 

Example Response

{
   "results":[
      {
         "id":"975797",
         "name":"Microsoft",
         "organization_id":1213,
         "user_id":12793,
         "created_at":"2013-07-08T06:57:45Z",
         "updated_at":"2013-07-09T07:47:32Z",
         "referral_source_id":null,
         "industry_id":null,
         "background":"",
         "private":true,
         "created_by_id":12793,
         "group_id":null,
         "note_last_added_at":null,
         "note_last_added_id":null,
         "avatar_url":"/assets/company_thumb-dd391.jpg",
         "private_notes":null,
         "tag_list":"",
          "emails":[

           ],
           "websites":[

           ],
           "addresses":[

           ],
           "social_accounts":[

           ],
           "field_values":[

           ],
           "permissions":[

           ]
       }
   ],
   "total_count":1,
}

Cases

Arguments
id: integer
subject: string
description: string
case_status_id: integer
case_priority_id: integer
case_type_id: integer
user_id: integer
tag_list: string
closing_notes: string
participants: array
List of related contacts, deals, companies, users, cases this task associated with
field_values: array
List of custom fields
permissions: array
List of permissions
private: boolean
set to true if permissions are specified

Creating a New Case

Creates a new case object.

Arguments
subject: required
description: optional
case_status_id: optional
case_priority_id: optional
user_id: optional
case_type_id: optional
tag_list: optional
closing_notes: optional
participants: optional
List of related contacts, deals, companies, users, cases this task associated with
field_values: optional
List of custom fields
permissions: optional
List of permissions
private: optional
set to true if permissions are specified
Returns

Returns a case object if the call succeeded.

Definition

POST https://app.karmacrm.com/api/v2/cases.json

Example Request

curl -H "Accept: application/json" \
-H "Content-type: application/json" \
-X POST https://app.karmacrm.com/api/v2/cases.json?\
api_token=FDGz79n8D2Cz2bjqB7BB -d '{
  "case":{
    "subject":"Big project",
    "user_id":"1",
    "notify_user":false,
    "case_status_id":"5",
    "case_priority_id":"9",
    "case_type_id":"3",
    "description":"This will be a pig project",
    "tag_list":"project",
    "closing_notes":"final notes",
    "participants":[
       {
          "participater_id":14,
          "participater_type":"User"
       }
    ],
    "field_values":[
       {
          "field_id":"4",
          "value":"07/18/2013",
          "field_type_id":7
       }
    ],
    "private":"true",
    "permissions":[
       {
          "accessor_id":"22",
          "accessor_type":"User",
          "label":"Test test",
          "key":"permissions",
          "index":833,
          "permission":"1"
       }
    ]
 }
}'

Example Response

{
  "id": 7,
  "subject": "Big project",
  "description": "This will be a pig project",
  "user_id": 1,
  "case_status_id": 5,
  "case_priority_id": 9,
  "case_type_id": 3,
  "tag_list": "project",
  "closing_notes": "final notes",
  "private": true,
  "participants": [
    {
      "id": 117,
      "participater_id": "14",
      "participater_type": "User",
      "path": "settings/users"
    }
  ],
  "field_values": [
    {
      "id": 21,
      "value": "07/18/2013",
      "field_type_id": 7,
      "field_parent_id": null,
      "field_id": 4
    }
  ],
  "permissions": [
    {
      "id": 18,
      "permission": 1,
      "accessor_id": 22,
      "accessor_type": "User"
    }
  ]
}

Retrieving a Case

Retrieves the details of an existing case. You need only supply the unique case identifier that was returned upon case creation.

Returns

Returns a case object if a valid identifier was provided

Definition

GET https://app.karmacrm.com/api/v2/cases/{CASE_ID}.json

Example Request

curl -G https://app.karmacrm.com/api/v2/cases/7.json? \
-d api_token=FDGz79n8D2Cz2bjqB7BB

Example Response

{
  "id": "7",
  "subject": "Big project",
  "description": "This will be a pig project",
  "user_id": 1,
  "case_status_id": 5,
  "case_priority_id": 9,
  "case_type_id": 3,
  "tag_list": "project",
  "closing_notes": "final notes",
  "private": true,
  "participants": [
    {
      "id": 117,
      "participater_id": 14,
      "participater_type": "User",
      "path": "settings/users"
    }
  ],
  "field_values": [
    {
      "id": 21,
      "value": "07/18/2013",
      "field_type_id": 7,
      "field_parent_id": null,
      "field_id": 4
    }
  ],
  "permissions": [
    {
      "id": 18,
      "permission": 1,
      "accessor_id": 22,
      "accessor_type": "User"
    }
  ]
}

Updating a Case

Updates a Case

Arguments
subject: required
description: optional
case_status_id: optional
case_priority_id: optional
user_id: optional
case_type_id: optional
tag_list: optional
closing_notes: optional
participants: optional
List of related contacts, deals, companies, users, cases this task associated with
field_values: optional
List of custom fields
permissions: optional
List of permissions
private: optional
set to true if permissions are specified
Returns

Returns a case object if the call succeeded.

Definition

PUT https://app.karmacrm.com/api/v2/cases/{CASE_ID}.json

Example Request

curl -H "Accept: application/json" -H \
"Content-type: application/json" \
-X PUT https://app.karmacrm.com/api/v2/cases/7.json?\
api_token=FDGz79n8D2Cz2bjqB7BB -d '{
  "case":{
    "subject":"Big project",
    "description":"This will be a pig project",
    "user_id":"1",
    "case_status_id":"5",
    "case_priority_id":"9",
    "case_type_id":"3",
    "tag_list":"project",
    "closing_notes":"final notes",
    "notify_user":false,
    "participants":[
       {
          "id":117,
          "participater_id":14,
          "participater_type":"User"
       }
    ],
    "field_values":[
       {
          "id": 21,
          "field_id":"4",
          "value":"07/18/2013",
          "field_type_id":7
       }
    ],
    "private":"true",
    "permissions":[
       {
          "id": 18,
          "accessor_id":"22",
          "accessor_type":"User",
          "label":"Test test",
          "key":"permissions",
          "index":833,
          "permission":"1"
       }
    ]
 }
}'

Deleting a Case

Permanently deletes a case. It cannot be undone.

Returns

Returns nothing. If the case ID does not exist, an error is returned.

Definition

DELETE https://app.karmacrm.com/api/v2/cases/{CASE_ID}.json

Example Request

curl -X DELETE -G \
https://app.karmacrm.com/api/v2/cases/243130.json \
-d api_token=FDGz79n8D2Cz2bjqB7BB

List of Cases

List of cases you can see.

Returns

A dictionary with a results property that contains an array of up to count cases, starting at index offset. Each entry in the array is a separate case object. If no more cases are available, the resulting array will be empty. This request should never return an error.

Definition

GET http://app.karmacrm.com/api/v2/cases.json?page={PAGE_NUMBER}

Example Request

curl -G https://app.karmacrm.com/api/v2/cases.json \
-d api_token=FDGz79n8D2Cz2bjqB7BB \
-d page=1

Example Response

{
  "results": [
    {
      "id": "7",
      "subject": "Big project",
      "description": "This will be a pig project",
      "user_id": 1,
      "case_status_id": 5,
      "case_priority_id": 9,
      "case_type_id": 3,
      "tag_list": "project",
      "closing_notes": "final notes",
      "private": true,
      "participants": [
        {
          "id": 117,
          "participater_id": 14,
          "participater_type": "User",
          "path": "settings/users"
        }
      ],
      "field_values": [
        {
          "id": 21,
          "value": "07/18/2013",
          "field_type_id": 7,
          "field_parent_id": null,
          "field_id": 4
        }
      ],
      "permissions": [
        {
          "id": 18,
          "permission": 1,
          "accessor_id": 22,
          "accessor_type": "User"
        }
      ]
    },
  ],
  "total_count": 1,
}

List of Contact Cases

Definition

GET http://app.karmacrm.com/api/v2/contacts/#{CONTACT_ID}/cases.json?page={PAGE_NUMBER}

Example Request

curl -G https://app.karmacrm.com/api/v2/contacts/8733/cases.json? \
-d api_token=FDGz79n8D2Cz2bjqB7BB \
-d page=1

Example Response

{
  "results": [
    {
      "id": "8",
      "subject": "Big project",
      "description": "",
      "user_id": 1,
      "case_status_id": null,
      "case_priority_id": null,
      "case_type_id": null,
      "tag_list": "",
      "closing_notes": "",
      "private": false,
      "participants": [
        {
          "id": 128,
          "participater_id": "8733",
          "participater_type": "Contact"
        }
      ],
      "field_values": [

      ],
      "permissions": [

      ]
    }
  ],
  "total_count": 1
}

List of Company Cases

Definition

GET http://app.karmacrm.com/api/v2/companies/#{COMPANY_ID}/cases.json?page={PAGE_NUMBER}

Example Request

curl -G https://app.karmacrm.com/api/v2/companies/2798/cases.json? \
-d api_token=FDGz79n8D2Cz2bjqB7BB \
-d page=1

Example Response

{
  "results": [
    {
      "id": "9",
      "subject": "Big project",
      "description": "",
      "user_id": 1,
      "case_status_id": null,
      "case_priority_id": null,
      "case_type_id": null,
      "tag_list": "",
      "closing_notes": "",
      "private": false,
      "participants": [
        {
          "id": 130,
          "participater_id": "2798",
          "participater_type": "Company"
        }
      ],
      "field_values": [

      ],
      "permissions": [

      ]
    }
  ],
  "total_count": 1
}

Deals

Arguments
id: integer
name: string
description: string
due_on: date
currency: string
price: string
lead_id: string - maps to contact_id
The contact this deal assigned to
company_id: integer
The company this deal assigned to
proposal_status_id: integer - maps to deal_stage_id
tag_list: string
user_id: integer
The user this deal assigned to
field_values: array
List of custom fields
Returns

A deal record

Creating a New Deal

Creates a new deal object.

Arguments
name: required
description: optional
company_id: optional
The company this deal assigned to
currency: optional
due_on: optional
lead_id: optional - maps to contact_id
The contact this deal assigned to
price: optional
proposal_status_id: optional - maps to deal_stage_id
tag_list: optional
user_id: optional
The user this deal assigned to
field_values: optional
List of custom fields
Returns

Returns a deal object if the call succeeded.

Definition

POST https://app.karmacrm.com/api/v2/deals.json

Example Request

curl -H "Accept: application/json" \
-H "Content-type: application/json" \
-X POST https://app.karmacrm.com/api/v2/deals.json?\
api_token=FDGz79n8D2Cz2bjqB7BB \
-d '{
{
   "deal":{
      "name":"Meet with my boss",
      "company_id":"2530",
      "lead_id":"",
      "price":"100",
      "currency":"USD",
      "due_on":"07/13/2013",
      "user_id":"1",
      "notify_user":false,
      "description":"Have a lunch",
      "proposal_status_id":"7",
      "important_dates":[
         {
            "date":"07/17/2013"
         }
      ],
      "tag_list":"lunch, boss",
      "probability":"10",
      "field_values":[
         {
            "field_id":"3",
            "value":"I need to be there",
            "field_type_id":4
         }
      ]
   }
}'

Example Response

{
   "id":5,
   "name":"Meet with my boss",
   "description":"Have a lunch",
   "price":100.0,
   "currency":"USD",
   "probability":10,
   "tag_list":"lunch, boss",
   "due_on":"2013-07-13",
   "private_notes":null,
   "proposal_status_id":7,
   "lead_id":null,
   "private":false,
   "organization_id":1,
   "user_id":1,
   "created_at":"2013-07-12T09:08:42Z",
   "updated_at":"2013-07-12T09:08:42Z",
   "created_by_id":1,
   "group_id":null,
   "note_last_added_at":null,
   "note_last_added_id":null,
   "permission":1,
   "field_values":[
      {
         "id":15,
         "value":"I need to be there",
         "field_type_id":4,
         "field_parent_id":null,
         "field_id":3
      }
   ],
   "relationships":[

   ]
}

Retrieving a Deal

Retrieves the details of an existing deal. You need only supply the unique deal identifier that was returned upon deal creation.

Returns

Returns a deal object if a valid identifier was provided.

Definition

GET https://app.karmacrm.com/api/v2/deals/{DEAL_ID}.json

Example Request

curl -G https://app.karmacrm.com/api/v2/deals/38367.json \
-d api_token=FDGz79n8D2Cz2bjqB7BB

Example Response

{
   "id":"5",
   "name":"Meet with my boss",
   "description":"Have a lunch",
   "price":100.0,
   "currency":"USD",
   "probability":10,
   "tag_list":"lunch, boss",
   "due_on":"2013-07-13",
   "private_notes":null,
   "proposal_status_id":7,
   "lead_id":null,
   "private":false,
   "organization_id":1,
   "user_id":1,
   "created_at":"2013-07-12T09:08:42Z",
   "updated_at":"2013-07-12T09:08:42Z",
   "created_by_id":1,
   "group_id":null,
   "note_last_added_at":null,
   "note_last_added_id":null,
   "permission":1,
   "field_values":[
      {
         "id":15,
         "value":"I need to be there",
         "field_type_id":4,
         "field_parent_id":null,
         "field_id":3
      }
   ],
   "relationships":[

   ]
}

Updating a Deal

Updates a Deal

Arguments
name: required
description: optional
company_id: optional
The company this deal assigned to
currency: optional
due_on: optional
lead_id: optional - maps to contact_id
The contact this deal assigned to
price: optional
proposal_status_id: optional - maps to deal_stage_id
tag_list: optional
user_id: optional
The user this deal assigned to
field_values: optional
List of custom fields
Returns

Returns a deal object if the call succeeded.

Definition

PUT https://app.karmacrm.com/api/v2/deals/{DEAL_ID}.json

Example Request

curl -H "Accept: application/json" \
-H "Content-type: application/json" \
-X PUT https://app.karmacrm.com/api/v2/deals/38367.json?\
api_token=FDGz79n8D2Cz2bjqB7BB \
-d '{
   "deal":{
      "name": "Meet with my boss",
      "description": "Have a lunch",
      "company_id": 976621,
      "currency": "USD",
      "due_on": "07/12/2013",
      "lead_id": "",
      "notify_user": false,
      "price": "10000",
      "proposal_status_id": 36567,
      "tag_list": "lunch, boss",
      "user_id": 12793
   }
}'

Deleting a Deal

Permanently deletes a deal. It cannot be undone.

Returns

Returns nothing. If the deal ID does not exist, an error is returned.

Definition

DELETE https://app.karmacrm.com/api/v2/deals/{DEAL_ID}.json

Example Request

curl -X DELETE -G \
https://app.karmacrm.com/api/v2/deals/243130.json \
-d api_token=FDGz79n8D2Cz2bjqB7BB

List of Deals

List of deals you can see.

Returns

A dictionary with a results property that contains an array of up to count deals, starting at index offset. Each entry in the array is a separate deal object. If no more deals are available, the resulting array will be empty. This request should never return an error.

Definition

GET http://app.karmacrm.com/api/v2/deals.json?page={PAGE_NUMBER}

Example Request

curl -G https://app.karmacrm.com/api/v2/deals.json \
-d api_token=FDGz79n8D2Cz2bjqB7BB \
-d page=1

Example Response

{
   "results":[
      {
         "id":"5",
         "name":"Meet with my boss",
         "description":"Have a lunch",
         "price":100.0,
         "currency":"USD",
         "probability":10,
         "tag_list":"lunch, boss",
         "due_on":"2013-07-13",
         "private_notes":null,
         "proposal_status_id":7,
         "lead_id":null,
         "private":false,
         "organization_id":1,
         "user_id":1,
         "created_at":"2013-07-12T09:08:42Z",
         "updated_at":"2013-07-12T09:08:42Z",
         "created_by_id":1,
         "group_id":null,
         "note_last_added_at":null,
         "note_last_added_id":null,
         "permission":1,
         "field_values":[
            {
               "id":15,
               "value":"I need to be there",
               "field_type_id":4,
               "field_parent_id":null,
               "field_id":3
            }
         ],
         "relationships":[

         ]
      }
   ],
   "total_count":1
}

List of Contact Deals

Definition

GET http://app.karmacrm.com/api/v2/contacts/#{CONTACT_ID}/deals.json?page={PAGE_NUMBER}

Example Request

curl -G https://app.karmacrm.com/api/v2/contacts/8733/deals.json? \
-d api_token=FDGz79n8D2Cz2bjqB7BB \
-d page=1

Example Response

{
  "results": [
    {
      "id": "7",
      "name": "Deal with Jimm",
      "description": "",
      "price": 0.0,
      "currency": "USD",
      "probability": null,
      "tag_list": "",
      "due_on": null,
      "private_notes": null,
      "proposal_status_id": null,
      "lead_id": 8733,
      "private": false,
      "organization_id": 1,
      "user_id": 1,
      "created_at": "2013-07-18T11:06:48Z",
      "updated_at": "2013-07-18T11:06:48Z",
      "created_by_id": 1,
      "group_id": null,
      "note_last_added_at": null,
      "note_last_added_id": null,
      "permission": 1,
      "field_values": [

      ],
      "relationships": [

      ]
    }
  ],
  "total_count": 1
}

List of Company Deals

Definition

GET http://app.karmacrm.com/api/v2/companies/#{COMPANY_ID}/deals.json?page={PAGE_NUMBER}

Example Request

curl -G https://app.karmacrm.com/api/v2/companies/2798/deals.json? \
-d api_token=FDGz79n8D2Cz2bjqB7BB \
-d page=1

Example Response

{
  "results": [
    {
      "id": "8",
      "name": "Deal with Jimm",
      "description": "",
      "price": 0.0,
      "currency": "USD",
      "probability": null,
      "tag_list": "",
      "due_on": null,
      "private_notes": null,
      "proposal_status_id": null,
      "lead_id": null,
      "private": false,
      "organization_id": 1,
      "user_id": 1,
      "created_at": "2013-07-18T11:16:41Z",
      "updated_at": "2013-07-18T11:16:41Z",
      "created_by_id": 1,
      "group_id": null,
      "note_last_added_at": null,
      "note_last_added_id": null,
      "permission": 1,
      "field_values": [

      ],
      "relationships": [

      ]
    }
  ],
  "total_count": 1
}

Events

Arguments
id: integer
name: string
content: string
The description of the event
where: string
The location of the event
calendar_id: integer
all_day: boolean
Specifies is this full day event or not, if not specify specific time(start_time, end_time)
start_date: date
start_time: string
end_date: date
end_time: string
recurring_schedule: hash
reminders: array
List of reminders
participants: array
List of related contacts, deals, companies, users this event associated with

Creating a New Event

Creates a new event object.

Arguments
name: required
content: required
The description of the event
where: optional
The location of the event
calendar_id: required
start_at: required
end_at: required
all_day: required
Specifies is this full day event or not
recurrence: optional
recurrence rules in the RFC2445 format, e.g. ["RRULE:FREQ=DAILY;UNTIL=20141201Z", "EXDATE:20141130Z"]
reminders: optional
List of reminders
participants: optional
List of related contacts, deals, companies, users this event associated with
Returns

Returns a event object if the call succeeded.

Definition

POST https://app.karmacrm.com/api/v3/events.json

Example Request

curl -H "Accept: application/json" \
-H "Content-type: application/json" \
-X POST https://app.karmacrm.com/api/v3/events.json?\
api_token=FDGz79n8D2Cz2bjqB7BB \
-d '{
   "event":{
      "name":"Visit parents",
      "content":"need to visit my parents",
      "where":"New Yourk",
      "start_at":"2013-07-10T10:00:00Z",
      "end_at":"2013-07-10T18:00:00Z",
      "all_day": false,
      "recurrence":["RRULE:FREQ=DAILY;UNTIL=20141201Z", "EXDATE:20141130Z"],
      "calendar_id":24044,
      "reminders":[
        {
          "reminder_type_id":"2",
          "time_increment":"15",
          "interval":"minutes"
        }
      ],
      "participants":[
        {
          "participater_id":12793,
          "participater_type":"User"
        }
      ]
    }
}'

Example Response

{
   "id":869514,
   "name":"Visit parents",
   "content":"need to visit my parents",
   "where":"New Yourk",
   "calendar_id":24044,
   "all_day":false,
   "created_by_id":12793,
   "created_at":"2014-08-27T08:36:59Z",
   "updated_at":"2014-08-27T08:36:59Z",
   "start_at":"2013-07-10T10:00:00Z",
   "end_at":"2013-07-10T18:00:00Z",
   "recurrence":[
      "RRULE:FREQ=DAILY;UNTIL=20141201Z",
      "EXDATE:20141130Z"
   ],
   "reminders":[
      {
         "id":78590,
         "reminder_type_id":2,
         "interval":"minutes",
         "time_increment":15
      }
   ],
   "participants":[
      {
         "id":2108899,
         "label":"Jim Smith",
         "participater_id":12793,
         "participater_type":"User"
      }
   ],
}

Retrieving an Event

Retrieves the details of an existing event. You need only supply the unique event identifier that was returned upon event creation.

Returns

Returns an event object if a valid identifier was provided.

Definition

GET https://app.karmacrm.com/api/v3/events/{EVENT_ID}.json

Example Request

curl -G https://app.karmacrm.com/api/v3/events/210774.json \
-d api_token=FDGz79n8D2Cz2bjqB7BB

Example Response

{
   "id":210774,
   "name":"Visit parents",
   "content":"need to visit my parents",
   "where":"New Yourk",
   "calendar_id":24044,
   "all_day":true,
   "created_by_id":12793,
   "created_at":"2013-07-09T08:57:36Z",
   "updated_at":"2013-07-09T08:57:36Z",
   "start_at":"2013-07-10T00:00:00Z",
   "end_at":"2013-07-10T23:59:59Z",
   "recurrence":[
      "DTSTART:20130710T000000Z",
      "RRULE:FREQ=DAILY;UNTIL=20130711T000000Z",
      "DTEND:20130710T000000Z"
   ],
   "reminders":[
      {
         "id":28129,
         "reminder_type_id":2,
         "interval":"minutes",
         "time_increment":15
      }
   ],
   "participants":[
      {
         "id":309206,
         "label":"Jim Smith",
         "participater_id":12793,
         "participater_type":"User"
      }
   ],
   "event_syncs":[

   ],
   "comments":{
      "results":[

      ],
      "total_count":0
   }
}

Updating an Event

Updates an Event

Arguments
name: required
content: required
The description of the event
where: optional
The location of the event
calendar_id: required
start_date: required
start_time: optional
end_date: required
end_time: optional
recurring_schedule: optional
reminders: optional
List of reminders
participants: optional
List of related contacts, deals, companies, users this event associated with
all_day: required
Specifies is this full day event or not, if not specify specific time(start_time, end_time)
Returns

Returns an event object if the call succeeded.

Definition

PUT https://app.karmacrm.com/api/v3/events/{EVENT_ID}.json

Example Request

curl -H "Accept: application/json" \
-H "Content-type: application/json" \
-X PUT https://app.karmacrm.com/api/v3/events/210774.json?\
api_token=FDGz79n8D2Cz2bjqB7BB \
-d '{
   "event":{
      "all_day":true,
      "name":"Visit parents",
      "content":"need to visit my parents",
      "where":"New Yourk",
      "start_at":"2013-07-10T12:00:00Z",
      "end_at":"2013-07-10T18:00:00Z",
      "calendar_id":24044,
      "recurrence":["RRULE:FREQ=DAILY;UNTIL=20141201Z", "EXDATE:20141130Z"],
      "reminders":[
        {
          "id":28129,
          "reminder_type_id":"2",
          "time_increment":"15",
          "interval":"minutes"
        }
      ],
      "participants":[
        {
          "id":309206,
          "participater_id":12793,
          "participater_type":"User"
        }
      ]
    }
}'

Deleting an Event

Permanently deletes an event. It cannot be undone.

Returns

Returns nothing. If the event ID does not exist, an error is returned.

Definition

DELETE https://app.karmacrm.com/api/v3/events/{EVENT_ID}.json

Example Request

curl -X DELETE -G \
https://app.karmacrm.com/api/v3/events/243130.json \
-d api_token=FDGz79n8D2Cz2bjqB7BB

Calendar events and tasks

List of calendar events and tasks.

Returns

A dictionary with a results property that contains an array of up to count events, starting at index offset. Each entry in the array is a separate event object. If no more events are available, the resulting array will be empty. This request should never return an error.

Definition

GET https://app.karmacrm.com/api/v3/calendars/items.json

Example Request

curl -G \
https://app.karmacrm.com/api/v3/calendars/items.json \
-d calendar_ids[]=24044 \
-d start_date=2013-06-30 \
-d end_date=2013-08-11 \
-d all_events=false \
-d all_todos=false \
-d include[]=todos \
-d include[]=events \
-d page=1 \
-d api_token=FDGz79n8D2Cz2bjqB7BB 

Example Response

{
   "events":[
      {
         "id":210774,
         "name":"Visit parents",
         "calendar_id":24044,
         "all_day":true,
         "logged_at":null,
         "parent_id":null,
         "start_at":"2013-07-10T12:00:00Z",
         "end_at":"2013-07-10T18:00:00Z",
         "recurrence":[
            "RRULE:FREQ=DAILY;UNTIL=20141201Z",
            "EXDATE:20141130Z"
         ]
      },
      {
         "id":211293,
         "name":"monthly",
         "calendar_id":24044,
         "all_day":true,
         "logged_at":null,
         "parent_id":null,
         "start_at":"2013-07-18T00:00:00Z",
         "end_at":"2013-07-18T23:59:59Z",
         "recurrence":[
            "DTSTART:20130718T000000Z",
            "RRULE:FREQ=MONTHLY;COUNT=3;BYMONTHDAY=18"
         ]
      },
      {
         "id":211297,
         "name":"monthly",
         "calendar_id":24044,
         "all_day":true,
         "logged_at":null,
         "parent_id":211293,
         "start_at":"2013-07-18T00:00:00Z",
         "end_at":"2013-07-18T23:59:59Z"
      },
      {
         "id":869514,
         "name":"Visit parents",
         "calendar_id":24044,
         "all_day":false,
         "logged_at":null,
         "parent_id":null,
         "start_at":"2013-07-10T10:00:00Z",
         "end_at":"2013-07-10T18:00:00Z",
         "recurrence":[
            "RRULE:FREQ=DAILY;UNTIL=20141201Z",
            "EXDATE:20141130Z"
         ]
      }
   ],
   "todos":[
      {
         "id":260884,
         "body":"API documentation",
         "time":null,
         "due_at":"2013-07-12T00:00:00Z",
         "due_on":"2013-12-07"
      }
   ]
}

List of Contact Events

Definition

GET http://app.karmacrm.com/api/v3/events.json?page={PAGE_NUMBER}&filters[participants][operator]='and'&filters[participants][values][participater_type]='Contact'&filters[participants][values][participater_id]={CONTACT_ID}

Example Request

curl -G \
https://app.karmacrm.com/api/v3/events.json? \
-d filters[participants][operator]='and' \
-d filters[participants][values][participater_type]='Contact' \
-d filters[participants][values][participater_id]=2098101 \
-d api_token=FDGz79n8D2Cz2bjqB7BB \
-d page=1

Example Response

{
   "results":[
      {
         "id":869515,
         "name":"holyday",
         "content":"",
         "where":"",
         "calendar_id":24044,
         "all_day":true,
         "start_at":"2014-08-27T00:00:00Z",
         "end_at":"2014-08-27T23:59:59Z",
         "participants":[
            {
               "id":2108923,
               "participater_id":2098101,
               "participater_type":"Contact",
               "label":"John Smith"
            },
            {
               "id":2108924,
               "participater_id":12793,
               "participater_type":"User",
               "label":"Jim Smith"
            }
         ]
      }
   ],
   "total_count":1
}

List of Company Events

Definition

GET http://app.karmacrm.com/api/v3/events.json?page={PAGE_NUMBER}&filters[participants][operator]='and'&filters[participants][values][participater_type]='Company'&filters[participants][values][participater_id]={COMPANY_ID}

Example Request

curl -G \
https://app.karmacrm.com/api/v3/events.json? \
-d filters[participants][operator]='and' \
-d filters[participants][values][participater_type]='Company' \
-d filters[participants][values][participater_id]=1382998 \
-d api_token=FDGz79n8D2Cz2bjqB7BB \
-d page=1

Example Response

{
   "results":[
      {
         "id":869519,
         "name":"holyday",
         "content":"",
         "where":"",
         "calendar_id":24044,
         "all_day":true,
         "start_at":"2014-08-27T00:00:00Z",
         "end_at":"2014-08-27T23:59:59Z",
         "participants":[
            {
               "id":2108935,
               "participater_id":1382998,
               "participater_type":"Company",
               "label":"Widgets LLC"
            },
            {
               "id":2108936,
               "participater_id":12793,
               "participater_type":"User",
               "label":"Jim Smith"
            }
         ]
      }
   ],
   "total_count":1
}

List of Deal Events

Definition

GET http://app.karmacrm.com/api/v3/events.json?page={PAGE_NUMBER}&filters[participants][operator]='and'&filters[participants][values][participater_type]='Deal'&filters[participants][values][participater_id]={DEAL_ID}

Example Request

curl -G \
https://app.karmacrm.com/api/v3/events.json? \
-d filters[participants][operator]='and' \
-d filters[participants][values][participater_type]='Deal' \
-d filters[participants][values][participater_id]=38403 \
-d api_token=FDGz79n8D2Cz2bjqB7BB \
-d page=1

Example Response

{
   "results":[
      {
         "id":869520,
         "name":"Holyday",
         "content":"",
         "where":"",
         "calendar_id":24044,
         "all_day":true,
         "start_at":"2014-08-27T00:00:00Z",
         "end_at":"2014-08-27T23:59:59Z",
         "participants":[
            {
               "id":2108940,
               "participater_id":38403,
               "participater_type":"Deal",
               "label":"Meet with my boss"
            },
            {
               "id":2108941,
               "participater_id":12793,
               "participater_type":"User",
               "label":"Jim Smith"
            }
         ]
      }
   ],
   "total_count":1
}

List of Case Events

Definition

GET http://app.karmacrm.com/api/v3/events.json?page={PAGE_NUMBER}&filters[participants][operator]='and'&filters[participants][values][participater_type]='Case'&filters[participants][values][participater_id]={CASE_ID}

Example Request

curl -G \
https://app.karmacrm.com/api/v3/events.json? \
-d filters[participants][operator]='and' \
-d filters[participants][values][participater_type]='Case' \
-d filters[participants][values][participater_id]=2060 \
-d api_token=FDGz79n8D2Cz2bjqB7BB \
-d page=1

Example Response

{
   "results":[
      {
         "id":869521,
         "name":"Holyday",
         "content":"",
         "where":"",
         "calendar_id":24044,
         "all_day":true,
         "start_at":"2014-08-27T00:00:00Z",
         "end_at":"2014-08-27T23:59:59Z",
         "participants":[
            {
               "id":2108945,
               "participater_id":2060,
               "participater_type":"Case",
               "label":"Buy a car"
            },
            {
               "id":2108946,
               "participater_id":12793,
               "participater_type":"User",
               "label":"Jim Smith"
            }
         ]
      }
   ],
   "total_count":1
}

Tasks

Arguments
id: integer
body: string
The task name
description: string
due_on: date
When the task should be done
time: string
The specific time the task should be done
todo_list_id: integer
todo_category_id: integer
user_id: integer
The user identifier the task assigned to, default is current user id
reminders: array
The list of reminders
participants: array
List of related contacts, deals, companies, users, cases this task associated with

Creating a New Task

Creates a new task object.

Arguments
body: required
The task name
description: optional
due_on: optional
When the task should be done
time: optional
The specific time the task should be done
todo_list_id: optional
todo_category_id: optional
user_id: optional
The user identifier the task assigned to, default is current user id
reminders: optional
The list of reminders
participants: optional
List of related contacts, deals, companies, users this task associated with
Returns

Returns a task object if the call succeeded.

Definition

POST https://app.karmacrm.com/api/v2/todos.json

Example Request

curl -H "Accept: application/json" \
-H "Content-type: application/json" \
-X POST https://app.karmacrm.com/api/v2/todos.json?\
api_token=FDGz79n8D2Cz2bjqB7BB \
-d '{
   "todo":{
      "body":"API documentation",
      "description":"We need the documentation for our API ",
      "todo_list_id":"263",
      "todo_category_id":"43043",
      "due_on":"07/12/2013",
      "time":"",
      "user_id":"12793",
      "notify_user":false,
      "reminders":[
         {
            "key":"reminders",
            "index":635,
            "reminder_type_id":"2",
            "time_increment":"15",
            "interval":"minutes"
         }
      ],
      "participants":[
         {
            "label":"Jim Smith",
            "participater_id":12793,
            "participater_type":"User"
         }
      ]
   }
}'

Example Response

{
   "id":1,
   "body":"API documentation",
   "user_id":null,
   "due_on":"2013-12-07",
   "complete":false,
   "organization_id":1,
   "created_at":"2013-07-12T14:58:08+04:00",
   "updated_at":"2013-07-12T14:58:08+04:00",
   "time":null,
   "lead_process_id":null,
   "notification_sent":false,
   "todo_category_id":43043,
   "tasker_id":null,
   "tasker_type":null,
   "private":false,
   "proposal_status_id":null,
   "days_until_due":null,
   "due_at":"2013-07-12T00:00:00+04:00",
   "created_by_id":1,
   "has_reminder":true,
   "followup_type":null,
   "followup_id":null,
   "group_id":null,
   "history_note_count":0,
   "comment_count":0,
   "completed_at":null,
   "completed_by_id":null,
   "todo_template_step_id":null,
   "process_milestone_id":null,
   "skipped":false,
   "dependent_step_complete":false,
   "completion_notes":null,
   "starred":false,
   "todo_list_id":263,
   "description":"We need the documentation for our API ",
   "position":5,
   "calendar_id":null,
   "state":null,
   "rejection_notes":null,
   "todo_template_id":null,
   "participants":[
      {
         "id":87,
         "label":null,
         "participater_id":"12793",
         "participater_type":"User",
         "path":"settings/users"
      }
   ],
   "reminders":[
      {
         "description":null,
         "deliver_at":"2013-07-11T23:45:00+04:00",
         "reminder_type_id":2,
         "sent":false,
         "failed":false,
         "interval":"minutes",
         "time_increment":15,
         "created_at":"2013-07-12T14:58:08+04:00",
         "updated_at":"2013-07-12T14:58:08+04:00",
         "recurring":false,
         "parent_id":null
      }
   ],
   "comments":[

   ]
}

Retrieving a Task

Retrieves the details of an existing task. You need only supply the unique task identifier that was returned upon task creation.

Returns

Returns a task object if a valid identifier was provided

Definition

GET https://app.karmacrm.com/api/v2/todos/{TODO_ID}.json

Example Request

curl -G https://app.karmacrm.com/api/v2/todos/260889.json \
-d api_token=FDGz79n8D2Cz2bjqB7BB

Example Response

{
   "id": 1,
   "body":"API documentation",
   "user_id":null,
   "due_on":"2013-12-07",
   "complete":false,
   "organization_id":1,
   "created_at":"2013-07-12T14:58:08+04:00",
   "updated_at":"2013-07-12T14:58:08+04:00",
   "time":null,
   "lead_process_id":null,
   "notification_sent":false,
   "todo_category_id":43043,
   "tasker_id":null,
   "tasker_type":null,
   "private":false,
   "proposal_status_id":null,
   "days_until_due":null,
   "due_at":"2013-07-12T00:00:00+04:00",
   "created_by_id":1,
   "has_reminder":true,
   "followup_type":null,
   "followup_id":null,
   "group_id":null,
   "history_note_count":0,
   "comment_count":0,
   "completed_at":null,
   "completed_by_id":null,
   "todo_template_step_id":null,
   "process_milestone_id":null,
   "skipped":false,
   "dependent_step_complete":false,
   "completion_notes":null,
   "starred":false,
   "todo_list_id":263,
   "description":"We need the documentation for our API ",
   "position":5,
   "calendar_id":null,
   "state":null,
   "rejection_notes":null,
   "todo_template_id":null,
   "participants":[
      {
         "id":87,
         "label":null,
         "participater_id":"12793",
         "participater_type":"User",
         "path":"settings/users"
      }
   ],
   "reminders":[
      {
         "description":null,
         "deliver_at":"2013-07-11T23:45:00+04:00",
         "reminder_type_id":2,
         "sent":false,
         "failed":false,
         "interval":"minutes",
         "time_increment":15,
         "created_at":"2013-07-12T14:58:08+04:00",
         "updated_at":"2013-07-12T14:58:08+04:00",
         "recurring":false,
         "parent_id":null
      }
   ],
   "comments":[

   ]
}

Updating a Task

Updates a Task

Arguments
body: required
The task name
description: optional
due_on: optional
When the task should be done
time: optional
The specific time the task should be done
todo_list_id: optional
todo_category_id: optional
user_id: optional
The user identifier the task assigned to, default is current user id
reminders: optional
The list of reminders
participants: optional
List of related contacts, deals, companies, users this task associated with
Returns

Returns a task object if the call succeeded.

Definition

PUT https://app.karmacrm.com/api/v2/todos/{TODO_ID}.json

Example Request

curl -H "Accept: application/json" \
-H "Content-type: application/json" \
-X PUT https://app.karmacrm.com/api/v2/todos/260889.json?\
api_token=FDGz79n8D2Cz2bjqB7BB \
-d '{
   "todo":{
      "body":"API documentation",
      "description":"We need the documentation for our API ",
      "todo_list_id":"263",
      "todo_category_id":"43043",
      "due_on":"07/12/2013",
      "time":"",
      "user_id":"12793",
      "notify_user":false,
      "reminders":[
         {
            "id":28215,
            "key":"reminders",
            "index":635,
            "reminder_type_id":"2",
            "time_increment":"15",
            "interval":"minutes"
         }
      ],
      "participants":[
         {
           "id":312916,
            "label":"Jim Smith",
            "participater_id":12793,
            "participater_type":"User"
         }
      ]
   }
}'

Deleting a Task

Permanently deletes a task. It cannot be undone.

Returns

Returns nothing. If the task ID does not exist, an error is returned.

Definition

DELETE https://app.karmacrm.com/api/v2/todos/{TODO_ID}.json

Example Request

curl -X DELETE -G \
https://app.karmacrm.com/api/v2/todos/243130.json \
-d api_token=FDGz79n8D2Cz2bjqB7BB

List of Tasks

List of tasks you can see.

Returns

A dictionary with a results property that contains an array of up to count tasks, starting at index offset. Each entry in the array is a separate task object. If no more tasks are available, the resulting array will be empty. This request should never return an error.

Definition

GET http://app.karmacrm.com/api/v2/todos.json?page={PAGE_NUMBER}

Example Request

curl -G https://app.karmacrm.com/api/v2/todos.json \
-d api_token=FDGz79n8D2Cz2bjqB7BB \
-d page=1

Example Response

{
   "results":[
      {
         "id":"12",
         "body":"API documentation",
         "user_id":1,
         "due_on":"2013-12-07",
         "complete":false,
         "organization_id":1,
         "created_at":"2013-07-12T10:58:08Z",
         "updated_at":"2013-07-12T10:58:08Z",
         "time":null,
         "lead_process_id":null,
         "notification_sent":false,
         "todo_category_id":43043,
         "tasker_id":null,
         "tasker_type":null,
         "private":false,
         "proposal_status_id":null,
         "days_until_due":null,
         "due_at":"2013-07-11T20:00:00Z",
         "created_by_id":1,
         "has_reminder":true,
         "followup_type":null,
         "followup_id":null,
         "group_id":null,
         "history_note_count":0,
         "comment_count":0,
         "completed_at":null,
         "completed_by_id":null,
         "todo_template_step_id":null,
         "process_milestone_id":null,
         "skipped":false,
         "dependent_step_complete":false,
         "completion_notes":null,
         "starred":false,
         "todo_list_id":263,
         "description":"We need the documentation for our API ",
         "position":5,
         "calendar_id":null,
         "state":null,
         "rejection_notes":null,
         "todo_template_id":null,
         "participants":[

         ],
         "reminders":[
            {
               "description":null,
               "deliver_at":null,
               "reminder_type_id":2,
               "sent":null,
               "failed":null,
               "interval":"minutes",
               "time_increment":15,
               "created_at":null,
               "updated_at":null,
               "recurring":null,
               "parent_id":null
            }
         ],
         "comments":[

         ]
      },
   "total_count":1,
}

List of Contact Tasks

Definition

GET http://app.karmacrm.com/api/v2/contacts/#{CONTACT_ID}/todos.json?page={PAGE_NUMBER}

Example Request

curl -G \
https://app.karmacrm.com/api/v2/contacts/8733/todos.json? \
-d api_token=FDGz79n8D2Cz2bjqB7BB \
-d page=1

Example Response

{
  "results": [
    {
      "id": "17",
      "body": "Task",
      "user_id": 1,
      "due_on": null,
      "complete": false,
      "organization_id": 1,
      "created_at": "2013-07-17T12:33:32Z",
      "updated_at": "2013-07-17T12:33:32Z",
      "time": null,
      "lead_process_id": null,
      "notification_sent": false,
      "todo_category_id": null,
      "tasker_id": null,
      "tasker_type": null,
      "private": false,
      "proposal_status_id": null,
      "days_until_due": null,
      "due_at": null,
      "created_by_id": 1,
      "has_reminder": false,
      "followup_type": null,
      "followup_id": null,
      "group_id": null,
      "history_note_count": 0,
      "comment_count": 0,
      "completed_at": null,
      "completed_by_id": null,
      "todo_template_step_id": null,
      "process_milestone_id": null,
      "skipped": false,
      "dependent_step_complete": false,
      "completion_notes": null,
      "starred": false,
      "todo_list_id": null,
      "description": "",
      "position": 10,
      "calendar_id": null,
      "state": null,
      "rejection_notes": null,
      "todo_template_id": null,
      "participants": [
        {
          "id": 120,
          "label": "John Smith",
          "participater_id": "8733",
          "participater_type": "Contact"
        }
      ],
      "reminders": [

      ],
      "comments": [

      ]
    }
  ],
  "total_count": 1
}

List of Company Tasks

Definition

GET http://app.karmacrm.com/api/v2/companies/#{COMPANY_ID}/todos.json?page={PAGE_NUMBER}

Example Request

curl -G \
https://app.karmacrm.com/api/v2/companies/2798/todos.json? \
-d api_token=FDGz79n8D2Cz2bjqB7BB \
-d page=1

Example Response

{
  "results": [
    {
      "id": "18",
      "body": "Task",
      "user_id": 1,
      "due_on": null,
      "complete": false,
      "organization_id": 1,
      "created_at": "2013-07-17T12:49:45Z",
      "updated_at": "2013-07-17T12:49:45Z",
      "time": null,
      "lead_process_id": null,
      "notification_sent": false,
      "todo_category_id": null,
      "tasker_id": null,
      "tasker_type": null,
      "private": false,
      "proposal_status_id": null,
      "days_until_due": null,
      "due_at": null,
      "created_by_id": 1,
      "has_reminder": false,
      "followup_type": null,
      "followup_id": null,
      "group_id": null,
      "history_note_count": 0,
      "comment_count": 0,
      "completed_at": null,
      "completed_by_id": null,
      "todo_template_step_id": null,
      "process_milestone_id": null,
      "skipped": false,
      "dependent_step_complete": false,
      "completion_notes": null,
      "starred": false,
      "todo_list_id": null,
      "description": "",
      "position": 11,
      "calendar_id": null,
      "state": null,
      "rejection_notes": null,
      "todo_template_id": null,
      "participants": [
        {
          "id": 122,
          "label": "1 Two Kids",
          "participater_id": "2798",
          "participater_type": "Company"
        }
      ],
      "reminders": [

      ],
      "comments": [

      ]
    }
  ],
  "total_count": 1
}

List of Deal Tasks

Definition

GET http://app.karmacrm.com/api/v2/deals/#{DEAL_ID}/todos.json?page={PAGE_NUMBER}

Example Request

curl -G https://app.karmacrm.com/api/v2/deals/5/todos.json? \
-d api_token=FDGz79n8D2Cz2bjqB7BB \
-d page=1

Example Response

{
  "results": [
    {
      "id": "19",
      "body": "task",
      "user_id": 1,
      "due_on": null,
      "complete": false,
      "organization_id": 1,
      "created_at": "2013-07-17T13:17:54Z",
      "updated_at": "2013-07-17T13:17:54Z",
      "time": null,
      "lead_process_id": null,
      "notification_sent": false,
      "todo_category_id": null,
      "tasker_id": null,
      "tasker_type": null,
      "private": false,
      "proposal_status_id": null,
      "days_until_due": null,
      "due_at": null,
      "created_by_id": 1,
      "has_reminder": false,
      "followup_type": null,
      "followup_id": null,
      "group_id": null,
      "history_note_count": 0,
      "comment_count": 0,
      "completed_at": null,
      "completed_by_id": null,
      "todo_template_step_id": null,
      "process_milestone_id": null,
      "skipped": false,
      "dependent_step_complete": false,
      "completion_notes": null,
      "starred": false,
      "todo_list_id": null,
      "description": "",
      "position": 12,
      "calendar_id": null,
      "state": null,
      "rejection_notes": null,
      "todo_template_id": null,
      "participants": [
        {
          "id": 124,
          "label": "Meet with my boss",
          "participater_id": "5",
          "participater_type": "Deal"
        }
      ],
      "reminders": [

      ],
      "comments": [

      ]
    }
  ],
  "total_count": 1
}

List of Case Tasks

Definition

GET http://app.karmacrm.com/api/v2/cases/#{CASE_ID}/todos.json?page={PAGE_NUMBER}

Example Request

curl -G https://app.karmacrm.com/api/v2/cases/7/todos.json? \
-d api_token=FDGz79n8D2Cz2bjqB7BB \
-d page=1

Example Response

{
  "results": [
    {
      "id": "20",
      "body": "Task",
      "user_id": 1,
      "due_on": null,
      "complete": false,
      "organization_id": 1,
      "created_at": "2013-07-17T13:29:49Z",
      "updated_at": "2013-07-17T13:29:49Z",
      "time": null,
      "lead_process_id": null,
      "notification_sent": false,
      "todo_category_id": null,
      "tasker_id": null,
      "tasker_type": null,
      "private": false,
      "proposal_status_id": null,
      "days_until_due": null,
      "due_at": null,
      "created_by_id": 1,
      "has_reminder": false,
      "followup_type": null,
      "followup_id": null,
      "group_id": null,
      "history_note_count": 0,
      "comment_count": 0,
      "completed_at": null,
      "completed_by_id": null,
      "todo_template_step_id": null,
      "process_milestone_id": null,
      "skipped": false,
      "dependent_step_complete": false,
      "completion_notes": null,
      "starred": false,
      "todo_list_id": null,
      "description": "",
      "position": 13,
      "calendar_id": null,
      "state": null,
      "rejection_notes": null,
      "todo_template_id": null,
      "participants": [
        {
          "id": 126,
          "label": "Big project",
          "participater_id": "7",
          "participater_type": "Case"
        }
      ],
      "reminders": [

      ],
      "comments": [

      ]
    }
  ],
  "total_count": 1
}

Organization

This represents your account with karmaCRM. Organizations are the entities that house your subscription information, and all your data in karamCRM is scoped by this organization_id.

Arguments
name: string

Creating a New Organization

This method creates a new organization with a free 30 day trial.

Arguments
name: required

Definition

https://app.karmacrm.com/signups/new

Example Request

{
  account: { 
    first_name: 'John',
    last_name: 'Doe',
    email: 'john.doe@gmail.com'
    time_zone: 'Eastern Time (US & Canada)',
    password: 'grapes12345',
    password_confirmation: 'grapes12345'
  },
  organization: {
    name: 'Widgets LLC'
  }
}

Example Response

{
  id: 121311,
  name: 'Widgets LLC',
  subscription_id: 1
  account: {
    id: 232452
    first_name: 'John',
    last_name: 'Doe',
    email: 'john.doe@gmail.com,
    time_zone: 'Eastern Time (US & Canada)',
  },
  user: {
    id: 121411,
    api_token: 'scWnweFX5Gr1RbWsqewf'
    account_id: 232452
  }            
}

History

Creating a New History record

Karma doesn't provide api to create history records directly. To create history record you need to create a Note which should be associated with entity you want to attach it. Creating the note will automatically create a history record.

Arguments
body: required
Note body
contact_type_id: required
values for contact_type_id EMAIL = 1, PHONE = 2, NOTE = 3 (for notes one should use contact_type_id = 3)
date: required
Display date for this note. Example "12/11/2013" (mm/dd/yyyy)
time: optional
Specific time for this note "2:00am" (format XX:YYam/pm, where YY should be 00 or 30)
parent_id: required
ID of parent record
parent_type: required
Type of parent for which note is created. Supported types are 'Contact', 'Company', 'Deal', 'Case'. When you are creating a note for Company you should set parent_id = ID of Company object and parent_type = Company
participants: optional
List of records associated with history, e.g. users, contacts, companies, ...
user_ids: optional
Array of user IDS from current organization that should get notification that note was created
Returns

Returns a note object if the call succeeded.

Definition

POST https://app.karmacrm.com/api/v2/notes.json

Example Request

curl -H "Accept: application/json" \ 
  -H "Content-type: application/json" \
  -X POST https://app.karmacrm.com/api/v2/notes.json?\ 
api_token=FDGz79n8D2Cz2bjqB7BB
  -d '{
    "note"=>{
      "contact_type_id"=>"3",
      "body"=>"test body",
      "date"=>"12/11/2013",
      "time"=>"10:15am",
      "user_ids"=>["12652", "11129"],
      "parent_type"=>"Contact",
      "parent_id"=>"750418",
      "participants"=>[
        {
          "participater_id"=>"750418",
          "participater_type"=>"Contact"
        },
        {
          "participater_id"=>"1978",
          "participater_type"=>"Case"
        },
        {
          "participater_id"=>"37460",
          "participater_type"=>"Deal"
        }
      ]
   }
}'

Example Response

{
  "id":847793,
  "to":null,
  "from":null,
  "bcc":null,
  "cc":null,
  "body":"test body",
  "subject":null,
  "date":null,
  "lead_id":750418,
  "user_id":11129,
  "contact_type_id":3,
  "organization_id":972,
  "created_at":"2013-12-04T11:17:52+04:00",
  "updated_at":"2013-12-04T11:17:52+04:00",
  "from_lead":false,
  "created_by_id":11129,
  "html_email":false,
  "sent_at":null,
  "draft":false,
  "dropbox":false,
  "signature":false,
  "email_template_id":null,
  "asset_count":0,
  "email_filename":null,
  "company_id":null,
  "message_id":null,
  "viewed_at":null,
  "token":null,
  "old_entity_id":null,
  "options":null,
  "note_type":null,
  "email":null,
  "class_name":"Decorators::Note",
  "history":{"id":2526262,
    "history_record_id":750418,
    "history_record_type":"Contact",
    "history_type_id":3,
    "name":"Note",
    "description":null,
    "user_id":11129,
    "organization_id":972,
    "lead_id":null,
    "created_at":"2013-12-04T11:17:52+04:00",
    "updated_at":"2013-12-04T11:17:52+04:00",
    "note_id":847793,
    "company_id":null,
    "external_id":847793,
    "external_type":"Note",
    "private":null,
    "created_by_id":11129,
    "group_id":null,
    "delta":false,
    "read":false,
    "notification":false,
    "parent_id":null,
    "occurred_at":"2013-12-11T11:17:00+04:00",
    "comment_count":0,
    "history_category_id":1,
    "secondary_history_record_id":null,
    "secondary_history_record_type":null,
    "old_entity_id":null,
    "additional_information":{},
    "occurred_at_short":"12/11",
    "occurred_at_date":"12/11/2013",
    "occurred_at_time":"11:17",
    "occurred_at_long":"12/11/2013 at 11:17",
    "class_name":"History",
    "posted_by":"Posted by",
    "box_class":"note",
    "editable":true,
    "list_body":"test body",
    "body":"test body"
  }
}

Deleting a History record

Deletes history record and it's associated note

Definition

DELETE https://app.karmacrm.com/api/v2/histories/{HISTORY_ID}.json

Example Request

curl -X DELETE -G \ https://app.karmacrm.com/api/v2/histories/243130.json \
-d api_token=FDGz79n8D2Cz2bjqB7BB

Retrieving information about specific history record

History record includes information about associated note in the 'external' attribute

Arguments
id: required
ID of history record
history_record_id: required
ID of parent for which history was created.
history_record_type: required
Type of parent for which history is created. Supported types are 'Contact', 'Company', 'Deal', 'Case'.
history_type_id: required
The type of history, available types: UPDATE = 1, DELETE = 2, CREATE = 3, COMPLETE = 4, ASSIGNED = 5, BROADCAST = 6, STATUS_UPDATE = 7
name: required
The history name, for note history it will be always 'Note'
user_id: required
User id who created the history
organization_id: required
Organization id
created_at: required
When history was created
updated_at: required
When history was last updated
external: required
Note attributes which were specified in the 'Creating a New History record' section
participants: optional
List of related contacts, deals, companies, users this history associated with

Definition

GET https://app.karmacrm.com/api/v2/histories/{HISTORY_ID}.json

Example Request

curl -G https://app.karmacrm.com/api/v2/histories/3804605.json \ 
-d api_token=FDGz79n8D2Cz2bjqB7BB

Example Response

{
   "id":"3804605",
   "history_record_id":949509,
   "history_record_type":"Contact",
   "history_type_id":3,
   "name":"Note",
   "description":null,
   "user_id":12793,
   "organization_id":1213,
   "lead_id":null,
   "created_at":"2013-12-12T11:27:24Z",
   "updated_at":"2013-12-12T11:27:24Z",
   "note_id":1471648,
   "company_id":null,
   "external_id":1471648,
   "external_type":"Note",
   "private":null,
   "created_by_id":12793,
   "group_id":null,
   "delta":false,
   "read":false,
   "notification":false,
   "parent_id":null,
   "occurred_at":"2013-12-12T11:27:24Z",
   "comment_count":0,
   "history_category_id":1,
   "secondary_history_record_id":null,
   "secondary_history_record_type":null,
   "old_entity_id":null,
   "additional_information":{

   },
   "external":{
      "id":1471648,
      "label":"Some Note",
      "subject":null,
      "body":"Some Note",
      "contact_type_id":3,
      "assets":[

      ]
   },
   "comments":[

   ],
   "participants":[
      {
         "id":null,
         "participater_id":949509,
         "participater_type":"Contact",
         "label":"JohnyZahidcvc Smith"
      }
   ],
   "_type":"history",
   "_index":"histories_production",
   "_version":1,
   "history_record_label":"JohnyZahidcvc Smith",
   "history_record_path":"contacts/949509",
   "occurred_at_short":"12/12",
   "class_name":"History",
   "posted_by":"Posted by",
   "occurred_at_long":"12/12/2013 at 11:27am",
   "updated_at_formatted":"12/12/2013",
   "box_class":"note",
   "editable":true,
   "list_body":"Some Note",
   "body":"Some Note",
   "attachments":[

   ]
}

Retrieving list of history records for particular entity

Returns list of history records information with full notes info embedded inside it

Definition

GET https://app.karmacrm.com/api/v2/histories.json

Example Request

curl -G https://app.karmacrm.com/api/v2/histories.json \ 
-d api_token=FDGz79n8D2Cz2bjqB7BB \
-d '{"filters"=>{"history_record_type"=>"Contact", \
"history_record_id"=>"750418"}, "per_page"=>"9999", \
"page"=>"1", "result_type"=>"backbone"}'

Example Response

{
   "results":[
      {
         "history_record_label":"Konstantin Gerasimov",
         "history_record_path":"contacts/750418",
         "id":"2526261",
         "history_record_id":750418,
         "history_record_type":"Contact",
         "history_type_id":3,
         "name":"Note",
         "description":null,
         "user_id":11129,
         "organization_id":972,
         "lead_id":null,
         "created_at":"2013-12-04T07:13:11Z",
         "updated_at":"2013-12-04T07:13:11Z",
         "note_id":847792,
         "company_id":null,
         "external_id":847792,
         "external_type":"Note",
         "private":null,
         "created_by_id":11129,
         "group_id":null,
         "delta":false,
         "read":false,
         "notification":false,
         "parent_id":null,
         "occurred_at":"2013-12-11T07:13:00Z",
         "comment_count":0,
         "history_category_id":1,
         "secondary_history_record_id":null,
         "secondary_history_record_type":null,
         "old_entity_id":null,
         "additional_information":{

         },
         "external":{
            "subject":null,
            "contact_type_id":3,
            "label":"test body",
            "comments":[

            ],
            "assets":[

            ]
         },
         "comments":[

         ],
         "participants":[
            {
               "id":252492,
               "label":"Konstantin Gerasimov",
               "participater_id":"750418",
               "participater_type":"Contact"
            },
            {
               "id":252493,
               "label":"Test case",
               "participater_id":"1978",
               "participater_type":"Case"
            },
            {
               "id":252494,
               "label":"Test deal",
               "participater_id":"37460",
               "participater_type":"Deal"
            }
         ],
         "_score":null,
         "_type":"history",
         "_index":"histories_development",
         "_version":null,
         "sort":[
            1386745980000
         ],
         "highlight":null,
         "_explanation":null,
         "history_record":{

         },
         "posted_by":"Posted by",
         "occurred_at_date":"12/11/2013",
         "occurred_at_time":"11:13",
         "occurred_at_long":"12/11/2013 at 11:13",
         "occurred_at_medium":"12/11/13",
         "occurred_at_short":"12/11",
         "box_class":"note",
         "external_path":"notes/847792",
         "history_type_name":"Created",
         "editable":true,
         "list_body":"test body",
         "body":"test body",
         "class_name":"History"
      }
   ],
   "total_count":3,
   "filter":"history record type 'Contact' history record id '750418' "
}

Updating history record

Updates particular history record and it's associated note. Note's body is located in the 'external' attribute

Arguments
external: required
note attributes

Definition

PUT https://app.karmacrm.com/api/v2/histories/{HISTORY_ID}.json

Example Request

curl -H "Accept: application/json" \
-H "Content-type: application/json" \
-X PUT https://app.karmacrm.com/api/v2/histories/2526261.json?\
api_token=FDGz79n8D2Cz2bjqB7BB \
-d '{
  "history": {
    "external": { 
      "body": "test body", 
      "date": "12/10/2013", 
      "time": "11:14",
      "contact_type_id": "3"
    }
  }
}'

Assets

Uploading a New File

Creates a new asset object.

Returns

Returns a case object if the call succeeded.

Definition

POST https://app.karmacrm.com/api/v2/assets

Example Request

curl -i -F asset[data]=@path_to_local_file \
https://app.karmacrm.com/api/v2/assets?\
api_token=FDGz79n8D2Cz2bjqB7BB

Example Response

{
  "id":350766,
  "name":null,
  "description":null,
  "user_id":19586,
  "organization_id":972,
  "data_file_name":"cat.jpg",
  "data_content_type":"image/jpeg",
  "data_file_size":33703,
  "data_updated_at":null,
  "attachable_type":null,
  "attachable_id":null,
  "created_at":"2014-12-15T10:37:47Z",
  "updated_at":"2014-12-15T10:37:47Z",
  "data_processed":false,
  "asset_category_id":null,
  "cached_tag_list":null,
  "private":false,
  "group_id":null,
  "created_by_id":19586,
  "delta":false,
  "s3_key":null,
  "uuid":null,
  "cached_preview":null,
  "old_entity_id":null
}