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