NAV Navbar
shell

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
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":false
add 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
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