Introduction
Welcome to the KarmaCRM API!
Authentication
Sign in
curl "https://app.karmacrm.com/accounts/sign_in.json" \
-X POST \
-H "Content-Type: application/json" \
-d '{"account":{"email":"user@example.com","password":"xyz"}}'
Successful sign in response:
{
"activity_churn_started_at": null,
"activity_churn_stopped_at": null,
"avatar": {
"url": null,
"thumb": {
"url": null
},
"medium": {
"url": null
},
"large": {
"url": null
}
},
"business_phone": "555-1212",
"clicky_token": null,
"created_at": "2019-03-11T21:48:46Z",
"current_user_id": 4,
"distinct_id": "52WzU7kkugXcx85DbHtUSeh17LKmf3cfGFNADtzhUX7djXmQxzg4fG4AB9PWVS1vFo4",
"email": "john@example.com",
"email_type": null,
"first_name": "John",
"id": 4,
"last_name": "Smith",
"last_request_at": null,
"locale": "en",
"per_page": 10,
"phone": null,
"phone_carrier": null,
"settings": {
"date_format": "mm/dd/yy",
"default_currency": "USD",
"phone_number_app": "skype",
"phone_number_code": null
},
"support_agent_id": 10794,
"time_zone": null,
"unread_product_updates": null,
"updated_at": "2019-03-27T19:33:18Z",
"use_24h_time": false,
"version": 1,
"current_organization_id": 2,
"beta": false,
"api_token": "oGscoGFsdS54mProUdDz",
"current_user_role_name": "owner",
"current_user_role_type": null,
"current_user_objective": null,
"current_user_dropbox_id": 4832250,
"current_user_mixpanel_person_id": "yq4RvpuQW6SHoHwGa2AEz6YY7fAnQUdrfEMz96vDzkqdb5s5x_TJsx6qdk6Zg8ipv3k"
}
Unsuccessful sign in response:
{
"error": "Invalid email or password."
}
This endpoint retrieves all contacts.
HTTP Request
POST https://app.karmacrm.com/accounts/sign_in.json
Request Payload
| Parameter | Description |
|---|---|
| account[email] | User's email |
| account[password] | User's password |
Authorizations
Get all authorizations
curl "https://app.karmacrm.com/api/v2/settings/integrations.json?api_token=oGscoGFsdS54mProUdDz"
Successful response
[
{
"last_synced_at_formatted": "Monday Apr, 22nd at 9:06am",
"id": 1,
"user_id": 4,
"provider": "nylas_mailman",
"uid": "khulani@karmacrm.com",
"created_at": "2019-03-12T14:21:46-06:00",
"updated_at": "2019-05-13T10:52:47-06:00",
"token": "mJKFXxe6PXexkVM2fse5FHu3JrVK9r",
"secret": null,
"account": "khulani@karmacrm.com",
"organization_id": 2,
"settings": {
"send_copy": null,
"signature": null,
"open_tracking": true,
"click_tracking": null,
"incoming_emails_enabled": true,
"outgoing_emails_enabled": true,
"import_past_emails": false,
"incoming_emails_notifications_enabled": null,
"privacy": "private"
},
"active": true,
"refreshing": false,
"last_synced_at": "2019-04-22T09:06:56-06:00",
"error_message": "{\"incoming\":null,\"outgoing\":null}",
"refresh_token": "rwlesmklasdwapp6zizx1fo9",
"old_entity_id": null,
"position": 0,
"error_code": null,
"domain": null,
"private": null,
"contextio_account_id": "7642p8a4ciwbfs5tl0qkd7dmk",
"contextio_source_label": null,
"state": null,
"timestamp": null
},
{
"last_synced_at_formatted": "Tuesday Mar, 19th at 11:51am",
"id": 2,
"user_id": 4,
"provider": "google_contacts",
"uid": "109333742401691400392",
"created_at": "2019-03-19T10:37:50-06:00",
"updated_at": "2019-03-19T11:51:28-06:00",
"token": "ya67.GlvRBqzYwxjnncMqf3PB_6FPd3xsdXlfnoWRvwrKhjqSUUhiaIvY1bLhiQJIxJ9EI2yufMUOZeFY7DciVq89TiAWaecZtUHKmZHBZpq8zTR3Yj2sHSDJGxkTtq7_",
"secret": null,
"account": "khulani@karmacrm.com",
"organization_id": 2,
"settings": {
"google_contact_groups": [
{
"href": "http://www.google.com/m8/feeds/groups/khulani%40karmacrm.com/base/6",
"title": "System Group: My Contacts",
"content": "System Group: My Contacts"
},
{
"href": "http://www.google.com/m8/feeds/groups/khulani%40karmacrm.com/base/d",
"title": "System Group: Friends",
"content": "System Group: Friends"
},
{
"href": "http://www.google.com/m8/feeds/groups/khulani%40karmacrm.com/base/e",
"title": "System Group: Family",
"content": "System Group: Family"
},
{
"href": "http://www.google.com/m8/feeds/groups/khulani%40karmacrm.com/base/f",
"title": "System Group: Coworkers",
"content": "System Group: Coworkers"
}
],
"selected_google_contact_groups": [
"http://www.google.com/m8/feeds/groups/khulani%40karmacrm.com/base/6"
],
"sync_method": "import"
},
"active": true,
"refreshing": false,
"last_synced_at": "2019-03-19T11:51:26-06:00",
"error_message": null,
"refresh_token": "1/JgVweYDDFWs5biaukM4ndi0vK4V_mfvzXbyEa5RjTpjJuryp3KoLhhuEWSSF_pxz",
"old_entity_id": null,
"position": 0,
"error_code": null,
"domain": null,
"private": null,
"contextio_account_id": null,
"contextio_source_label": null,
"state": null,
"timestamp": null
},
{
"id": 3,
"user_id": 4,
"provider": "sparkpost",
"uid": null,
"created_at": "2019-04-08T15:53:09-06:00",
"updated_at": "2019-04-08T15:53:09-06:00",
"token": null,
"secret": null,
"account": null,
"organization_id": 2,
"settings": null,
"active": true,
"refreshing": false,
"last_synced_at": null,
"error_message": null,
"refresh_token": null,
"old_entity_id": null,
"position": 0,
"error_code": null,
"domain": null,
"private": null,
"contextio_account_id": null,
"contextio_source_label": null,
"state": null,
"timestamp": null
},
{
"id": 6,
"user_id": 4,
"provider": "mailchimp",
"uid": "14fe08de6b94402fef9b9ecdc",
"created_at": "2019-04-25T07:13:31-06:00",
"updated_at": "2019-04-25T07:13:31-06:00",
"token": "748340185da250c1021661bc0a6147ac",
"secret": null,
"account": "khulani@karmacrm.com",
"organization_id": 2,
"settings": {
"api_endpoint": "https://us20.api.mailchimp.com"
},
"active": true,
"refreshing": false,
"last_synced_at": null,
"error_message": null,
"refresh_token": null,
"old_entity_id": null,
"position": 0,
"error_code": null,
"domain": null,
"private": null,
"contextio_account_id": null,
"contextio_source_label": null,
"state": null,
"timestamp": null
}
]
This endpoint gets authorizations.
HTTP Request
GET https://app.karmacrm.com/api/v2/settings/integrations.json
Query Parameters
| Parameter | Description |
|---|---|
| api_token | The token to authenticate request |
Contacts
Get All Contacts
curl "https://app.karmacrm.com/api/v3/contacts?api_token=oGscoGFsdS54mProUdDz&page=3&filters%5Bcontact_stage_id%5D=13&sorts%5Bfirst_name%5D=asc" \
-H "Content-Type: application/json"
The above command returns JSON structured like this:
{
"results":[
{
"id":25,
"first_name":"John",
"last_name":"Smith",
"avatar_url":"/assets/person_thumb.png",
"department":"Development",
"referral_source_id":8,
"user_id":5,
"created_by_id":4,
"private":true,
"position":"developer",
"background":"Good developer with 3+ years of experience",
"contact_status_id":13,
"contact_stage_id":13,
"tags":["development","usa"],
"company":{
"id":5,
"name":"Company A"
},
"created_at":"2019-03-28T02:45:39Z",
"updated_at":"2019-03-28T05:07:19Z",
"emails":[
{
"id":12,
"email":"john.smith@example.com",
"secondary_email_type_id":2
}
],
"websites":[
{
"id":4,
"url":"example.com",
"secondary_website_type_id":1
}
],
"phone_numbers":[
{
"id":6,
"number":"+7 902 4321 2123",
"phone_number_type_id":2
}
],
"addresses":[
{
"id":4,
"country":"USA",
"state":"Illinois",
"city":"Chicago",
"street":"South St",
"postal_code":"60667"
}
],
"social_accounts":[
{
"id":3,
"name":"john_smith",
"social_account_type_id":1
}
],
"field_values":[
{
"id":7,
"field_id":1,
"field_type_id":5,
"value":"value for custom text field"
},
{
"id":13,
"field_id":4,
"field_type_id":3,
"field_parent_id":2,
"value":"4"
}
],
"permissions":[
{
"id":1,
"permission":1,
"accessor_id":5,
"accessor_type":"User"
},
{
"id":2,
"permission":1,
"accessor_id":4,
"accessor_type":"User"
}
]
}
],
"total_count":21
}
This endpoint retrieves all contacts.
HTTP Request
GET https://app.karmacrm.com/api/v3/contacts.json
Query Parameters
| Parameter | Description |
|---|---|
| page | Gets a specific page of contacts |
| api_token | The token to authenticate request |
| filters[user_id] | Filters contacts by assigned user id |
| filters[contact_status_id] | Filters contacts by status id |
| filters[contact_stage_id] | Filters contacts by stage id |
| filters[tag_list] | Filters contacts by tag list (i.e. eastern,night) |
sorts[<FIELD NAME>] |
Sort contacts on a specified field (i.e. first_name)in ascending asc or descending desc order |
Get a Specific Contact
curl "https://app.karmacrm.com/api/v3/contacts/25.json?api_token=oGscoGFsdS54mProUdDz" \
-H "Content-Type: application/json"
Example Response:
{
"id":25,
"first_name":"John",
"last_name":"Smith",
"background":"Good developer with 3+ years of experience",
"position":"developer",
"avatar_url":"/assets/person_thumb.png",
"department":"Development",
"organization_id":2,
"referral_source_id":8,
"user_id":5,
"created_by_id":4,
"private":true,
"contact_status_id":13,
"contact_stage_id":13,
"tags":["development","usa"],
"company":{
"id":5,
"name":"Company A"
},
"created_at":"2019-03-28T02:45:39Z",
"updated_at":"2019-03-28T05:07:19Z",
"bucket_ids":[],
"emails":[
{
"id":12,
"email":"john.smith@example.com",
"label":"home",
"email_type_id":2
}
],
"websites":[
{
"id":4,
"url":"example.com",
"label":"work",
"website_type_id":1
}
],
"phone_numbers":[
{
"id":6,
"number":"+7 902 4321 2123",
"phone_number_type_id":2,
"label":"mobile"
}
],
"addresses":[
{
"id":4,
"label":"home",
"country":"USA",
"city":"Chicago",
"street":"South St",
"state":"Illinois",
"postal_code":"60667",
"address_type_id":2
}
],
"social_accounts":[
{
"id":3,
"name":"john_smith",
"social_account_type_id":1
}
],
"field_values":[
{
"id":7,
"field_id":1,
"field_type_id":5,
"value":"Updated text curl2"
},
{
"id":13,
"field_id":4,
"field_type_id":3,
"field_parent_id":2,
"value":"4"
}
],
"permissions":[
{
"id":1,
"permission":1,
"accessor_id":5,
"accessor_type":"User"
},
{
"id":2,
"permission":1,
"accessor_id":4,
"accessor_type":"User"
}
],
"relationships":[],
"important_dates":[],
"attachments": [
{
"id": 9,
"asset_id": 4,
"data_file_name": "document.pdf",
"data_content_type": "application/pdf",
"private": false,
"created_at_long": "03/12/2019 at 9:52pm",
"created_at": "2019-03-12T21:52:03Z",
"class_name": "Attachment"
},
{
"id": 13,
"asset_id": 12,
"data_file_name": "photo.JPG",
"data_content_type": "image/jpeg",
"private": false,
"created_at_long": "05/28/2019 at 9:30pm",
"created_at": "2019-05-28T21:30:10Z",
"class_name": "Attachment"
}
]
}
This endpoint retrieves a specific contact.
HTTP Request
GET https://app.karmacrm.com/api/v3/contacts/<ID>.json
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the contact to retrieve |
| api_token | The token to authenticate request |
Create a Contact
curl "https://app.karmacrm.com/api/v3/contacts.json?api_token=oGscoGFsdS54mProUdDz" \
-X POST \
-H "Content-Type: application/json" \
-d '{"contact":{"first_name":"John","last_name":"Smith","position":"developer","background":"Good developer with 3+ years of experience","contact_stage_id":13,"contact_status_id":13,"referral_source_id":8,"department":"Development","industry_id":null,"company":{"name":"Company A"},"tags":["development","usa"],"addresses":[{"street":"South St","city":"Chicago","state":"Illinois","country":"USA","postal_code":"60667","address_type_id":2}],"phone_numbers":[{"number":"+7 902 4321 2123","phone_number_type_id":2}],"emails":[{"email":"john.smith@example.com","email_type_id":2}],"social_accounts":[{"name":"john_smith","social_account_type_id":1}],"websites":[{"url":"example.com","website_type_id":1},{"url":"another.com","label":"New Label"}],"field_values":[{"field_id":1,"value":"Updated text"},{"field_parent_id":2,"field_id":4}],"permissions":[{"accessor_id":5,"accessor_type":"User","permission":1}]}}'
Successful contact creation response:
{
"id": 25,
"first_name": "John",
"last_name": "Smith",
"background": "Good developer with 3+ years of experience",
"position": "developer",
"private_notes": null,
"department": "Development",
"organization_id": 2,
"referral_source_id": 8,
"user_id": 4,
"created_by_id": 4,
"industry_id": null,
"private": true,
"contact_status_id": 13,
"contact_stage_id": 13,
"tags": ["development", "usa"],
"company": {
"id": 5,
"name": "Company A"
},
"created_at": "2019-03-28T02: 45: 39Z",
"updated_at": "2019-03-28T02: 45: 39Z",
"emails": [
{
"id": 12,
"email": "john.smith@example.com",
"email_type_id": 2
}
],
"websites": [
{
"id": 4,
"url": "example.com",
"website_type_id": 1
}
],
"phone_numbers": [
{
"id": 6,
"number": "+7 902 4321 2123",
"phone_number_type_id": 2
}
],
"addresses": [
{
"id": 4,
"country": "USA",
"city": "Chicago",
"street": "South St",
"street_2": null,
"postal_code": "60667",
"address_type_id": 2
}
],
"social_accounts": [
{
"id": 3,
"name": "john_smith",
"social_account_type_id": 1
}
],
"field_values": [
{
"id": 7,
"field_id": 1,
"field_type_id": 5,
"field_parent_id": null,
"value": "Updated text"
},
{
"id": 8,
"field_id": 4,
"field_type_id": 3,
"field_parent_id": 2,
"value": 4
}
],
"bucket_ids": [],
"permissions": [
{
"id": 1,
"permission": 1,
"accessor_id": 5,
"accessor_type": "User"
}
]
}
Unsuccessful contact creation response:
{
"message": "Validation error",
"errors": {
"contact_status_id": [
"given contact status doesn't exist in organization"
]
}
}
HTTP Request
POST https://app.karmacrm.com/api/v3/contacts.json
URL Parameters
| Parameter | Description |
|---|---|
| api_token | The token to authenticate request |
Request Payload
| Parameter | Description |
|---|---|
| contact[first_name] | Contact's first name |
| contact[last_name] | Contact's last name |
| contact[position] | Contact's title |
| contact[background] | Contact's background information |
| contact[contact_stage_id] | ID for contact's stage |
| contact[contact_status_id] | ID for contact's status |
| contact[referral_source_id] | ID for contact's referral source |
| contact[user_id] | ID for contact's assigned user |
| contact[department] | Contact's department |
| contact[industry_id] | ID for contact's industry |
| contact[company] | Contact's company object i.e. {"name":"Company A"} |
| contact[tags] | array of contact's tags i.e. ["development","usa"] |
| contact[addresses] | array of contact's addresses, i.e. {"street":"South St","city":"Chicago","state":"Illinois","country":"USA","postal_code":"60667","address_type_id": 2,"label": "New Custom Label", (optional: adds custom label)} |
| contact[phone_numbers] | array of contact's phone_numbers, i.e. (with optional custom label){"number":"+7 902 4321 2123","phone_number_type_id":2,"label":"New Custom Label"} |
| contact[emails] | array of contact's emails, i.e. (with optional custom label){"email":"john.smith@example.com","email_type_id":2,"label":"New Custom Label"} |
| contact[social_accounts] | array of contact's social accounts, i.e.{"name":"john_smith","social_account_type_id":1} |
| contact[websites] | array of contact's websites, i.e. (with optional custom label){"url":"example.com","website_type_id":1,"label":"New Custom Label"} |
| contact[field_values] | array of contact's custom field values, i.e {"field_id":1,"value":"custom info"} {"value":"5","field_id":5,"field_parent_id":2} (with parent field) |
| contact[permissions] | array of permission granting access to contact's info i.e.{"accessor_id": 4,"accessor_type": "User","permission": 1} |
Update a Contact
curl "https://app.karmacrm.com/api/v3/contacts/24.json?api_token=oGscoGFsdS54mProUdDz" \
-X PUT \
-H "Content-Type: application/json" \
-d '{"contact":{"first_name":"John","last_name":"Smith","background":"Good developer with 3+ years of experience","position":"developer","private_notes":null,"department":"Development","referral_source_id":8,"user_id":4,"industry_id":null,"private":true,"contact_status_id":13,"contact_stage_id":13,"tags":["development","usa"],"company":{"id":5,"name":"Company A"},"emails":[{"id":12,"email":"john.smith@example.com","email_type_id":2}],"websites":[{"id":4,"url":"example.com","website_type_id":1}],"phone_numbers":[{"id":6,"number":"+7 902 4321 2123","phone_number_type_id":2}],"addresses":[{"id":4,"country":"USA","city":"Chicago","street":"South St","postal_code":"60667","address_type_id":2}],"social_accounts":[{"id":3,"name":"john_smith","social_account_type_id":1}],"field_values":[{"id":7,"field_id":1,"value":"Updated text curl2"},{"id":13,"field_id":4,"field_parent_id":2,"value":"4"}],"permissions":[{"id":1,"permission":1,"accessor_id":5,"accessor_type":"User"}]}}'
This endpoint updates a specific contact.
HTTP Request
PUT https://app.karmacrm.com/api/v3/contacts/<ID>.json
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the contact to update |
| api_token | The token to authenticate request |
Request Payload
| Parameter | Description |
|---|---|
| contact[first_name] | Contact's first name |
| contact[last_name] | Contact's last name |
| contact[position] | Contact's title |
| contact[background] | Contact's background information |
| contact[private_notes] | Contact's private notes |
| contact[contact_stage_id] | ID for contact's stage |
| contact[contact_status_id] | ID for contact's status |
| contact[referral_source_id] | ID for contact's referral source |
| contact[user_id] | ID for contact's user |
| contact[department] | Contact's department |
| contact[industry_id] | ID for contact's industry |
| contact[company] | Contact's company object i.e. {"id":5,"name":"Company A"} |
| contact[tags] | array of contact's tags i.e. ["development","usa"] |
| contact[addresses] | array of contact's addresses i.e. {"id":4,"street":"South St","city":"Chicago","state":"Illinois","country":"USA","postal_code":"60667","address_type_id": 2,"label": "New Custom Label", (optional: adds custom label)"_destroy": true (optional: deletes address)} |
| contact[phone_numbers] | array of contact's phone_numbers, i.e. update: {"id":6,"number":"+7 902 4321 2123","phone_number_type_id":2}add new: {"number":"+7 902 4321 2123","phone_number_type_id":2,"label":"New Custom Label"}delete: {"id":7,"number":"+7 902 4321 2123","phone_number_type_id":2, "_destroy":true} |
| contact[emails] | array of contact's emails, i.e. update: {"id":12,"email":"update.email@example.com","email_type_id":2}add new: {"email":"add.email @example.com","email_type_id":2,"label":"New Label"}delete: {"id":14,"email":"delete.email@example.com","email_type_id":2,"_destroy":true} |
| contact[social_accounts] | array of contact's social accounts, i.e. update: {"id":3,"name":"update name","social_account_type_id":1}add new: {name":"new name","social_account_type_id":3}delete: {"id":3,"name":"delete name","social_account_type_id":1,"_delete":true} |
| contact[websites] | array of contact's websites, i.e. update: {"id":4,"url":"update.com","website_type_id":2}add new: {"url":"addnew.com","website_type_id":1, 'New Label'}delete: {"id":6,"url":"delete.com","website_type_id":1, "_destroy":true} |
| contact[field_values] | array of contact's custom field values, i.e update: {"id":7,"field_id":1,"value":"update value for text field"}add/check new (checkbox choice): {"value":"5","field_id":5,"field_parent_id":2} |
| contact[permissions] | array of permission granting access to contact's info i.e.{"id":1,"accessor_id": 4,"accessor_type": "User","permission": 1"_destroy": true (optional: deletes permission)} |
Return Codes
| Code | Description |
|---|---|
| 204 | No content |
Delete a Contact
curl "https://app.karmacrm.com/api/v3/contacts/27.json?api_token=oGscoGFsdS54mProUdDz"
-X DELETE \
-H "Content-Type: application/json"
This endpoint deletes a specific contact.
HTTP Request
DELETE https://app.karmacrm.com/api/v3/contacts/<ID>.json
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the contact to delete |
| api_token | The token to authenticate request |
Return Codes
| Code | Description |
|---|---|
| 204 | No content |
Companies
Get All Companies
curl "https://app.karmacrm.com/api/v3/companies.json?api_token=oGscoGFsdS54mProUdDz&page=3&filters%5Bcontact_stage_id%5D=13&sorts%5Bfirst_name%5D=asc" \
-H "Content-Type: application/json"
The above command returns JSON structured like this:
{
"results": [
{
"id": 10,
"name": "my company name",
"background": "my background",
"referral_source_id": 9,
"user_id": 4,
"created_by_id": 4,
"private": false,
"avatar_url": "/assets/company_thumb.jpg",
"tags": [
"local",
"new"
],
"created_at": "2019-06-18T16:18:03Z",
"updated_at": "2019-06-18T16:18:03Z",
"emails": [
{
"id": 31,
"email": "my.company@email.com",
"secondary_email_type_id": 1
},
{
"id": 32,
"email": "my.company2@email.com",
"secondary_email_type_id": 1
}
],
"websites": [
{
"id": 11,
"url": "mycompany.com",
"secondary_website_type_id": 2
},
{
"id": 12,
"url": "mycompanywork.com",
"secondary_website_type_id": 1
}
],
"phone_numbers": [
{
"id": 10,
"number": "123-456-7890",
"phone_number_type_id": 1
},
{
"id": 11,
"number": "321-654-0987",
"phone_number_type_id": 1
}
],
"addresses": [
{
"id": 9,
"country": "US",
"state": "ST",
"city": "City",
"street": "123 A St",
"postal_code": "12345"
}
],
"social_accounts": [
{
"id": 4,
"name": "mycompany",
"social_account_type_id": 1
},
{
"id": 5,
"name": "mycompany",
"social_account_type_id": 2
}
]
}
],
"total_count": 1
}
This endpoint retrieves all companies.
HTTP Request
GET https://app.karmacrm.com/api/v3/companies.json
Query Parameters
| Parameter | Description |
|---|---|
| page | Gets a specific page of companies |
| api_token | The token to authenticate request |
Get a Specific Company
curl "https://app.karmacrm.com/api/v3/companies/10.json?api_token=oGscoGFsdS54mProUdDz" \
-H "Content-Type: application/json"
Example Response:
{
"id": 10,
"name": "my company name",
"background": "my background",
"avatar_url": "/assets/company_thumb.jpg",
"organization_id": 2,
"referral_source_id": 9,
"user_id": 4,
"created_by_id": 4,
"private": false,
"tags": [
"local",
"new"
],
"created_at": "2019-06-18T16:18:03Z",
"updated_at": "2019-06-18T16:18:03Z",
"emails": [
{
"id": 31,
"email": "my.company@email.com",
"position": 0,
"email_type_id": 1
},
{
"id": 32,
"email": "my.company2@email.com",
"position": 1,
"email_type_id": 1
}
],
"websites": [
{
"id": 11,
"url": "mycompany.com",
"position": 0,
"website_type_id": 2
},
{
"id": 12,
"url": "mycompanywork.com",
"position": 1,
"website_type_id": 1
}
],
"phone_numbers": [
{
"id": 10,
"number": "123-456-7890",
"phone_number_type_id": 1,
"position": 0,
"label": "work"
},
{
"id": 11,
"number": "321-654-0987",
"phone_number_type_id": 1,
"position": 1,
"label": "school"
}
],
"addresses": [
{
"id": 9,
"country": "US",
"city": "City",
"street": "123 A St",
"postal_code": "12345",
"position": 1811,
"label": "work",
"address_type_id": 1
}
],
"social_accounts": [
{
"id": 4,
"name": "mycompany",
"social_account_type_id": 1,
"position": 0
},
{
"id": 5,
"name": "mycompany",
"social_account_type_id": 2,
"position": 1
}
],
"field_values": [],
"permissions": [],
"relationships": []
}
This endpoint retrieves a specific company.
HTTP Request
GET https://app.karmacrm.com/api/v3/companies/<ID>.json
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the company to retrieve |
| api_token | The token to authenticate request |
Create a Company
curl "https://app.karmacrm.com/api/v3/companies.json?api_token=oGscoGFsdS54mProUdDz" \
-X POST \
-H "Content-Type: application/json" \
-d '{"company":{"name":"My Company Name","background":"My Company Background","tags":["local","support"],"referral_source_id":7,"user_id":4,"emails":[{"email":"email@mycompany.com","label":"work","email_type_id":1,"position":0},{"email":"email2@mycompany.com","label":"support","email_type_id":1,"position":1}],"social_accounts":[{"name":"mycompany","social_account_type_id":"1","position":0},{"name":"mycompany","social_account_type_id":"2","position":1}],"phone_numbers":[{"number":"123-456-7890","label":"work","phone_number_type_id":1,"position":0},{"number":"321-654-0987","label":"mobile","phone_number_type_id":2,"position":1}],"addresses":[{"street":"123 A St.","city":"City","state":"ST","postal_code":"12345","country":"US","label":"work","address_type_id":1,"position":3002},{"street":"456 B St.","city":"City","state":"ST","postal_code":"12345","country":"","label":"support","address_type_id":3,"position":3008}],"websites":[{"url":"mycompanywebsite.com","label":"work","website_type_id":1,"position":0},{"url":"mycompanysupportwebsite.com","label":"support","website_type_id":1,"position":1}],"permissions":[{"accessor_id":"4","accessor_type":"User","permission":"1"},{"accessor_id":"5","accessor_type":"User","permission":"0"}],"private":true,"notify_user":false}}'
Successful company creation response:
{
"id":13,
"name":"My Company Name",
"background":"My Company Background",
"avatar_file_name":null,
"private_notes":null,
"organization_id":2,
"referral_source_id":7,
"user_id":4,
"created_by_id":4,
"industry_id":null,
"private":true,
"tags":["local","support"],
"created_at":"2019-06-19T14:28:49Z",
"updated_at":"2019-06-19T14:28:49Z",
"emails":[
{
"id":34,
"email":"email@mycompany.com",
"email_type_id":1
},
{
"id":35,
"email":"email2@mycompany.com",
"email_type_id":1
}
],
"websites":[
{
"id":16,
"url":"mycompanywebsite.com",
"website_type_id":1
},
{
"id":17,
"url":"mycompanysupportwebsite.com",
"website_type_id":1
}
],
"phone_numbers":[
{
"id":13,
"number":"123-456-7890",
"phone_number_type_id":1
},
{
"id":14,
"number":"321-654-0987",
"phone_number_type_id":2
}
],
"addresses":[
{
"id":12,
"country":"US",
"city":"City",
"street":"123 A St.",
"street_2":null,
"postal_code":"12345",
"address_type_id":1
},
{
"id":13,
"country":"",
"city":"City",
"street":"456 B St.",
"street_2":null,
"postal_code":"12345",
"address_type_id":3
}
],
"social_accounts":[
{
"id":7,
"name":"mycompany",
"social_account_type_id":1
},
{
"id":8,
"name":"mycompany",
"social_account_type_id":2
}
],
"field_values":[],
"permissions":[
{
"id":4,
"permission":1,
"accessor_id":4,
"accessor_type":"User"
},
{
"id":5,
"permission":0,
"accessor_id":5,
"accessor_type":"User"
}
]
}
HTTP Request
POST https://app.karmacrm.com/api/v3/companies.json
URL Parameters
| Parameter | Description |
|---|---|
| api_token | The token to authenticate request |
Request Payload
| Parameter | Description |
|---|---|
| company[name] | Company's name |
| company[background] | Company's background info |
| company[tags] | array of company's tags i.e. ["development","usa"] |
| company[referral_source_id] | ID of company's referral source |
| company[user_id] | ID for company's assigned user |
| company[addresses] | array of company's addresses, i.e. {"street":"South St","city":"Chicago","state":"Illinois","country":"USA","postal_code":"60667","address_type_id": 2,"label": "New Custom Label","position": 0, (optional: adds custom label)} |
| company[phone_numbers] | array of company's phone_numbers, i.e. (with optional custom label){"number":"+7 902 4321 2123","phone_number_type_id":2,"label":"New Custom Label","position":0} |
| company[emails] | array of company's emails, i.e. (with optional custom label){"email":"john.smith@example.com","email_type_id":2,"label":"New Custom Label","position":0} |
| company[social_accounts] | array of company's social accounts, i.e.{"name":"john_smith","social_account_type_id":1,"position":0} |
| company[websites] | array of company's websites, i.e. (with optional custom label){"url":"example.com","website_type_id":1,"label":"New Custom Label","position":0} |
| company[field_values] | array of company's custom field values, i.e {"field_id":1,"value":"custom info"} {"value":"5","field_id":5,"field_parent_id":2} (with parent field) |
| company[permissions] | array of permission granting access to company's info i.e.{"accessor_id": 4,"accessor_type": "User","permission": 1} |
| company[private] | boolean value for whether company permissions is private |
Update a Company
curl "https://app.karmacrm.com/api/v3/companies/13.json?api_token=oGscoGFsdS54mProUdDz" \
-X PUT \
-H "Content-Type: application/json" \
-d '{"id":13,"company":{"name":"My Company Name","background":"My Company Background","tags":["local","support"],"referral_source_id":7,"user_id":4,"emails":[{"id":34,"email":"email@mycompany.com","label":"work","email_type_id":1,"_destroy":false,"position":0},{"id":35,"email":"email2@mycompany.com","label":"support","email_type_id":1,"_destroy":false,"position":1}],"social_accounts":[{"id":7,"name":"mycompany","social_account_type_id":"1","_destroy":false,"position":0},{"id":8,"name":"mycompany","social_account_type_id":"2","_destroy":false,"position":1}],"phone_numbers":[{"id":13,"number":"123-456-7890","label":"work","phone_number_type_id":1,"_destroy":false,"position":0},{"id":14,"number":"321-654-0987","label":"mobile","phone_number_type_id":2,"_destroy":false,"position":1}],"addresses":[{"id":12,"street":"123 A St.","city":"City","state":"ST","postal_code":"12345","country":"US","label":"work","address_type_id":1,"_destroy":false,"position":1152},{"id":13,"street":"456 B St.","city":"City","state":"ST","postal_code":"12345","country":"","label":"support","address_type_id":3,"_destroy":false,"position":1158}],"websites":[{"id":16,"url":"mycompanywebsite.com","label":"work","website_type_id":1,"_destroy":false,"position":0},{"id":17,"url":"mycompanysupportwebsite.com","label":"support","website_type_id":1,"_destroy":false,"position":1}],"permissions":[{"id":4,"accessor_id":4,"accessor_type":"User","permission":"1"},{"id":5,"accessor_id":5,"accessor_type":"User","permission":"0"}],"private":true,"field_values":[{"value":"custom text field value","field_id":52}],"notify_user":false}}'
This endpoint updates a specific company.
HTTP Request
PUT https://app.karmacrm.com/api/v3/companies/<ID>.json
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the company to update |
| api_token | The token to authenticate request |
Request Payload
| Parameter | Description |
|---|---|
| company[name] | Company's name |
| company[background] | Company's background info |
| company[tags] | array of company's tags i.e. ["development","usa"] |
| company[referral_source_id] | ID of company's referral source |
| company[user_id] | ID for company's assigned user |
| company[addresses] | array of company's addresses i.e. {"id":4,"street":"South St","city":"Chicago","state":"Illinois","country":"USA","postal_code":"60667","address_type_id": 2,"label": "New Custom Label", (optional: adds custom label)"_destroy": true (optional: deletes address)} |
| company[phone_numbers] | array of company's phone_numbers, i.e. update: {"id":6,"number":"+7 902 4321 2123","phone_number_type_id":2}add new: {"number":"+7 902 4321 2123","phone_number_type_id":2,"label":"New Custom Label"}delete: {"id":7,"number":"+7 902 4321 2123","phone_number_type_id":2, "_destroy":true} |
| company[emails] | array of company's emails, i.e. update: {"id":12,"email":"update.email@example.com","email_type_id":2}add new: {"email":"add.email @example.com","email_type_id":2,"label":"New Label"}delete: {"id":14,"email":"delete.email@example.com","email_type_id":2,"_destroy":true} |
| company[social_accounts] | array of company's social accounts, i.e. update: {"id":3,"name":"update name","social_account_type_id":1}add new: {name":"new name","social_account_type_id":3}delete: {"id":3,"name":"delete name","social_account_type_id":1,"_delete":true} |
| company[websites] | array of company's websites, i.e. update: {"id":4,"url":"update.com","website_type_id":2}add new: {"url":"addnew.com","website_type_id":1, 'New Label'}delete: {"id":6,"url":"delete.com","website_type_id":1, "_destroy":true} |
| company[field_values] | array of company's custom field values, i.e update: {"id":7,"field_id":1,"value":"update value for text field"}add/check new (checkbox choice): {"value":"5","field_id":5,"field_parent_id":2} |
| company[permissions] | array of permission granting access to company's info i.e.{"id":1,"accessor_id": 4,"accessor_type": "User","permission": 1"_destroy": true (optional: deletes permission)} |
Return Codes
| Code | Description |
|---|---|
| 204 | No content |
Delete a Company
curl "https://app.karmacrm.com/api/v2/companies/27.json?api_token=oGscoGFsdS54mProUdDz"
-X DELETE \
-H "Content-Type: application/json"
This endpoint deletes a specific company.
HTTP Request
DELETE https://app.karmacrm.com/api/v2/companies/<ID>.json
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the company to delete |
| api_token | The token to authenticate request |
Return Codes
| Code | Description |
|---|---|
| 204 | No content |
Activities
Get All Activities
curl "
https://app.karmacrm.com/api/v3/activities.json?api_token=oGscoGFsdS54mProUdDz&per_page=100&page=1&filters%5Bdue_category%5D=overdue&filters%5Btodo_category_id%5D%5Bvalues%5D%5B%5D=21&filters%5Buser_id%5D=mine&columns%5B%5D=all_day&columns%5B%5D=body&columns%5B%5D=complete&columns%5B%5D=end_at&columns%5B%5D=due_at" \
-H "Content-Type: application/json"
The above command returns JSON structured like this:
{
"results": [
{
"id": 21,
"body": "Meeting",
"todo_category_id": 21,
"all_day": false,
"start_at": "2019-04-12T00:00:00Z"
},
{
"id": 34,
"body": "Task Step",
"todo_category_id": 21,
"all_day": false,
"contact": {
"id": 22,
"name": "John Smith",
"email": "john.smith@email.com"
},
"start_at": "2019-05-17T21:00:00Z"
}
],
"total_count": 2
}
This endpoint retrieves all activities related to a contact.
HTTP Request
GET https://app.karmacrm.com/api/v3/activities/related.json
Query Parameters
| Parameter | Description |
|---|---|
| page | Gets a specific page of activities |
| per_page | Number of activities per page |
| api_token | The token to authenticate request |
| filters[due_category] | Filter based on "due_at" date i.e. overdue, today_and_overdue, today, this_week, upcoming |
| filters[todo_category_id][values][] | Filter based on todo category ids |
| filters[user_id] | Filter based "user_id" i.e, mine, or user_id |
| sorts[due_at] | Sort by "due_at" date asc and desc |
| columns[] | Include columns in results i.e. all_day, body, complete, end_at, etc |
Get Related Activities (for a Contact)
curl "https://app.karmacrm.com/api/v3/activities/related.json?api_token=oGscoGFsdS54mProUdDz&record_type=Contact&record_id=22&per_page=100&page=1" \
-H "Content-Type: application/json"
The above command returns JSON structured like this:
{
"results": [
{
"id": 34,
"body": "Task from Template",
"user_id": 4,
"created_by_id": 4,
"todo_category_id": 21,
"complete": false,
"todo_template_step_id": 1,
"start_at": "2019-05-17T21:00:00Z",
"created_at": "2019-05-17T16:50:56Z",
"source": "Task Template",
"participants": [
{
"id": 91,
"label": "John Smith",
"participater_id": 22,
"participater_type": "Contact"
}
],
"reminders":[
{
"id": 10,
"reminder_type_id": 5,
"time_increment": 10,
"interval": "minutes"
}
]
},
{
"id": 35,
"body": "Task from Campaign",
"created_by_id": 4,
"complete": false,
"campaign_step_id": 5,
"start_at": "2019-05-17T06:00:00Z",
"created_at": "2019-05-17T16:51:08Z",
"source": "Task Campaign",
"participants": [
{
"id": 93,
"label": "John Smith",
"participater_id": 22,
"participater_type": "Contact"
}
]
}
],
"total_count":2
}
This endpoint retrieves all activities related to a contact.
HTTP Request
GET https://app.karmacrm.com/api/v3/activities/related.json
Query Parameters
| Parameter | Description |
|---|---|
| page | Gets a specific page of activities |
| per_page | Number of activities per page |
| api_token | The token to authenticate request |
| record_type | Record Type (i.e. Contact) |
| record_id | Record ID |
Get a Specific Activity
curl "
https://app.karmacrm.com/api/v3/activities/48.json?api_token=oGscoGFsdS54mProUdDz" \
-H "Content-Type: application/json"
The above command returns JSON structured like this:
{
"id": 48,
"body": "My Activity Body",
"description": "My Activity Notes",
"todo_category_id": 17,
"user_id": 4,
"organization_id": 2,
"created_by_id": 4,
"activity_type": "Todo",
"recurrence": [],
"where": "",
"calendar_id": 4,
"complete": false,
"created_at": "2019-06-20T22:49:55Z",
"updated_at": "2019-06-20T22:49:55Z",
"reminders": [
{
"id": 14,
"reminder_type_id": 2,
"interval": "minutes",
"time_increment": 15
},
{
"id": 15,
"reminder_type_id": 3,
"interval": "days",
"time_increment": 2
}
],
"participants": []
}
This endpoint retrieves a specific activity.
HTTP Request
GET https://app.karmacrm.com/api/v3/activities/related.json
Query Parameters
| Parameter | Description |
|---|---|
| api_token | The token to authenticate request |
Create an Activity
curl "https://app.karmacrm.com/api/v3/activities.json?api_token=oGscoGFsdS54mProUdDz" \
-X POST \
-H "Content-Type: application/json" \
-d '{"activity":{"body":"My Body","where":"","description":"My Notes","all_day":true,"user_id":36192,"todo_category_id":140844,"reminders":[{"reminder_type_id":"2","interval":"minutes","time_increment":"15"}],"participants":[{"participater_id":"10662866","participater_type":"Contact"}],"recurrence":[],"due_at":"2019-06-21 6:00:00Z","end_at":null,"calendar_id":53518,"complete":false}}'
Successful activity creation response:
{
"id":2674024,
"body":"My Body",
"description":"My Notes",
"todo_category_id":140844,
"user_id":36192,
"organization_id":13346,
"created_by_id":36192,
"all_day":true,
"recurrence":[],
"where":"",
"calendar_id":53518,
"complete":false,
"start_at":"2019-06-21T06:00:00Z",
"created_at":"2019-06-21T17:33:12Z",
"updated_at":"2019-06-21T17:33:12Z",
"reminders":[
{
"id":1767753,
"reminder_type_id":2,
"interval":"minutes",
"time_increment":15
}
],
"participants":[
{
"id":18861339,
"participater_type":"Contact",
"participater_id":10662866,
"label":"John Smith"
}
]
}
HTTP Request
POST https://app.karmacrm.com/api/v3/activities.json
URL Parameters
| Parameter | Description |
|---|---|
| api_token | The token to authenticate request |
Request Payload
| Parameter | Description |
|---|---|
| activity[body] | Activity's body |
| activity[where] | Activity's location, |
| activity[description] | Activity's notes, |
| activity[all_day] | Boolean value for if the activity is all day |
| activity[user_id] | ID of activity's assigned user, |
| activity[todo_category_id] | ID of activity's todo category, |
| activity[reminders] | an array of reminder objects i.e. {"reminder_type_id":"3","interval":"minutes","time_increment":"15"} |
| activity[participants] | an array of participant objects i.e.{"participater_id":36348,"participater_type":"User"} |
| activity[due_at] | Activity's start time / due time |
| activity[end_at] | Activity's end time, |
| activity[calendar_id] | ID of calendar the activity belongs to, |
| activity[complete] | Boolean value for if the activity is completed, |
| activity[completed_at] | Activity's completion time if completed |
Update an Activity
curl "https://app.karmacrm.com/api/v3/activities/49.json?api_token=oGscoGFsdS54mProUdDz" \
-X PUT \
-H "Content-Type: application/json" \
-d '{"id":49,"activity":{"body":"My Body","where":"","description":"My Notes","all_day":false,"user_id":36192,"todo_category_id":140847,"reminders":[{"id":1767725,"_destroy":false,"reminder_type_id":"2","interval":"minutes","time_increment":"15"}],"participants":[{"id":18861204,"participater_id":36192,"participater_type":"User","_destroy":true},{"participater_id":36348,"participater_type":"User"}],"recurrence":[],"due_at":"2019-06-21 18:30:00Z","end_at":"2019-06-21 20:00:00Z","calendar_id":53518,"complete":false}}'
This endpoint updates a specific activity.
HTTP Request
PUT https://app.karmacrm.com/api/v3/activities/<ID>.json
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the activity to update |
| api_token | The token to authenticate request |
Request Payload
| Parameter | Description |
|---|---|
| activity[body] | Activity's body |
| activity[where] | Activity's location, |
| activity[description] | Activity's notes, |
| activity[all_day] | Boolean value for if the activity is all day |
| activity[user_id] | ID of activity's assigned user, |
| activity[todo_category_id] | ID of activity's todo category, |
| activity[reminders] | an array of reminder objects i.e. update: {"id":4,"reminder_type_id":"3","interval":"minutes","time_increment":"20"}add new: {"reminder_type_id":"3","interval":"hours","time_increment":"1"}delete: {"id":6,"reminder_type_id":"3","interval":"minutes","time_increment":"15","_destroy":true} |
| activity[participants] | an array of participant objects i.e. update: {"id":18,"participater_id":10,"participater_type":"Contact","_destroy":falseadd new: {"participater_id":36,"participater_type":"User"}delete: {"id":6,"participater_id":23,"participater_type":"User","_destroy":true} |
| activity[due_at] | Activity's start time / due time |
| activity[end_at] | Activity's end time, |
| activity[calendar_id] | ID of calendar the activity belongs to, |
| activity[complete] | Boolean value for if the activity is completed, |
| activity[completed_at] | Activity's completion time if completed |
Return Codes
| Code | Description |
|---|---|
| 204 | No content |
Delete a Activity
curl "https://app.karmacrm.com/api/v3/activities/27.json?api_token=oGscoGFsdS54mProUdDz"
-X DELETE \
-H "Content-Type: application/json"
This endpoint deletes a specific activity.
HTTP Request
DELETE https://app.karmacrm.com/api/v3/activities/<ID>.json
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the activity to delete |
| api_token | The token to authenticate request |
Return Codes
| Code | Description |
|---|---|
| 204 | No content |
Calendars
Get All Calendars
curl "https://app.karmacrm.com/api/v3/activities.json?api_token=oGscoGFsdS54mProUdDz" \
-H "Content-Type: application/json"
The above command returns JSON structured like this:
{
"results": [
{
"id": 9,
"title": "My private calendar",
"color": "#336699",
"user_id": 4,
"personal": true,
"public": false,
"calendar_users": []
},
{
"id": 10,
"title": "My Public Calendar",
"color": "#b08b59",
"user_id": 4,
"personal": false,
"public": true,
"calendar_users": []
},
{
"id": 12,
"title": "My Shared Calendar",
"color": "#b08b59",
"user_id": 4,
"personal": false,
"public": false,
"calendar_users": [
{
"user_id": 5,
"hidden": null,
"position": null
}
]
}
],
"total_count": 6
}
This endpoint retrieves all calendars.
HTTP Request
GET https://app.karmacrm.com/api/v3/calendars.json
Query Parameters
| Parameter | Description |
|---|---|
| api_token | The token to authenticate request |
Get All Calendar Items
curl "https://app.karmacrm.com/api/v3/calendars/items?api_token=oGscoGFsdS54mProUdDz&include%5B%5D=activities&start_date=2019-05-26&end_date=2019-07-07&calendar_ids%5B%5D=4" \
-H "Content-Type: application/json"
The above command returns JSON structured like this:
{
"events": [
{
"id": 41,
"name": "Deal ask",
"calendar_id": 4,
"all_day": false,
"logged_at": null,
"parent_id": null,
"activity_type": "Todo",
"event_category_id": 17,
"complete": false,
"start_at": "2019-06-10T20:30:00Z",
"end_at": "2019-06-10T20:30:00Z"
},
{
"id": 51,
"name": "My Body",
"calendar_id": 4,
"all_day": true,
"logged_at": null,
"parent_id": null,
"activity_type": null,
"event_category_id": 20,
"complete": false,
"start_at": "2019-06-21T06:00:00Z",
"end_at": "2019-06-21T06:00:00Z"
}
],
"todos": []
}
This endpoint retrieves all calendar items.
HTTP Request
GET https://app.karmacrm.com/api/v3/calendars/items.json
Query Parameters
| Parameter | Description |
|---|---|
| api_token | The token to authenticate request |
| include | An array of calendar item types, i.e. activities |
| start_date | Retrieves calendar items after this date |
| end_date | Retrieves calendar items before this date |
| calendar_ids | An array of calendar ids that the calendar items belong to. |
Get a Specific Calendar
curl "https://app.karmacrm.com/api/v3/calendars/12.json?api_token=oGscoGFsdS54mProUdDz" \
-H "Content-Type: application/json"
Example Response:
{
"id": 12,
"title": "My Shared Calendar",
"color": "#b08b59",
"token": "X2ed2K8AJzDjc6zxp7Yi",
"personal": false,
"public": false,
"user_id": 4,
"calendar_users": [
{
"user_id": 5
}
]
}
This endpoint retrieves a specific calendar.
HTTP Request
GET https://app.karmacrm.com/api/v3/calendars/<ID>.json
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the calendar to retrieve |
| api_token | The token to authenticate request |
Create a Calendar
curl "https://app.karmacrm.com/api/v3/calendars.json?api_token=oGscoGFsdS54mProUdDz" \
-X POST \
-H "Content-Type: application/json" \
-d '{"calendar":{"title":"My Shared Calendar","color":"#b08b59","calendar_users":[{"user_id":"36348"}],"personal":false,"public":false}}'
Successful calendar creation response:
{
"id": 12,
"title": "My Shared Calendar",
"color": "#b08b59",
"token": "X2ed2K8AJzDjc6zxp7Yi",
"personal": false,
"public": false,
"user_id": 4,
"calendar_users": [
{
"user_id": 5
}
]
}
HTTP Request
POST https://app.karmacrm.com/api/v3/calendars.json
URL Parameters
| Parameter | Description |
|---|---|
| api_token | The token to authenticate request |
Request Payload
| Parameter | Description |
|---|---|
| calendar[title] | Calendar's title |
| calendar[color] | Calendar's color i.e. #b08b59 |
| calendar[personal] | Boolean value for calendar is private |
| calendar[public] | Boolean value for if calendar is public |
| calendar[calendar_users] | Array of user objects to share calendar with i.e. { "user_id": "5"} |
Update a Calendar
curl "https://app.karmacrm.com/api/v3/calendars/20.json?api_token=oGscoGFsdS54mProUdDz" \
-X PUT \
-H "Content-Type: application/json" \
-d '{"calendar":{"title":"My Shared Calendar","color":"#b08b59","personal":false,"public":false,"calendar_users":[{"user_id":"7"},{"user_id":"5","_destroy":true}]}}'
This endpoint updates a specific calendar.
HTTP Request
PUT https://app.karmacrm.com/api/v3/calendars/<ID>.json
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the calendar to update |
| api_token | The token to authenticate request |
Request Payload
| Parameter | Description |
|---|---|
| calendar[title] | Calendar's title |
| calendar[color] | Calendar's color i.e. #b08b59 |
| calendar[personal] | Boolean value for calendar is private |
| calendar[public] | Boolean value for if calendar is public |
| calendar[calendar_users] | Array of user objects to share calendar with i.e. add new: {"user_id":"5"}delete: {"user_id":6,"_destroy":true} |
Return Codes
| Code | Description |
|---|---|
| 204 | No content |
Delete a Calendar
curl "https://app.karmacrm.com/api/v2/calendars/27.json?api_token=oGscoGFsdS54mProUdDz"
-X DELETE \
-H "Content-Type: application/json"
This endpoint deletes a specific calendar.
HTTP Request
DELETE https://app.karmacrm.com/api/v2/calendars/<ID>.json
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the calendars to delete |
| api_token | The token to authenticate request |
Return Codes
| Code | Description |
|---|---|
| 204 | No content |
Deals
Get All Deals
curl "https://app.karmacrm.com/api/v3/deals.json?api_token=oGscoGFsdS54mProUdDz&page=3&since=2019-06-02" \
-H "Content-Type: application/json"
The above command returns JSON structured like this:
{
"results": [
{
"id": 20,
"name": "Deal Title",
"created_at": "2019-06-19T15:58:33Z",
"updated_at": "2019-06-19T16:15:45Z",
"field_values": [
{
"id": 60,
"field_id": 53,
"field_type_id": 5,
"value": "Custom Text Field Value"
}
]
},
{
"id": 21,
"name": "Deal Title Two",
"created_at": "2019-06-19T16:16:20Z",
"updated_at": "2019-06-19T16:16:20Z",
"field_values": [
{
"id": 61,
"field_id": 53,
"field_type_id": 5,
"value": "Custom Text Field Value Two"
}
]
}
],
"total_count": 2
}
This endpoint retrieves all deals.
HTTP Request
GET https://app.karmacrm.com/api/v3/deals.json
Query Parameters
| Parameter | Description |
|---|---|
| page | Gets a specific page of deals |
| api_token | The token to authenticate request |
| since | Filters deals after a specified date |
Get a Specific Deal
curl "https://app.karmacrm.com/api/v3/deals/20.json?api_token=oGscoGFsdS54mProUdDz" \
-H "Content-Type: application/json"
Example Response:
{
"id": 20,
"name": "Deal Title",
"description": "Deal Description",
"deal_stage_id": 15,
"currency": "USD",
"organization_id": 2,
"user_id": 4,
"created_by_id": 4,
"private": false,
"due_on": "2019-06-30",
"probability": 18.0,
"price": 10.0,
"stages": [
{
"id": 11,
"name": "Pending",
"position": 1
},
{
"id": 12,
"name": "Won",
"position": 2
},
{
"id": 13,
"name": "Lost",
"position": 3
},
{
"id": 14,
"name": "Holding",
"position": 4
},
{
"id": 15,
"name": "Sent",
"date": "2019-06-19",
"position": 0
},
{
"id": 16,
"name": "Changed",
"position": 5
}
],
"deal_syncs": [],
"tag_list": "local,support",
"contact": {
"id": 11,
"first_name": "Fred",
"last_name": "Derf",
"avatar_url": "/assets/person_thumb.png",
"emails": [],
"websites": [],
"phone_numbers": [],
"addresses": [],
"social_accounts": [],
"tags": []
},
"contact_id": 11,
"created_at": "2019-06-19T15:58:33Z",
"updated_at": "2019-06-19T16:15:45Z",
"field_values": [
{
"id": 60,
"field_id": 53,
"field_type_id": 5,
"value": "Custom Text Field Value"
}
],
"important_dates": [
{
"id": 21,
"date": "2019-06-19",
"to_status_id": 15
}
]
}
This endpoint retrieves a specific deal.
HTTP Request
GET https://app.karmacrm.com/api/v3/deals/<ID>.json
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the deal to retrieve |
| api_token | The token to authenticate request |
Create a Deal
curl "https://app.karmacrm.com/api/v3/deals.json?api_token=oGscoGFsdS54mProUdDz" \
-X POST \
-H "Content-Type: application/json" \
-d '{"deal":{"name":"Deal Title","contact_id":5,"company_id":7,"deal_stage_id":15,"probability":18,"price":10,"currency":"USD","description":"Deal Description","tags":["local","support"],"user_id":4,"private":false,"field_values":[{"value":"Custom Text Field Value","field_id":53}],"due_on":"2019-06-30"}}'
Successful deal creation response:
{
"id":20,
"name":"Deal Title",
"description":"Deal Description",
"deal_stage_id":15,
"contact_id":5,
"company_id":7,
"price":10.0,
"currency":"USD",
"organization_id":2,
"user_id":4,
"created_by_id":4,
"private":false,
"due_on":"2019-06-30",
"probability":18.0,
"tags":["local","support"],
"created_at":"2019-06-19T15:58:33Z",
"updated_at":"2019-06-19T15:58:33Z",
"field_values":[
{
"id":60,
"field_id":53,
"field_type_id":5,
"field_parent_id":null,
"value":"Custom Text Field Value"
}
],
"important_dates":[
{
"id":21,
"date":"2019-06-19",
"from_status_id":null,
"to_status_id":15
}
]
}
HTTP Request
POST https://app.karmacrm.com/api/v3/deals.json
URL Parameters
| Parameter | Description |
|---|---|
| api_token | The token to authenticate request |
Request Payload
| Parameter | Description |
|---|---|
| deal[name] | Deal's name |
| deal[probablity] | Deal's probablity value |
| deal[price] | Deal's price |
| deal[currency] | Deal's currency |
| deal[description] | Deal's description |
| deal[due_on] | Date deal is due on |
| deal[tags] | array of deal's tags i.e. ["development","usa"] |
| deal[deal_stage_id] | ID of deal's stage |
| deal[contact_id] | ID of contact the deal is for |
| deal[company_id] | ID of company the deal is for (Note: company and contact must be associated with each other if both are provided.) |
| deal[user_id] | ID for deal's assigned user |
| deal[field_values] | array of deal's custom field values, i.e {"field_id":1,"value":"custom info"} {"value":"5","field_id":5,"field_parent_id":2} (with parent field) |
Update a Deal
curl "https://app.karmacrm.com/api/v3/deals/20.json?api_token=oGscoGFsdS54mProUdDz" \
-X PUT \
-H "Content-Type: application/json" \
-d '{"id":20,"deal":{"name":"Deal Title","contact_id":11,"company_id":null,"deal_stage_id":15,"probability":18,"price":10,"currency":"USD","description":"Deal Description","tags":["local","support"],"user_id":4,"private":false,"field_values":[{"id":60,"value":"Custom Text Field Value","field_id":53}],"due_on":"2019-06-30"}}'
This endpoint updates a specific deal.
HTTP Request
PUT https://app.karmacrm.com/api/v3/deals/<ID>.json
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the deal to update |
| api_token | The token to authenticate request |
Request Payload
| Parameter | Description |
|---|---|
| deal[name] | Deal's name |
| deal[probablity] | Deal's probablity value |
| deal[price] | Deal's price |
| deal[currency] | Deal's currency |
| deal[description] | Deal's description |
| deal[due_on] | Date deal is due on |
| deal[tags] | array of deal's tags i.e. ["development","usa"] |
| deal[deal_stage_id] | ID of deal's stage |
| deal[contact_id] | ID of contact the deal is for |
| deal[company_id] | ID of company the deal is for (Note: company and contact must be associated with each other if both are provided.) |
| deal[user_id] | ID for deal's assigned user |
| deals[field_values] | array of deals's custom field values, i.e update: {"id":7,"field_id":1,"value":"update value for text field"}add/check new (checkbox choice): {"value":"5","field_id":5,"field_parent_id":2} |
Return Codes
| Code | Description |
|---|---|
| 204 | No content |
Delete a Deal
curl "https://app.karmacrm.com/api/v2/deals/27.json?api_token=oGscoGFsdS54mProUdDz"
-X DELETE \
-H "Content-Type: application/json"
This endpoint deletes a specific deal.
HTTP Request
DELETE https://app.karmacrm.com/api/v2/deals/<ID>.json
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the deal to delete |
| api_token | The token to authenticate request |
Return Codes
| Code | Description |
|---|---|
| 204 | No content |
Histories
Get All Histories
curl "https://app.karmacrm.com/api/v3/histories.json?api_token=oGscoGFsdS54mProUdDz&per_page=3&page=1&include_external=true" \
-H "Content-Type: application/json"
The above command returns JSON structured like this:
{
"results": [
{
"id": 137,
"name": "Todo",
"user_id": 4,
"created_by_id": 4,
"history_category_id": 8,
"history_type_id": 3,
"history_record_id": 34,
"history_record_type": "Todo",
"external_id": 34,
"external_type": "Todo",
"history_record_label": "Task Step",
"external": {
"label": "Task Step"
},
"created_at": "2019-05-17T16:50:56Z",
"occurred_at": "2019-05-17T16:50:56Z",
"participants": [
{
"id": 92,
"participater_id": 22,
"participater_type": "Contact",
"label": "Fresh Koolaid"
}
]
},
{
"id": 136,
"name": "Email",
"user_id": 4,
"created_by_id": 4,
"history_category_id": 5,
"history_type_id": 8,
"history_record_id": 5,
"history_record_type": "Contact",
"external_id": 111,
"external_type": "Note",
"history_record_label": "Khulani Malone",
"external": {
"body": "<div><br></div><div>Malone</div>",
"contact_type_id": 1
},
"created_at": "2019-05-17T01:26:25Z",
"occurred_at": "2019-05-17T01:26:21Z",
"participants": [
{
"id": 90,
"participater_id": 7,
"participater_type": "Company",
"label": "Khulani Malone Company"
}
]
},
{
"id": 128,
"name": "Notification",
"user_id": 5,
"created_by_id": 4,
"history_category_id": 3,
"history_type_id": 5,
"history_record_id": 44,
"history_record_type": "Contact",
"external_id": 44,
"external_type": "Contact",
"history_record_label": "Webhook First",
"external": {
"label": "Webhook First"
},
"created_at": "2019-05-13T17:02:36Z",
"occurred_at": "2019-05-13T17:02:36Z"
}
],
"total_count": 100
}
This endpoint retrieves all histories.
HTTP Request
GET https://app.karmacrm.com/api/v3/histories.json
Query Parameters
| Parameter | Description |
|---|---|
| page | Gets a specific page of contacts |
| per_page | Number of contacts per page |
| api_token | The token to authenticate request |
| include_external | Boolean value to include external info |
Get Related Histories (for a Contact)
curl "https://app.karmacrm.com/api/v3/histories/related?api_token=oGscoGFsdS54mProUdDz&record_type=Contact&record_id=22&per_page=100&page=1" \
-H "Content-Type: application/json"
The above command returns JSON structured like this:
{
"results": [
{
"id": 137,
"name": "Todo",
"user_id": 4,
"created_by_id": 4,
"history_category_id": 8,
"history_type_id": 3,
"occurred_at": "2019-05-17T16:50:56Z",
"external": {
"type": "Todo",
"id": 34,
"label": "Task Step"
}
},
{
"id": 127,
"name": "Email",
"user_id": 7,
"created_by_id": 7,
"history_category_id": 5,
"history_type_id": 8,
"occurred_at": "2019-05-13T16:57:55Z",
"record": {
"type": "Contact",
"id": 22,
"label": "John Smith"
},
"external": {
"type": "Note",
"id": 71,
"label": "<div>testing</div>",
"note_type": "email",
"subject": "local email test",
"private": false,
"incoming": false,
"reminders": [],
"meta": {
"id": 53
}
}
},
{
"id": 35,
"name": "Contact",
"user_id": 4,
"created_by_id": 4,
"history_category_id": 2,
"history_type_id": 3,
"occurred_at": "2019-03-22T18:49:07Z",
"record": {
"type": "Contact",
"id": 22,
"label": "John Smith"
},"external": {
"type": "Contact",
"id": 22,
"label": "John Smith"
}
}
],
"total_count": 3
}
This endpoint retrieves all histories related to a contact.
HTTP Request
GET https://app.karmacrm.com/api/v3/histories/related.json
Query Parameters
| Parameter | Description |
|---|---|
| page | Gets a specific page of contacts |
| per_page | Number of contacts per page |
| api_token | The token to authenticate request |
| record_type | Record Type (i.e. Contact) |
| record_id | Record ID |
Custom Fields
Custom Text Field - Create
Create a resource with a custom text field
{
"contact" : {
...
"field_values": [
...
{
"field_id": 1,
"value": "custom text value"
},
...
]
...
}
}
Response object
{
"id": 38,
...
"field_values": [
...
{
"id": 45,
"field_id": 1,
"field_type_id": 5,
"field_parent_id": null,
"value": "custom text value"
},
...
],
...
}
Request Payload
| Parameter | Description |
|---|---|
| field_id | id of custom text field |
| value | value for custom text field |
Custom Text Field - Update
Update a resource with a custom text field
{
"contact" : {
...
"field_values": [
...
{
"id": 45,
"value": "custom text value update",
"field_id": 1
},
...
],
...
}
}
Response
204 No Content
Request Payload
| Parameter | Description |
|---|---|
| id | id of custom text value |
| field_id | id of custom text field |
| value | value for custom text field |
Custom Checkbox - Create
Create a resource with a custom checkbox
{
"contact" : {
...
"field_values": [
...
{
"value": "4",
"field_id": 4,
"field_parent_id": 2
},
{
"value": "5",
"field_id": 5,
"field_parent_id": 2
,
...
]
...
}
}
Response object
{
"id": 38,
...
"field_values": [
...
{
"id": 46,
"field_id": 4,
"field_type_id": 3,
"field_parent_id": 2,
"value": 4
},
{
"id": 47,
"field_id": 5,
"field_type_id": 3,
"field_parent_id": 2,
"value": 5
},
...
],
...
}
Request Payload
| Parameter | Description |
|---|---|
| field_id | id of custom checkbox selection |
| field_parent_id | id of custom checkbox field |
| value | value for custom checkbox selection |
Custom Checkbox - Update
Update a resource with a custom checkbox
{
"contact" : {
...
"field_values": [
...
{
"value": "3",
"field_id": 3,
"field_parent_id": 2
},
{
"id": 46,
"value": "4",
"field_id": 1,
"field_parent_id": 2,
"_destroy": true
},
{
"id": 47,
"value":" 5",
"field_id": 5,
"field_parent_id": 2
},
...
],
...
}
}
Response
204 No Content
Request Payload
| Parameter | Description |
|---|---|
| id | id of checkbox field record |
| field_id | id of custom checkbox selection |
| field_parent_id | id of custom checkbox field |
| value | value for custom checkbox selection |
| _destroy | boolean to uncheck checkbox selection |
Custom Date Field - Create
Create a resource with a custom text field
{
"contact" : {
...
"field_values": [
...
{
"field_id": 6,
"value": "2019-04-24"
},
...
]
...
}
}
Response object
{
"id": 38,
...
"field_values": [
...
{
"id": 48,
"field_id": 6,
"field_type_id": 7,
"field_parent_id": null,
"value": "2019-04-24"
},
...
],
...
}
Request Payload
| Parameter | Description |
|---|---|
| field_id | id of custom date field |
| value | value for custom date field |
Custom Date Field - Update
Update a resource with a custom date field
{
"contact" : {
...
"field_values": [
...
{
"id": 48,
"value": "2019-04-25",
"field_id": 6
},
...
],
...
}
}
Response
204 No Content
Request Payload
| Parameter | Description |
|---|---|
| id | id of custom date record |
| field_id | id of custom date field |
| value | value for custom date field |
Custom Text Area Field - Create
Create a resource with a custom text area field
{
"contact" : {
...
"field_values": [
...
{
"field_id": 15,
"value": "custom text area value"
},
...
]
...
}
}
Response object
{
"id": 38,
...
"field_values": [
...
{
"id": 49,
"field_id": 15,
"field_type_id": 4,
"field_parent_id": null,
"value": "custom text area value"
},
...
],
...
}
Request Payload
| Parameter | Description |
|---|---|
| field_id | id of custom text area field |
| value | value for custom text area field |
Custom Text Area Field - Update
Update a resource with a custom text area field
{
"contact" : {
...
"field_values": [
...
{
"id": 49,
"value": "custom text area value update",
"field_id": 15
},
...
],
...
}
}
Response
204 No Content
Request Payload
| Parameter | Description |
|---|---|
| id | id of custom text area record |
| field_id | id of custom text area field |
| value | value for custom text area field |
Custom Currency Field - Create
Create a resource with a custom currency field
{
"contact" : {
...
"field_values":[
...
{
"value": "13",
"field_id": 17
},
...
]
...
}
}
Response object
{
"id": 38,
...
"field_values": [
...
{
"id": 50,
"field_id": 17,
"field_type_id": 8,
"field_parent_id": null,
"value": "13"
},
...
],
...
}
Request Payload
| Parameter | Description |
|---|---|
| field_id | id of custom currency field |
| value | value for custom currency field |
Custom Currency Field - Update
Update a resource with a custom currency field
{
"contact" : {
...
"field_values": [
...
{
"id": 50,
"value": "15",
"field_id": 17
}
...
],
...
}
}
Response
204 No Content
Request Payload
| Parameter | Description |
|---|---|
| id | id of custom currency record |
| field_id | id of custom currency field |
| value | value for custom currency field |
Custom Select Field - Create
Create a resource with a custom select field
{
"contact" : {
...
"field_values":[
...
{
"value": "13",
"field_id": 13,
"field_parent_id": 11
},
...
]
...
}
}
Response object
{
"id": 38,
...
"field_values": [
...
{
"id": 51,
"field_id": 13,
"field_type_id": 2,
"field_parent_id": 11,
"value": 13
},
...
],
...
}
Request Payload
| Parameter | Description |
|---|---|
| field_id | id of custom select selection |
| field_parent_id | id of custom select field |
| value | value for custom checkbox selection |
Custom Select Field - Update
Update a resource with a custom select field
{
"contact" : {
...
"field_values": [
...
{
"id": 51,
"value": "12",
"field_id": 12,
"field_parent_id": 11
}
...
],
...
}
}
Response
204 No Content
Request Payload
| Parameter | Description |
|---|---|
| id | id of custom select record |
| field_id | id of custom select selection |
| field_parent_id | id of custom select field |
| value | value for custom checkbox selection |
| _destroy | boolean to unselect a selection |
Campaign Entries
Apply Campaign (Create a Campaign Entries)
curl "https://app.karmacrm.com/api/v3/campaign_entries/apply?api_token=oGscoGFsdS54mProUdDz" \
-X POST \
-H "Content-Type: application/json" \
-d '{"campaign_entry":{"record_id":10662866,"record_type":"Contact","campaign_id":"142"}}'
Response for successfully applying a campaign:
{
"id": 9646,
"record_id": 10662866,
"record_type": "Contact",
"campaign_id": 142,
"current_campaign_entry_step_id": 67223,
"created_at": "2019-04-02T22:25:05Z",
"updated_at": "2019-04-02T22:25:05Z",
"campaign_entry_steps": [
{
"id": 67223,
"activity_type": "Note",
"activity_id": 10419189,"
campaign_entry_id": 9646,"
campaign_step_id": 719
},
{
"id": 67224,
"campaign_entry_id": 9646,
"campaign_step_id": 720
},
{
"id": 67225,
"campaign_entry_id": 9646,
"campaign_step_id": 721
}
]
}
HTTP Request
POST https://app.karmacrm.com/api/v3/campaign_entries/apply
URL Parameters
| Parameter | Description |
|---|---|
| api_token | The token to authenticate request |
Request Payload
| Parameter | Description |
|---|---|
| campaign_entry[record_id] | Record's ID to apply campaign to |
| campaign_entry[record_type] | Record's type to apply campaign to (i.e. Contact) |
| campaign_entry[campaign_id] | ID of campaign being applied |
Cancel a Campaign Entry
curl "https://app.karmacrm.com/api/v3/campaign_entries/9646/cancel.json?api_token=oGscoGFsdS54mProUdDz" \
-X PUT \
-H "Content-Type: application/json" \
-d '{"id":9646}'
This endpoint updates a specific contact.
HTTP Request
PUT https://app.karmacrm.com/api/v3/campaign_entries/<ID>/cancel.json
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the campaign entry to cancel |
| api_token | The token to authenticate request |
Request Payload
| Parameter | Description |
|---|---|
| id | Campaign entry's id |
Return Codes
| Code | Description |
|---|---|
| 204 | No content |
Social Account Types
Get All Social Account Types
curl "https://app.karmacrm.com/api/v2/settings/social_account_types.json?api_token=oGscoGFsdS54mProUdDz" \
-H "Content-Type: application/json"
The above command returns JSON structured like this:
{
"results": [
{
"id": 104,
"name": "AngelList",
"index": "angellist"
},
{
"id": 1,
"name": "Twitter",
"index": "twitter"
},
{
"id": 2,
"name": "Facebook",
"index": "facebook"
},
{
"id": 3,
"name": "LinkedIn",
"index": "linkedin"
},
{
"id": 4,
"name": "Gravatar",
"index": "gravatar"
},
{
"id": 5,
"name": "Google Plus",
"index": "google_plus"
},
{
"id": 8,
"name": "AOLChat",
"index": "aOLChat"
},
{
"id": 10,
"name": "Bithucket",
"index": "bithucket"
},
{
"id": 14,
"name": "DevianArt",
"index": ""
},
{
"id": 15,
"name": "Digg",
"index": ""
},
{
"id": 25,
"name": "Flickr",
"index": ""
},
{
"id": 29,
"name": "Friendster",
"index": ""
},
{
"id": 35,
"name": "Github",
"index": "github"
},
{
"id": 4,
"name": "Gravatar",
"index": "gravatar"
},
{
"id": 105,
"name": "Instagram",
"index": "instagram"
},
{
"id": 49,
"name": "Imdb",
"index": ""
},
{
"id": 54,
"name": "Lastfm",
"index": ""
},
{
"id": 56,
"name": "Livejournal",
"index": ""
},
{
"id": 58,
"name": "Meetup",
"index": ""
},
{
"id": 63,
"name": "Myspace",
"index": ""
},
{
"id": 66,
"name": "Other",
"index": ""
},
{
"id": 67,
"name": "Pandora",
"index": ""
},
{
"id": 68,
"name": "Picasa",
"index": ""
},
{
"id": 70,
"name": "Pinterest",
"index": ""
},
{
"id": 76,
"name": "Quora",
"index": ""
},
{
"id": 77,
"name": "Reddit",
"index": ""
},
{
"id": 80,
"name": "Scribd",
"index": ""
},
{
"id": 82,
"name": "Skype",
"index": "skype"
},
{
"id": 85,
"name": "Soundcloud",
"index": ""
},
{
"id": 87,
"name": "Stackoverflow",
"index": ""
},
{
"id": 92,
"name": "Tumblr",
"index": ""
},
{
"id": 96,
"name": "Vimeo",
"index": ""
},
{
"id": 98,
"name": "Wordpress",
"index": ""
},
{
"id": 100,
"name": "Yahoo",
"index": "Yahoo"
},
{
"id": 102,
"name": "Yelp",
"index": "Yelp"
},
{
"id": 103,
"name": "YouTube",
"index": "youtube"
}
],
"total_count": 101,
"timestamp": 1552263193
}
This endpoint retrieves all social account types.
HTTP Request
GET https://app.karmacrm.com/api/v2/settings/social_account_types.json
Query Parameters
| Parameter | Description |
|---|---|
| api_token | The token to authenticate request |
Attachments
Download an Attachment
curl "https://app.karmacrm.com/api/v2/assets/5/download?api_token=oGscoGFsdS54mProUdDz"
This endpoint downloads a specific file attachment.
HTTP Request
GET https://app.karmacrm.com/api/v2/assets/5/download
Query Parameters
| Parameter | Description |
|---|---|
| api_token | The token to authenticate request |
Create an Attachment
curl "https://app.karmacrm.com/api/v2/attachments" \
-X POST \
-H "Content-Type: multipart/form-data" \
-F "attachment[record_type]=Contact" \
-F "attachment[record_id]=5" \
-F "attachment[file]=@/home/user1/Desktop/photo.jpeg"
Successful attachment creation response:
{
"id": 11,
"asset_id": 10,
"uuid": null,
"class_name": "Attachment",
"name": null,
"description": null,
"data_file_name": "photo.jpeg",
"data_file_size": 280930,
"data_content_type": "image/jpeg",
"created_at": "2019-05-28T14:17:10-06:00",
"private": false,
"created_at_formatted": "05/28/2019"
}
HTTP Request
POST https://app.karmacrm.com/api/v2/attachments
URL Parameters
| Parameter | Description |
|---|---|
| api_token | The token to authenticate request |
Form Data
| Parameter | Description |
|---|---|
| attachment[record_type] | Type of record associated w/ attachment i.e. Contact |
| attachment[record_id] | ID of Record associated w/ attachment |
| attachment[file] | File being attached (binary) |
Delete an Attachment
curl "https://app.karmacrm.com/api/v2/attachments/27?api_token=oGscoGFsdS54mProUdDz" \
-X DELETE
This endpoint deletes a specific attachment file.
HTTP Request
DELETE https://app.karmacrm.com/api/v2/attachments/<ID>
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the contact to delete |
| api_token | The token to authenticate request |
Return Codes
| Code | Description |
|---|---|
| 204 | No content |
Notes
Get All Notes (Histories)
curl "https://app.karmacrm.com/api/v2/histories.json?filters[external_type]=Note&filters[history_record_id]=46&filters[history_record_type]=Contact&page=1&api_token=oGscoGFsdS54mProUdDz \
-H "Content-Type: application/json"
The above command returns JSON structured like this:
{
"results": [
{
"history_record_label": "John Smith",
"history_record_path": "contacts/46",
"id": 179,
"history_record_id": 46,
"history_record_type": "Contact",
"history_type_id": 3,
"name": "Note",
"description": null,
"user_id": 4,
"organization_id": 2,
"lead_id": null,
"created_at": "2019-06-04T22:48:15Z",
"updated_at": "2019-06-04T22:48:15Z",
"note_id": 160,
"company_id": null,
"external_id": 160,
"external_type": "Note",
"private": null,
"created_by_id": 4,
"group_id": null,
"delta": false,
"read": false,
"notification": false,
"parent_id": null,
"occurred_at": "2019-06-04T22:48:15Z",
"comment_count": 0,
"history_category_id": 4,
"secondary_history_record_id": null,
"secondary_history_record_type": null,
"old_entity_id": null,
"activity_type": "",
"external": {
"subject": "",
"contact_type_id": 3,
"label": "My Note Content",
"comments": [],
"assets": []
},
"comments": [],
"participants": [],
"_score": null,
"_type": "history",
"_index": "histories_development",
"_version": null,
"sort": [1559688495000],
"highlight": null,
"_explanation": null,
"history_record": {},
"posted_by": "Posted by",
"box_class": "note",
"external_path": "notes/160",
"history_type_name": "Created",
"editable": true,
"list_body": "My Note Content",
"body": "My Note Content",
"class_name": "History"
}
],
"total_count": 4,
"filter": "external type 'Note' history record id '46' history record type 'Contact' "
}
This endpoint retrieves all contacts.
HTTP Request
GET https://app.karmacrm.com/api/v2/histories.json
Query Parameters
| Parameter | Description |
|---|---|
| page | Gets a specific page of histories |
| api_token | The token to authenticate request |
| filters[external_type] | Type of history i.e. Note |
| filters[history_record_type] | Record type assocated with histories i.e. Contact, Company, etc |
| filters[history_record_id] | Record id associated with histories |
Get a Note (History)
curl "https://app.karmacrm.com/api/v2/histories/179.json?api_token=oGscoGFsdS54mProUdDz" \
-H "Content-Type: application/json"
Example Response:
{
"id": "179",
"history_record_id": 46,
"history_record_type": "Contact",
"history_type_id": 3,
"name": "Note",
"description": null,
"user_id": 4,
"organization_id": 2,
"lead_id": null,
"created_at": "2019-06-04T22:48:15Z",
"updated_at": "2019-06-04T22:48:15Z",
"note_id": 160,
"company_id": null,
"external_id": 160,
"external_type": "Note",
"private": null,
"created_by_id": 4,
"group_id": null,
"delta": false,
"read": false,
"notification": false,
"parent_id": null,
"occurred_at": "2019-06-04T22:48:15Z",
"comment_count": 0,
"history_category_id": 4,
"secondary_history_record_id": null,
"secondary_history_record_type": null,
"old_entity_id": null,
"activity_type": "",
"external": {
"id": 160,
"label": "My Note Content",
"subject": null,
"body": "My Note Content",
"contact_type_id": 3,
"assets": []
},
"comments": [],
"participants": [
{
"id": null,
"participater_id": 46,
"participater_type": "Contact",
"label": "John Smith"
}
],
"_type": "history",
"_index": "histories_development",
"_version": 2,
"history_record_label": "John Smith",
"history_record_path": "contacts/46",
"occurred_at_short": "06/04",
"class_name": "History",
"posted_by": "Posted by",
"occurred_at_long": "06/04/2019 at 4:48pm",
"updated_at_formatted": "06/04/2019",
"box_class": "note",
"editable": true,
"list_body": "My Note Content",
"body": "My Note Content",
"attachments": []
}
This endpoint retrieves a specific contact.
HTTP Request
GET https://app.karmacrm.com/api/v2/histories/<ID>.json
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the contact to retrieve |
| api_token | The token to authenticate request |
Create a Note
curl "https://app.karmacrm.com/api/v2/notes.json??api_token=oGscoGFsdS54mProUdDz \
-X POST \
-H "Content-Type: application/json" \
-d '{"result_type":"backbone","note":{"body":"My Note Content","contact_type_id":3,"date":"2019-06-12","participants":[{"label":"John Smith","participater_type":"User","participater_id":4}],"user_ids":[4],"parent_type":"Contact","parent_id":11}}'
Successful note creation response:
{
"id": 153,
"to": null,
"from": null,
"bcc": null,
"cc": null,
"body": "My Note Content",
"subject": null,
"date": null,
"lead_id": 11,
"user_id": 4,
"contact_type_id": 3,
"organization_id": 2,
"created_at": "2019-06-04T10:16:18-06:00",
"updated_at": "2019-06-04T10:16:18-06:00",
"from_lead": false,
"created_by_id": 4,
"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,
"opened_at": null,
"incoming": null,
"contextio_message_id": null,
"private": false,
"deliver_at": null,
"replied_at": null,
"campaign_entry_step_id": null,
"bounced": false,
"delivery_attempts": 0,
"class_name": "Decorators::Note",
"history": {
"id": 172,
"history_record_id": 11,
"history_record_type": "Contact",
"history_type_id": 3,
"name": "Note",
"description": null,
"user_id": 4,
"organization_id": 2,
"lead_id": null,
"created_at": "2019-06-04T10:16:18-06:00",
"updated_at": "2019-06-04T10:16:18-06:00",
"note_id": 153,
"company_id": null,
"external_id": 153,
"external_type": "Note",
"private": null,
"created_by_id": 4,
"group_id": null,
"delta": false,
"read": false,
"notification": false,
"parent_id": null,
"occurred_at": "2019-06-12T10:16:00-06:00",
"comment_count": 0,
"history_category_id": 4,
"secondary_history_record_id": null,
"secondary_history_record_type": null,
"old_entity_id": null,
"additional_information": {},
"activity_type": "",
"occurred_at_utc": "2019-06-12T16:16:00Z",
"class_name": "History",
"posted_by": "Posted by",
"box_class": "note",
"editable": true,
"list_body": "My Note Content",
"body": "My Note Content"
}
}
HTTP Request
POST https://app.karmacrm.com/api/v2/notes.json
URL Parameters
| Parameter | Description |
|---|---|
| api_token | The token to authenticate request |
Request Payload
| Parameter | Description |
|---|---|
| note[body] | Note Content |
| note[contact_type_id] | type id for note i.e 3 to add a note, 2 log a call |
| note[date] | Date added to note |
| note[time] | Time added to note |
| note[parent_type] | Record Type associated with note i.e. Contact, Company, etc |
| note[parent_id] | Record ID associated with note |
| note[user_ids] | User IDs to receive email notification |
| note[participants] | array of participants, i.e. {"label": "John Smith","participater_type":"User","participater_id":4} |
Update a Note (History)
curl "https://app.karmacrm.com/api/v2/histories/177.json?api_token=oGscoGFsdS54mProUdDz" \
-X PUT \
-H "Content-Type: application/json" \
-d '{"result_type":"backbone","history":{"date":"2019-06-19","time":"4:30am","external":{"type":"Note","id":158,"label":"My Updated Note Content","private":false,"body":"My Updated Note Content"}}}'
Successful note update response:
{
"id":177,
"history_record_id":11,
"history_record_type":"Contact",
"history_type_id":3,
"name":"Phone Call",
"description":null,
"user_id":4,
"organization_id":2,
"lead_id":null,
"created_at":"2019-06-04T12:48:52-06:00",
"updated_at":"2019-06-04T12:57:07-06:00",
"note_id":158,
"company_id":null,
"external_id":158,
"external_type":"Note",
"private":null,
"created_by_id":4,
"group_id":null,
"delta":false,
"read":false,
"notification":false,
"parent_id":null,
"occurred_at":"2019-06-19T10:30:00Z",
"comment_count":0,
"history_category_id":6,
"secondary_history_record_id":null,
"secondary_history_record_type":null,
"old_entity_id":null,
"additional_information":{},
"activity_type":"phone_call_created",
"history_record_label":"Fred Derf",
"history_record_path":"contacts/11",
"occurred_at_short":"06/19",
"class_name":"History",
"posted_by":"Posted by",
"occurred_at_long":"06/19/2019 at 4:30am",
"updated_at_formatted":"06/04/2019",
"box_class":"phone-call",
"editable":true,
"list_body":"My Updated Note Content",
"body":"My Updated Note Content",
"external":{
"id":158,
"to":null,
"from":null,
"bcc":null,
"cc":null,
"body":"My Updated Note Content",
"subject":null,
"date":null,
"lead_id":11,
"user_id":4,
"contact_type_id":2,
"organization_id":2,
"created_at":"2019-06-04T12:48:52-06:00",
"updated_at":"2019-06-04T12:57:07-06:00",
"from_lead":false,
"created_by_id":4,
"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,
"opened_at":null,
"incoming":null,
"contextio_message_id":null,
"private":false,
"deliver_at":null,
"replied_at":null,
"campaign_entry_step_id":null,
"bounced":false,
"delivery_attempts":0
},
"attachments":[],
"participants":[
{
"id":null,
"participater_id":11,
"participater_type":"Contact",
"label":"Fred Derf"
},
{
"id":197,
"participater_id":7,
"participater_type":"User",
"label":"khulani@gmail.com malone"
}
]
}
This endpoint updates a specific note (history).
HTTP Request
PUT https://app.karmacrm.com/api/v2/histories/<ID>.json
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the contact to delete |
| api_token | The token to authenticate request |
Request Payload
| Parameter | Description |
|---|---|
| result_type | result type (...may not be required) i.e. backbone |
| history[date] | Date added to note |
| history[time] | Time added to note |
| history[external][type] | Note |
| history[external][id] | Note id |
| history[external][body] | Note content |
| history[external][label] | Note content (same value as body) |
Delete a Note (History)
curl "https://app.karmacrm.com/api/v2/histories/172.json?api_token=oGscoGFsdS54mProUdDz"
-X DELETE \
-H "Content-Type: application/json"
This endpoint deletes a specific note (history).
HTTP Request
DELETE https://app.karmacrm.com/api/v2/histories/<ID>.json
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the contact to delete |
| api_token | The token to authenticate request |
Return Codes
| Code | Description |
|---|---|
| 204 | No content |
Emails
Send an email
curl "https://app.karmacrm.com/api/v3/mailman_nylas/outgoing/messages.json?api_token=oGscoGFsdS54mProUdDz \
-X POST \
-H "Content-Type: application/json" \
-d '{"message":{"to":[{"id":5,"type":"Contact","label":"John Smith","email":"john.smith@gmail.com"}],"authorization_id":1,"subject":"My subject","body":"<div>My HTML body</div>"}}'
This endpoint sends an email.
HTTP Request
POST https://app.karmacrm.com/api/v3/mailman_nylas/outgoing/messages/create_draft.json
URL Parameters
| Parameter | Description |
|---|---|
| api_token | The token to authenticate request |
Request Payload
| Parameter | Description |
|---|---|
| message[to] | array of 'to' recipients i.e. {"label": "John Smith","type":"Contact","email":"john.smith@gmail.com""id":5} |
| message[authorization_id] | authorization id of sender (user) |
| message[subject] | Email subject |
| message[body] | Email body |
Response Code
| Code | Description |
|---|---|
| 204 | No content |
Create an Email Draft
curl "https://app.karmacrm.com/api/v3/mailman_nylas/outgoing/messages/create_draft.json?api_token=oGscoGFsdS54mProUdDz \
-X POST \
-H "Content-Type: application/json" \
-d '{"message":{"to":[{"id":5,"type":"Contact","label":"John Smith","email":"john.smith@gmail.com"}],"authorization_id":1,"cc":[{"id":"46","type":"Contact","email":"jane.smith@gmail.com"}],"bcc":[{"id":"22","type":"Contact","email":"joe.smith@gmail.com"}],"subject":"My subject","body":"<div>My HTML body</div>"}}'
Successful email draft creation response:
{
"id":171,
"from":"Tom Smith <tom.smith@karmacrm.com>",
"subject":"My subject",
"body":"<div>My HTML body</div>",
"to":[{"type":"Contact",
"id":5,
"label":"John Smith",
"email":"jonh.smith@gmail.com"}],
"cc":[{"type":"Contact",
"id":46,
"email":"jane.smith@gmail.com"}],
"bcc":[{"type":"Contact",
"id":22,
"email":"joe.smith@gmail.com"}],
"email_template_id":null,
"authorization_id":1,
"created_by_id":4,
"organization_id":2,
"created_at":"2019-06-05T12:31:54Z",
"updated_at":"2019-06-05T12:31:54Z",
"attachments":[]
}
This endpoint creates an email draft
HTTP Request
POST https://app.karmacrm.com/api/v3/mailman_nylas/outgoing/messages/create_draft.json
URL Parameters
| Parameter | Description |
|---|---|
| api_token | The token to authenticate request |
Request Payload
| Parameter | Description |
|---|---|
| message[to] | array of 'to' recipients i.e. {"label": "John Smith","type":"Contact","email":"john.smith@gmail.com""id":5} |
| message[cc] | array of 'cc' recipients i.e. {"type":"Contact","email":"john.smith@gmail.com""id":5} |
| message[bcc] | array of 'bcc' recipients i.e. {"type":"Contact","email":"john.smith@gmail.com""id":5} |
| message[authorization_id] | authorization id of sender (user) |
| message[subject] | Email subject |
| message[body] | Email body |
Update an Email (and optionally sends later)
curl "https://app.karmacrm.com/api/v3/mailman_nylas/outgoing/messages/173.json?api_token=oGscoGFsdS54mProUdDz" \
-X PUT \
-H "Content-Type: application/json" \
-d '{"message":{"to":[{"id":5,"type":"Contact","label":"John Smith","email":"john.smith@gmail.com"}],"subject":"My updated subject","body":"<div>My updated HTML body</div>","reminders":[{"time_increment":"2","interval":"days","reminder_type_id":4}],"cc":[{"id":"46","type":"Contact","email":"jane.smith@gmail.com"}],"bcc":[{"id":"22","type":"Contact","email":"joe.smith@gmail.com"}],"deliver_at":"2019-06-05T08:56:41-06:00"}}'
This endpoint updates a specific outgoing email draft.
HTTP Request
PUT https://app.karmacrm.com/api/v3/mailman_nylas/outgoing/messages/<ID>.json
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the contact to delete |
| api_token | The token to authenticate request |
Request Payload
| Parameter | Description |
|---|---|
| message[to] | array of 'to' recipients i.e. {"label": "John Smith","type":"Contact","email":"john.smith@gmail.com""id":5} |
| message[cc] | array of 'cc' recipients i.e. {"type":"Contact","email":"john.smith@gmail.com""id":5} |
| message[bcc] | array of 'bcc' recipients i.e. {"type":"Contact","email":"john.smith@gmail.com""id":5} |
| message[authorization_id] | authorization id of sender (user) |
| message[subject] | Email subject |
| message[body] | Email body |
| message[reminders] | array of reminders i.e. {"time_increment":"2","interval":"days""reminder_type_id":4} |
| message[deliver_at] | optional time to send email at i.e. 2019-06-05T08:56:41-06:00 |
Response Code
| Code | Description |
|---|---|
| 204 | No content |
Update and Deliver Email (Now)
curl "https://app.karmacrm.com/api/v3/mailman_nylas/outgoing/messages/173/update_and_deliver.json?api_token=oGscoGFsdS54mProUdDz" \
-X PUT \
-H "Content-Type: application/json" \
-d '{"message":{"to":[{"id":5,"type":"Contact","label":"John Smith","email":"john.smith@gmail.com"}],"subject":"My updated subject","body":"<div>My updated HTML body</div>","reminders":[{"time_increment":"2","interval":"days","reminder_type_id":4}],"cc":[{"id":"46","type":"Contact","email":"jane.smith@gmail.com"}],"bcc":[{"id":"22","type":"Contact","email":"joe.smith@gmail.com"}]}}'
This endpoint updates and delivers messages.
HTTP Request
PUT https://app.karmacrm.com/api/v3/mailman_nylas/outgoing/messages/<ID>/update_and_deliver.json
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the contact to delete |
| api_token | The token to authenticate request |
Request Payload
| Parameter | Description |
|---|---|
| message[to] | array of 'to' recipients i.e. {"label": "John Smith","type":"Contact","email":"john.smith@gmail.com""id":5} |
| message[cc] | array of 'cc' recipients i.e. {"type":"Contact","email":"john.smith@gmail.com""id":5} |
| message[bcc] | array of 'bcc' recipients i.e. {"type":"Contact","email":"john.smith@gmail.com""id":5} |
| message[authorization_id] | authorization id of sender (user) |
| message[subject] | Email subject |
| message[body] | Email body |
| message[reminders] | array of reminders i.e. {"time_increment":"2","interval":"days""reminder_type_id":4} |
Response Code
| Code | Description |
|---|---|
| 204 | No content |
Delete an Email Draft
curl "https://app.karmacrm.com/api/v3/mailman_nylas/outgoing/messages/172.json?api_token=oGscoGFsdS54mProUdDz"
-X DELETE \
-H "Content-Type: application/json"
This endpoint deletes an email draft.
HTTP Request
DELETE https://app.karmacrm.com/api/v3/mailman_nylas/outgoing/messages/<ID>.json
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the contact to delete |
| api_token | The token to authenticate request |
Response Code
| Code | Description |
|---|---|
| 204 | No content |