NAV
shell

Introduction

WELCOME!

You are currently viewing examples for Curl. You can use these examples to test the code in your terminal console.

Toggle examples for different languages with the selector above.

To get your environment setup to run each curl command, open a terminal and run...

export API_KEY=your_api_key
export API_SECRET=your_api_secret

The SalesforceIQ API is a full-featured, RESTful interface for interacting with the objects in our system. It allows you to make a lot of the reading and writing actions you would be able to make from inside the app.

Accessing Your Data

API requests are authorized with HTTP basic authentication consisting of an API Key and Secret. These are currently only available to certain SalesforceIQ plans. If you have API access, you can follow these instructions to generate your credentials.

Keep these credentials safe. We can’t regenerate the secret for you, so make sure it’s recorded somewhere. Failure to do so will result in having to deactivate the old integrations and rebuilding them with new credentials, and nobody wants that.

You’ll include these with every request, either directly or through one of our sdks (which handle the inclusion for you).

Requests

All requests use the root url of https://api.salesforceiq.com/v2. For each route, we support one or more of the following HTTP methods:

Responses

Each request is followed by a response in the form of a JSON object. Our sdk’s usually process this JSON into a more natural language structure (such as a Ruby hash). Hopefully, this response will include the data you wanted. Otherwise it will detail the error.

Errors

Error object structure

{
    "statusCode": "[INT] roughly corresponds to the matching HTTP error code",
    "userMessage": "A high level overview of the issue",
    "errorMessage": "A more specific description of the issue"
}

Sometimes, requests don’t work. When that happens, we respond with JSON that describes the nature of the problem. It will consist of three key pieces of information: Status Code (int), Message (String), Description (String).

The status code does its best to describe the issue you’re having.

Status Code Message Description
200 OK normal successful request
204 No Content successful request, but no content in the response payload
400 Bad Request missing or malformed parameter
401 Unauthorized missing credentials
403 Forbidden provided key does not have access for that method
404 Not Found requested object does not exist
422 Unprocessable Entity often the posted object is malformed
429 Too Many Requests exceeded rate limits
500 Server Error some sort of server issue
503 Service Unavailable likely a deploy is occurring, wait 2 minutes and retry

Rate Limits

Each API key is limited to a certain number of requests per day. Currently, the limit is 100k requests per calendar day. Any further requests will return error code 429 until the next day begins.

Object Model

Overview

Definition

# Account-based List


            ------------
            |   List   |
            ------------
                 |
                 |
                 |
           --------------
           | List Items |
           --------------
           /            \
          /              \
         /                \
        /                  \
  ------------        ------------
  | Contacts | ------ | Accounts |
  ------------        ------------
       |
       |
       |
  ------------
  |  Events  |
  ------------

# Contact-based List


      ------------
      |   List  |
      ------------
           |
           |
           |
     --------------
     | List Items |
     --------------
           |
           |
           |
      ------------        ------------
      | Contacts | ------ | Accounts |
      ------------        ------------
           |
           |
           |
      ------------
      |  Events  |
      ------------

To end users, everything in the SalesforceIQ UI is attributed to the List. The List name, list settings, the Stream and Grid View, and the relationsips/rows are all part of the List. In our backend, these components that make up a List are actually multiple objects within the system. For example, the rows on a List are actually instances of the List Item object. Accounts and Contacts are associated with those List Items and Stream Events are actually attributed to the Event Object instead of the List.

In the API, a List contains schema that defines the types of values that a List Item can have for each column. There are two types of Lists that define the structure of List Items: Account-based Lists and Contact-based Lists. A List can either be a Contact-based List or an Account-based List, but not both. Account-based Lists may have multiple Contacts (Points of Contact) associated with each List Item. Contact-based Lists may only have one Contact associated with each List Item.

To end users, we say that the List is where users will spend most of their time in SalesforceIQ. For the SalesforceIQ API, you will be spending most of your time handling List Items. List Items are rows on a List. At a high level, a List Item is a junction object between a Contact (person) or an Account (company) and a List.

Contacts also have a direct association with Accounts separate from List Items. To end users, this is reflected in the Account Profile section which showcases Account Contacts.

Events are objects that represent individual touch points with a Contact(s). Default events of the system are meetings, phone calls, and emails. The event object in the API is a separate event type that appears in the Stream View based on the Contact the event is associated with. The Contact needs to be associated to a particular List Item for the Event to show up in the Stream.

The User object represents an individual user of SalesforceIQ. Users are reflected in List Items as Owners or Collaborators of a Relationship.

What kind of information gets referenced?

All properties found on the Account Profile or Contact Profile are referenced. These can also be surfaced on the grid by adding fields under the Account or Contact section.

How do Accounts and Contacts get associated with List Items?

In the SalesforceIQ UI, you’re prompted to “Find or create an account” when you create a new List Item. By selecting an existing Account or creating a new one you associate an Account to a List Item. That association is reflected in the accountId property of the List Item.

Once you’ve associated an Account to a List Item, you’ll be prompted to associate Contacts (Points of Contact) to the List Item. Points of Contact are reflected in the contactIds property of the List Item. Additionally, the Contact is then directly associated to the Account which is reflected in the person_ids attribute under fieldValues for the Account Object.

For Contact-based Lists, you will only be prompted to “Find or create a Contact” when you create a new List Item.

What is the difference between Points of Contact tied to a List Item on an Accounts-based List vs. the Contacts linked to an Account in the Account Profile?

Points of Contact are a subset of the Account Contacts in the Account Profile page. In the SalesforceIQ UI, you can add a Contact to an Account without creating a List Item.

Field Datatypes

dataType Description
Contact This type of field stores a Contact within your SalesforceIQ Organization. The value stored is a contactID (Id for a Contact). To edit this type of field you can pass in the contactID or the contact’s email address.
Datetime This type of field stores a particular Date & Time in UTC milliseconds past the epoch.
Email This type of field stores an email address of a Contact. (Contact Object only)
File This type of field stores a file that gets uploaded via the web. The value stored is a Id of the file. (List Item Object only)
List This type of field stores a key which identifies the single select or multiselect list value. Passing in an invalid id for an option will return an error.
Location This type of field stores a full or individual component of an address.
Numeric This type of field stores a number. Passing in non-numeric characters will return an error.
Phone This type of field stores a phone number. (Contact Object only)
Text This type of field stores raw text.
Url This type of field stores a url. This field only appears for the LinkedIn URL Contact property. We only accept LinkedIn Profile URLs such as “https://www.linkedin.com/in/jmcsales” (Contact Object only)
User This type of field stores a User within your SalesforceIQ Organization. The value stored is a userID (Id for a User). To edit this type of field you can pass in the userID or the user’s email address.

Field Metadata Attributes

attribute Description
listOptions The listOptions property maps to an array of option objects, each containing an option id and the display value of that option. When setting the value of these types of fields, these list fields need to be set to this ID rather than their display value.
isMultiSelect Boolean value that determines whether a List field is a Single Select picklist or Mutli Select picklist.
isEditable Boolean value that determines whether a field can be updated.
isLinkedField Boolean value that determines whether the value of the field is populating from another field.

Lists

A List is an object that can be created and customized by a User to represent Accounts (companies) or Contacts (people) in a process (such as a sales pipeline). Each list has various Fields (columns) associated with them.

A List Item is a relationship within your lists and are represented as a row in your SalesforceIQ list. Each List Item has values associated with the Fields (columns) called Field Values. For more information about List Items, go to this section.

A List can either be a Contact-based List or an Account-based List, but not both. Account-based Lists may have multiple Contacts (Points of Contact) associated with each List Item. Contact-based Lists may only have one Contact associated with each List Item.

The List endpoint provides metadata for the list (id, title, listType) including an array of field objects with corresponding field metadata (id, name, dataType etc.). Use this endpoint to intepret the Field Values of List Items.

Additionally, use this endpoint to retrieve the appropriate listOption ids if you are trying to interpret or update list-type or picklist-type fields.

List Object

Definition

# Contact-based List
{
  "id": "56f087b0e4b0584aa39fbba8",
  "title": "Leads",
  "listType": "contact",
  "modifiedDate": 0,
  "fields": [
    {
      "id": "led",
      "name": "Last Event Date (sort)",
      "listOptions": [],
      "isMultiSelect": false,
      "isEditable": true,
      "isLinkedField": false,
      "dataType": "DateTime"
    },
    {
      "id": "process_created_date",
      "name": "Created Date",
      "listOptions": [],
      "isMultiSelect": false,
      "isEditable": true,
      "isLinkedField": false,
      "dataType": "DateTime"
    },
    {
      "id": "0",
      "name": "Status",
      "listOptions": [
        {
          "id": "0",
          "display": "Lead"
        },
        {
          "id": "1",
          "display": "Qualified"
        },
        {
          "id": "2",
          "display": "Negotiation"
        },
        {
          "id": "3",
          "display": "Verbal Commitment"
        },
        {
          "id": "4",
          "display": "Deal Won"
        },
        {
          "id": "5",
          "display": "Revisit Later"
        },
        {
          "id": "6",
          "display": "Deal Lost"
        }
      ],
      "isMultiSelect": false,
      "isEditable": true,
      "isLinkedField": false,
      "dataType": "List"
    },
    {
      "id": "process_close_date",
      "name": "Close Date",
      "listOptions": [],
      "isMultiSelect": false,
      "isEditable": true,
      "isLinkedField": false,
      "dataType": "DateTime"
    },
    {
      "id": "3",
      "name": "Revenue",
      "listOptions": [],
      "isMultiSelect": false,
      "isEditable": true,
      "isLinkedField": false,
      "dataType": "Numeric"
    },
    {
      "id": "1",
      "name": "Owner",
      "listOptions": [],
      "isMultiSelect": false,
      "isEditable": true,
      "isLinkedField": false,
      "dataType": "User"
    },
    {
      "id": "6",
      "name": "Contract",
      "listOptions": [],
      "isMultiSelect": false,
      "isEditable": true,
      "isLinkedField": false,
      "dataType": "File"
    },
    {
      "id": "7",
      "name": "Products",
      "listOptions": [
        {
          "id": "0",
          "display": "Aria"
        },
        {
          "id": "1",
          "display": "Charge"
        },
        {
          "id": "2",
          "display": "Charge HR"
        },
        {
          "id": "3",
          "display": "Blaze"
        }
      ],
      "isMultiSelect": true,
      "isEditable": true,
      "isLinkedField": false,
      "dataType": "List"
    },
    {
      "id": "9",
      "name": "Phone",
      "listOptions": [],
      "isMultiSelect": true,
      "isEditable": false,
      "isLinkedField": true,
      "dataType": "Phone"
    },
    {
      "id": "8",
      "name": "LinkedIn URL",
      "listOptions": [],
      "isMultiSelect": false,
      "isEditable": false,
      "isLinkedField": true,
      "dataType": "LinkedIn"
    },
    {
      "id": "10",
      "name": "Current Company",
      "listOptions": [],
      "isMultiSelect": false,
      "isEditable": false,
      "isLinkedField": true,
      "dataType": "Text"
    },
    {
      "id": "12",
      "name": "Referer",
      "listOptions": [],
      "isMultiSelect": false,
      "isEditable": true,
      "isLinkedField": false,
      "dataType": "Contact"
    },
    {
      "id": "14",
      "name": "Notes",
      "listOptions": [],
      "isMultiSelect": false,
      "isEditable": true,
      "isLinkedField": false,
      "dataType": "Text"
    }
  ],
  "size": 0
}

# Account-based list
{
  "id": "56f1b185e4b0d37eabe8c2b0",
  "title": "Customers",
  "listType": "account",
  "modifiedDate": 0,
  "fields": [
    {
      "id": "1",
      "name": "Owner",
      "listOptions": [],
      "isMultiSelect": false,
      "isEditable": true,
      "isLinkedField": false,
      "dataType": "User"
    },
    {
      "id": "0",
      "name": "Status",
      "listOptions": [
        {
          "id": "0",
          "display": "Lead"
        },
        {
          "id": "1",
          "display": "Qualified"
        },
        {
          "id": "2",
          "display": "Negotiation"
        },
        {
          "id": "3",
          "display": "Verbal Commitment"
        },
        {
          "id": "4",
          "display": "Deal Won"
        },
        {
          "id": "5",
          "display": "Revisit Later"
        },
        {
          "id": "6",
          "display": "Deal Lost"
        }
      ],
      "isMultiSelect": false,
      "isEditable": true,
      "isLinkedField": false,
      "dataType": "List"
    },
    {
      "id": "process_close_date",
      "name": "Close Date",
      "listOptions": [],
      "isMultiSelect": false,
      "isEditable": true,
      "isLinkedField": false,
      "dataType": "DateTime"
    },
    {
      "id": "process_created_date",
      "name": "Created Date",
      "listOptions": [],
      "isMultiSelect": false,
      "isEditable": true,
      "isLinkedField": false,
      "dataType": "DateTime"
    },
    {
      "id": "3",
      "name": "Revenue",
      "listOptions": [],
      "isMultiSelect": false,
      "isEditable": true,
      "isLinkedField": false,
      "dataType": "Numeric"
    },
    {
      "id": "led",
      "name": "Last Event Date (sort)",
      "listOptions": [],
      "isMultiSelect": false,
      "isEditable": true,
      "isLinkedField": false,
      "dataType": "DateTime"
    }
  ],
  "size": 0
}
Parameter Type Description
id String Id, The List’s unique identifier within SalesforceIQ. ID’s are unique alphanumeric strings, 24 characters long.
modifiedDate Numeric The time this object was last modified, in UTC milliseconds past the epoch. This field is automatically updated by writing queries and not directly editable.
title String The title of the List as it will be displayed within SalesforceIQ.
listType String The type of relationships this list manages. Lists are either Contact-based lists which support only one Contact ID per List Item and no Account ID, or Account-based lists where each List Item has a mapped Account ID and one or more Contact IDs. For certain clients there is a legacy type ‘both’ which accepts either format, but this functionality has been deprecated for all new Lists and is no longer supported.
fields Object[] A collection of Field definitions that are associated with the List. These Fields are stored as an array of Field objects, with each Field a mapping of an id, display name, and (in the case of pick list fields) an array of listOptions. The Field’s id is a string containing the index of that field in the order they were created; these ids are used to map fields to their values within List Items. The listOptions property maps to an array of option objects, each containing an option id and the display value of that option. When setting the value of these types of fields, these list fields need to be set to this ID rather than their display value.

Get All Lists

Request

# Retrieve all Lists in your Organization
curl 'https://api.salesforceiq.com/v2/lists'
  -X GET
  -u $API_KEY:$API_SECRET
  -H 'Accept: application/json'

# Retrieve two Lists starting at index 1
curl 'https://api.salesforceiq.com/v2/lists?_start=1&_limit=2'
  -X GET
  -u $API_KEY:$API_SECRET
  -H 'Accept: application/json'

Response

# Retrieve all Lists in your Organization
HTTP/1.1 200 OK
{
  "objects": [
    {
      "id": "56f087b0e4b0584aa39fbba8",
      "title": "Leads",
      "listType": "contact",
      "modifiedDate": 0,
      "fields": [
        {
          "id": "led",
          "name": "Last Event Date (sort)",
          "listOptions": [],
          "isMultiSelect": false,
          "isEditable": true,
          "isLinkedField": false,
          "dataType": "DateTime"
        },
        {
          "id": "process_created_date",
          "name": "Created Date",
          "listOptions": [],
          "isMultiSelect": false,
          "isEditable": true,
          "isLinkedField": false,
          "dataType": "DateTime"
        },
        {
          "id": "0",
          "name": "Status",
          "listOptions": [
            {
              "id": "0",
              "display": "Lead"
            },
            {
              "id": "1",
              "display": "Qualified"
            },
            {
              "id": "2",
              "display": "Negotiation"
            },
            {
              "id": "3",
              "display": "Verbal Commitment"
            },
            {
              "id": "4",
              "display": "Deal Won"
            },
            {
              "id": "5",
              "display": "Revisit Later"
            },
            {
              "id": "6",
              "display": "Deal Lost"
            }
          ],
          "isMultiSelect": false,
          "isEditable": true,
          "isLinkedField": false,
          "dataType": "List"
        },
        {
          "id": "process_close_date",
          "name": "Close Date",
          "listOptions": [],
          "isMultiSelect": false,
          "isEditable": true,
          "isLinkedField": false,
          "dataType": "DateTime"
        },
        {
          "id": "3",
          "name": "Revenue",
          "listOptions": [],
          "isMultiSelect": false,
          "isEditable": true,
          "isLinkedField": false,
          "dataType": "Numeric"
        },
        {
          "id": "1",
          "name": "Owner",
          "listOptions": [],
          "isMultiSelect": false,
          "isEditable": true,
          "isLinkedField": false,
          "dataType": "User"
        },
        {
          "id": "6",
          "name": "Contract",
          "listOptions": [],
          "isMultiSelect": false,
          "isEditable": true,
          "isLinkedField": false,
          "dataType": "File"
        },
        {
          "id": "7",
          "name": "Products",
          "listOptions": [
            {
              "id": "0",
              "display": "Aria"
            },
            {
              "id": "1",
              "display": "Charge"
            },
            {
              "id": "2",
              "display": "Charge HR"
            },
            {
              "id": "3",
              "display": "Blaze"
            }
          ],
          "isMultiSelect": true,
          "isEditable": true,
          "isLinkedField": false,
          "dataType": "List"
        },
        {
          "id": "9",
          "name": "Phone",
          "listOptions": [],
          "isMultiSelect": true,
          "isEditable": false,
          "isLinkedField": true,
          "dataType": "Phone"
        },
        {
          "id": "8",
          "name": "LinkedIn URL",
          "listOptions": [],
          "isMultiSelect": false,
          "isEditable": false,
          "isLinkedField": true,
          "dataType": "LinkedIn"
        },
        {
          "id": "10",
          "name": "Current Company",
          "listOptions": [],
          "isMultiSelect": false,
          "isEditable": false,
          "isLinkedField": true,
          "dataType": "Text"
        },
        {
          "id": "12",
          "name": "Referer",
          "listOptions": [],
          "isMultiSelect": false,
          "isEditable": true,
          "isLinkedField": false,
          "dataType": "Contact"
        },
        {
          "id": "14",
          "name": "Notes",
          "listOptions": [],
          "isMultiSelect": false,
          "isEditable": true,
          "isLinkedField": false,
          "dataType": "Text"
        }
      ],
      "size": 0
    },
    {
      "id": "56f1b185e4b0d37eabe8c2b0",
      "title": "Customers",
      "listType": "account",
      "modifiedDate": 0,
      "fields": [
        {
          "id": "1",
          "name": "Owner",
          "listOptions": [],
          "isMultiSelect": false,
          "isEditable": true,
          "isLinkedField": false,
          "dataType": "User"
        },
        {
          "id": "0",
          "name": "Status",
          "listOptions": [
            {
              "id": "0",
              "display": "Lead"
            },
            {
              "id": "1",
              "display": "Qualified"
            },
            {
              "id": "2",
              "display": "Negotiation"
            },
            {
              "id": "3",
              "display": "Verbal Commitment"
            },
            {
              "id": "4",
              "display": "Deal Won"
            },
            {
              "id": "5",
              "display": "Revisit Later"
            },
            {
              "id": "6",
              "display": "Deal Lost"
            }
          ],
          "isMultiSelect": false,
          "isEditable": true,
          "isLinkedField": false,
          "dataType": "List"
        },
        {
          "id": "process_close_date",
          "name": "Close Date",
          "listOptions": [],
          "isMultiSelect": false,
          "isEditable": true,
          "isLinkedField": false,
          "dataType": "DateTime"
        },
        {
          "id": "process_created_date",
          "name": "Created Date",
          "listOptions": [],
          "isMultiSelect": false,
          "isEditable": true,
          "isLinkedField": false,
          "dataType": "DateTime"
        },
        {
          "id": "3",
          "name": "Revenue",
          "listOptions": [],
          "isMultiSelect": false,
          "isEditable": true,
          "isLinkedField": false,
          "dataType": "Numeric"
        },
        {
          "id": "led",
          "name": "Last Event Date (sort)",
          "listOptions": [],
          "isMultiSelect": false,
          "isEditable": true,
          "isLinkedField": false,
          "dataType": "DateTime"
        }
      ],
      "size": 0
    },
    {
      "id": "5672e3b8e4b071e7d1c0b100",
      "title": "Opportunities",
      "listType": "account",
      "modifiedDate": 0,
      "fields": [
        {
          "id": "0",
          "name": "Status",
          "listOptions": [
            {
              "id": "0",
              "display": "Identifying Opportunity"
            },
            {
              "id": "1",
              "display": "Determining Problem, Impact, Ideal"
            },
            {
              "id": "2",
              "display": "Negotiation"
            },
            {
              "id": "3",
              "display": "Verbal Commitment"
            },
            {
              "id": "4",
              "display": "Deal Won"
            },
            {
              "id": "5",
              "display": "Revisit Later"
            },
            {
              "id": "6",
              "display": "Deal Lost"
            }
          ],
          "isMultiSelect": false,
          "isEditable": true,
          "isLinkedField": false,
          "dataType": "List"
        },
        {
          "id": "process_close_date",
          "name": "Close Date",
          "listOptions": [],
          "isMultiSelect": false,
          "isEditable": true,
          "isLinkedField": false,
          "dataType": "DateTime"
        },
        {
          "id": "3",
          "name": "Revenue",
          "listOptions": [],
          "isMultiSelect": false,
          "isEditable": true,
          "isLinkedField": false,
          "dataType": "Numeric"
        },
        {
          "id": "led",
          "name": "Last Event Date (sort)",
          "listOptions": [],
          "isMultiSelect": false,
          "isEditable": true,
          "isLinkedField": false,
          "dataType": "DateTime"
        },
        {
          "id": "1",
          "name": "Owner",
          "listOptions": [],
          "isMultiSelect": false,
          "isEditable": true,
          "isLinkedField": false,
          "dataType": "User"
        },
        {
          "id": "process_created_date",
          "name": "Created Date",
          "listOptions": [],
          "isMultiSelect": false,
          "isEditable": true,
          "isLinkedField": false,
          "dataType": "DateTime"
        },
        {
          "id": "6",
          "name": "Inactive (days)",
          "listOptions": [],
          "isMultiSelect": false,
          "isEditable": false,
          "isLinkedField": false,
          "dataType": "Numeric"
        },
        {
          "id": "25",
          "name": "All Time (events)",
          "listOptions": [],
          "isMultiSelect": false,
          "isEditable": false,
          "isLinkedField": false,
          "dataType": "Numeric"
        }
      ],
      "size": 0
    }
  ],
  "nextPage": null
}

# Retrieve two Lists starting at index 1
HTTP/1.1 200 OK
{ 
  "objects": [
    {
      "id": "56f1b185e4b0d37eabe8c2b0",
      "title": "Customers",
      "listType": "account",
      "modifiedDate": 0,
      "fields": [
        {
          "id": "1",
          "name": "Owner",
          "listOptions": [],
          "isMultiSelect": false,
          "isEditable": true,
          "isLinkedField": false,
          "dataType": "User"
        },
        {
          "id": "0",
          "name": "Status",
          "listOptions": [
            {
              "id": "0",
              "display": "Lead"
            },
            {
              "id": "1",
              "display": "Qualified"
            },
            {
              "id": "2",
              "display": "Negotiation"
            },
            {
              "id": "3",
              "display": "Verbal Commitment"
            },
            {
              "id": "4",
              "display": "Deal Won"
            },
            {
              "id": "5",
              "display": "Revisit Later"
            },
            {
              "id": "6",
              "display": "Deal Lost"
            }
          ],
          "isMultiSelect": false,
          "isEditable": true,
          "isLinkedField": false,
          "dataType": "List"
        },
        {
          "id": "process_close_date",
          "name": "Close Date",
          "listOptions": [],
          "isMultiSelect": false,
          "isEditable": true,
          "isLinkedField": false,
          "dataType": "DateTime"
        },
        {
          "id": "process_created_date",
          "name": "Created Date",
          "listOptions": [],
          "isMultiSelect": false,
          "isEditable": true,
          "isLinkedField": false,
          "dataType": "DateTime"
        },
        {
          "id": "3",
          "name": "Revenue",
          "listOptions": [],
          "isMultiSelect": false,
          "isEditable": true,
          "isLinkedField": false,
          "dataType": "Numeric"
        },
        {
          "id": "led",
          "name": "Last Event Date (sort)",
          "listOptions": [],
          "isMultiSelect": false,
          "isEditable": true,
          "isLinkedField": false,
          "dataType": "DateTime"
        }
      ],
      "size": 0
    },
    {
      "id": "5672e3b8e4b071e7d1c0b100",
      "title": "Opportunities",
      "listType": "account",
      "modifiedDate": 0,
      "fields": [
        {
          "id": "0",
          "name": "Status",
          "listOptions": [
            {
              "id": "0",
              "display": "Identifying Opportunity"
            },
            {
              "id": "1",
              "display": "Determining Problem, Impact, Ideal"
            },
            {
              "id": "2",
              "display": "Negotiation"
            },
            {
              "id": "3",
              "display": "Verbal Commitment"
            },
            {
              "id": "4",
              "display": "Deal Won"
            },
            {
              "id": "5",
              "display": "Revisit Later"
            },
            {
              "id": "6",
              "display": "Deal Lost"
            }
          ],
          "isMultiSelect": false,
          "isEditable": true,
          "isLinkedField": false,
          "dataType": "List"
        },
        {
          "id": "process_close_date",
          "name": "Close Date",
          "listOptions": [],
          "isMultiSelect": false,
          "isEditable": true,
          "isLinkedField": false,
          "dataType": "DateTime"
        },
        {
          "id": "3",
          "name": "Revenue",
          "listOptions": [],
          "isMultiSelect": false,
          "isEditable": true,
          "isLinkedField": false,
          "dataType": "Numeric"
        },
        {
          "id": "led",
          "name": "Last Event Date (sort)",
          "listOptions": [],
          "isMultiSelect": false,
          "isEditable": true,
          "isLinkedField": false,
          "dataType": "DateTime"
        },
        {
          "id": "1",
          "name": "Owner",
          "listOptions": [],
          "isMultiSelect": false,
          "isEditable": true,
          "isLinkedField": false,
          "dataType": "User"
        },
        {
          "id": "process_created_date",
          "name": "Created Date",
          "listOptions": [],
          "isMultiSelect": false,
          "isEditable": true,
          "isLinkedField": false,
          "dataType": "DateTime"
        },
        {
          "id": "6",
          "name": "Inactive (days)",
          "listOptions": [],
          "isMultiSelect": false,
          "isEditable": false,
          "isLinkedField": false,
          "dataType": "Numeric"
        },
        {
          "id": "25",
          "name": "All Time (events)",
          "listOptions": [],
          "isMultiSelect": false,
          "isEditable": false,
          "isLinkedField": false,
          "dataType": "Numeric"
        }
      ],
      "size": 0
    }
  ],
  "nextPage": null
}

GET /lists

Retrieve a paginated collection of all Lists in your Organization.

Query Parameters

Parameter Type Required Description
_ids String[] false An optional, comma separated list of List identifiers.
_start Numeric false An optional starting point for the returned page of records (defaults to 0). If you start at 5 you will retrieve records starting at the index 6 to your _limit.
_limit Numeric false An optional page size for the returned result (defaults to 50, max size is 200).

Get a Single List

Request

curl 'https://api.salesforceiq.com/v2/lists/56f087b0e4b0584aa39fbba8'
  -X GET
  -u $API_KEY:$API_SECRET
  -H 'Accept: application/json'

Response

{
  "id": "56f087b0e4b0584aa39fbba8",
  "title": "Leads",
  "listType": "contact",
  "modifiedDate": 0,
  "fields": [
    {
      "id": "led",
      "name": "Last Event Date (sort)",
      "listOptions": [],
      "isMultiSelect": false,
      "isEditable": true,
      "isLinkedField": false,
      "dataType": "DateTime"
    },
    {
      "id": "process_created_date",
      "name": "Created Date",
      "listOptions": [],
      "isMultiSelect": false,
      "isEditable": true,
      "isLinkedField": false,
      "dataType": "DateTime"
    },
    {
      "id": "0",
      "name": "Status",
      "listOptions": [
        {
          "id": "0",
          "display": "Lead"
        },
        {
          "id": "1",
          "display": "Qualified"
        },
        {
          "id": "2",
          "display": "Negotiation"
        },
        {
          "id": "3",
          "display": "Verbal Commitment"
        },
        {
          "id": "4",
          "display": "Deal Won"
        },
        {
          "id": "5",
          "display": "Revisit Later"
        },
        {
          "id": "6",
          "display": "Deal Lost"
        }
      ],
      "isMultiSelect": false,
      "isEditable": true,
      "isLinkedField": false,
      "dataType": "List"
    },
    {
      "id": "process_close_date",
      "name": "Close Date",
      "listOptions": [],
      "isMultiSelect": false,
      "isEditable": true,
      "isLinkedField": false,
      "dataType": "DateTime"
    },
    {
      "id": "3",
      "name": "Revenue",
      "listOptions": [],
      "isMultiSelect": false,
      "isEditable": true,
      "isLinkedField": false,
      "dataType": "Numeric"
    },
    {
      "id": "1",
      "name": "Owner",
      "listOptions": [],
      "isMultiSelect": false,
      "isEditable": true,
      "isLinkedField": false,
      "dataType": "User"
    },
    {
      "id": "6",
      "name": "Contract",
      "listOptions": [],
      "isMultiSelect": false,
      "isEditable": true,
      "isLinkedField": false,
      "dataType": "File"
    },
    {
      "id": "7",
      "name": "Products",
      "listOptions": [
        {
          "id": "0",
          "display": "Aria"
        },
        {
          "id": "1",
          "display": "Charge"
        },
        {
          "id": "2",
          "display": "Charge HR"
        },
        {
          "id": "3",
          "display": "Blaze"
        }
      ],
      "isMultiSelect": true,
      "isEditable": true,
      "isLinkedField": false,
      "dataType": "List"
    },
    {
      "id": "9",
      "name": "Phone",
      "listOptions": [],
      "isMultiSelect": true,
      "isEditable": false,
      "isLinkedField": true,
      "dataType": "Phone"
    },
    {
      "id": "8",
      "name": "LinkedIn URL",
      "listOptions": [],
      "isMultiSelect": false,
      "isEditable": false,
      "isLinkedField": true,
      "dataType": "LinkedIn"
    },
    {
      "id": "10",
      "name": "Current Company",
      "listOptions": [],
      "isMultiSelect": false,
      "isEditable": false,
      "isLinkedField": true,
      "dataType": "Text"
    },
    {
      "id": "12",
      "name": "Referer",
      "listOptions": [],
      "isMultiSelect": false,
      "isEditable": true,
      "isLinkedField": false,
      "dataType": "Contact"
    },
    {
      "id": "14",
      "name": "Notes",
      "listOptions": [],
      "isMultiSelect": false,
      "isEditable": true,
      "isLinkedField": false,
      "dataType": "Text"
    }
  ],
  "size": 0
}

GET /lists/{id}

A GET request which fetches a single List by its unique identifier.

Query Parameters

Parameter Type Required Description
id String true Id for the List to be fetched.

List Items

A List Item is a row in a List. You can think about a List Item as a Contact (person) or an Account (company) who is being actively tracked as part of a List (process).

For example, your Organization may have a List of several sales leads. Each row (List Item/Relationship) in the List represents a lead. Each column describes an attribute of that lead (Field Values).

Any User who has access to edit List properties (depending on your admin controls) can create custom List fields through the UI. If you need to add a field to a List and you don’t have UI access, please contact an admin in your Organization.

Any changes to List Item status or other reportable fields in the List schema will be reflected in reporting.

List Item Object

Definition

# Contact-based List Item
{
  "id": "56f1b645e4b0d37eabea22b0",
  "listId": "56f087b0e4b0584aa39fbba8",
  "version": 1,
  "createdDate": 1458681413000,
  "modifiedDate": 1458681413814,
  "name": "Cecilia Avocado",
  "accountId": null,
  "contactIds": [
    "56b12644e4b08b67fd722d75"
  ],
  "fieldValues": {
    "0": [ { "raw": "0" } ],
    "1": [ { "raw": "56155a21e4b0fee51b1cb043" } ],
    "8": [ { "raw": "http://linkedin.com/test" } ],
    "9": [ 
      { "raw": "+14152990341" }, 
      { "raw": "+15103139867" }
    ],
    "10": [ { "raw": "Avocado, Inc." } ],
    "process_close_date": [ { "raw": "1461273413819" } ],
    "process_created_date": [ { "raw": "1458681413819" } ]
  },
  "linkedItemIds": {
    "5660e898e4b08148fc41667f.contacts": [ { "itemId": "56b12644e4b08b67fd722d75" } ]
  }
}

# Account-based List Item
{
  "id": "56f1b20ee4b0d37eabe8e15f",
  "listId": "56f1b185e4b0d37eabe8c2b0",
  "version": 1,
  "createdDate": 1458680334000,
  "modifiedDate": 1458680509693,
  "name": "Avocado, Inc.",
  "accountId": "56abd666e4b07f4066b7bcdc",
  "contactIds": [
    "56f1b2a8e4b0d37eabe91b9d",
    "56b12644e4b08b67fd722d75"
  ],
  "fieldValues": {
    "0": [ { "raw": "0" } ],
    "1": [ { "raw": "56155a21e4b0fee51b1cb043" } ],
    "process_close_date": [ { "raw": "1461272334831" } ],
    "process_created_date": [ { "raw": "1458680334831" } ]
  },
  "linkedItemIds": {}
}
Parameter Type Description
id String Id, The List Item’s unique identifier within SalesforceIQ. ID’s are unique alphanumeric strings, 24 characters long.
modifiedDate Numeric The time this object was last modified, in UTC milliseconds past the epoch. This field is automatically updated by writing queries and not directly editable.
createdDate Numeric The time this object was originally added to the List, in UTC milliseconds past the epoch. This field is automatically set when the entry is created and not directly editable.
listId String Id for the List to which this List Item belongs. ID’s are unique alphanumeric strings, 24 characters long.
accountId String If this is on an Account List, this field will store the unique identifier for the Account tied to this entry. Otherwise it will be unused.
contactIds String[] This field will store an array of Contact identifiers associated with this entry if it is an Account List, or the single Contact for the entry if it is a Contact List.
name String List Items can have a separate display name within the list to differentiate the entry or add more information about that item. If this value is not defined, the name displayed will correspond to the type of List - using the Account’s name if it is an Account based List, otherwise using the Contact’s name.
fieldValues String[] A collection of Field definitions that are associated with the List. These Fields are stored as an array of Field objects, with each Field a mapping of an id, display name, and (in the case of pick list fields) an array of listOptions. The Field’s id is a string containing the index of that field in the order they were created; these ids are used to map fields to their values within List Items. The listOptions property maps to an array of option objects, each containing an option id and the display value of that option. When setting the value of these types of fields, these list fields need to be set to this ID rather than their display value.
linkedItemIds Object This field linkedItemIds are used when linking data from other lists, accounts, or integrations into a particular list. This functionality will be expanded upon in a later release.

Create a List Item

Request

# Contact-based List
curl 'https://api.salesforceiq.com/v2/lists/56f087b0e4b0584aa39fbba8/listitems'
  -X POST
  -u $API_KEY:$API_SECRET
  -H 'Content-Type: application/json'
  -H 'Accept: application/json'
  -d '{
        "contactIds": ["56f1b2a8e4b0d37eabe91b9d"],
        "fieldValues": {
            "0": [ { "raw": "1" } ],
            "1": [ { "raw": "jmcsales@gmail.com" } ],
            "3": [ { "raw": "1500" } ],      
            "7": [ { "raw": "1" }, { "raw": "3" } ],
            "12": [ { "raw": "t.minutes@modelminutes.com" } ],
            "14": [ { "raw": "Hello World" }],
            "process_close_date": [ { "raw": "1558685591983" }]
        }
      }'

# Account-based List
curl 'https://api.salesforceiq.com/v2/lists/56f1b185e4b0d37eabe8c2b0/listitems'
  -X POST
  -u $API_KEY:$API_SECRET
  -H 'Content-Type: application/json'
  -H 'Accept: application/json'
  -d '{
        "name": "Avocado, Inc.",
        "accountId": "56abd666e4b07f4066b7bcdc",
        "contactIds": [
            "56b12644e4b08b67fd722d75",
            "56f1b2a8e4b0d37eabe91b9d"
        ],
        "fieldValues": {
            "0": [ { "raw": "4" } ],
            "1": [ { "raw": "jmcsales@gmail.com" } ],
            "3": [ { "raw": "2500" } ],
            "process_close_date": [ { "raw": "1558685591983" }]
        }
      }'

Response

# Contact-based List
HTTP/1.1 200 OK
{
  "id": "56f1dcefe4b047357c2c03e6",
  "listId": "56f087b0e4b0584aa39fbba8",
  "version": 1,
  "createdDate": 1458691311000,
  "modifiedDate": 1458691311848,
  "name": "John Clam",
  "accountId": null,
  "contactIds": [ "56f1b2a8e4b0d37eabe91b9d" ],
  "fieldValues": {
    "0": [ { "raw": "1" } ],
    "1": [ { "raw": "56155a21e4b0fee51b1cb043" } ],
    "3": [ { "raw": "1500" } ],
    "7": [ 
      { "raw": "1" },
      { "raw": "3" }
    ],
    "12": [ { "raw": "56df75a4e4b03009e48e8e76" } ],
    "14": [ { "raw": "Hello World" } ],
    "process_close_date": [ { "raw": "1558685591983" } ],
    "process_created_date": [ { "raw": "1458691311706" } ]
  },
  "linkedItemIds": {
    "5660e898e4b08148fc41667f.contacts": [
      { "itemId": "56f1b2a8e4b0d37eabe91b9d" }
    ]
  }
}

# Account-based List
HTTP/1.1 200 OK
{
  "id": "56f1db4be4b0336869dce48f",
  "listId": "56f1b185e4b0d37eabe8c2b0",
  "version": 1,
  "createdDate": 1458690891000,
  "modifiedDate": 1458690891433,
  "name": "Avocado, Inc.",
  "accountId": "56abd666e4b07f4066b7bcdc",
  "contactIds": [
    "56b12644e4b08b67fd722d75",
    "56f1b2a8e4b0d37eabe91b9d"
  ],
  "fieldValues": {
    "0": [ { "raw": "4" } ],
    "1": [ { "raw": "56155a21e4b0fee51b1cb043" } ],
    "3": [ { "raw": "2500" } ],
    "process_close_date": [ { "raw": "1558685591983" } ],
    "process_created_date": [ { "raw": "1458690891320" } ]
  },
  "linkedItemIds": {}
}

POST /lists/{listId}/listitems

A POST request which creates a new List Item object and returns the created List Item with it’s new ID.

For Contact-based Lists, at least one contactId is required.

Query Parameters

Parameter Type Required Description
listId String true The unique identifier for the List where the List Item should be created.

Payload

Parameter Type Required Description
newListItem Object true A JSON representation of a List Item, without the id, modifiedDate, or createdDate fields (which will be generated on creation).

Get a Single List Item

Request

curl 'https://api.salesforceiq.com/v2/lists/56f087b0e4b0584aa39fbba8/listitems/56f1dcefe4b047357c2c03e6'
  -X GET
  -u $API_KEY:$API_SECRET
  -H 'Content-Type: application/json'

Response

HTTP/1.1 200 OK
{
  "id": "56f1dcefe4b047357c2c03e6",
  "listId": "56f087b0e4b0584aa39fbba8",
  "version": 1,
  "createdDate": 1458691311000,
  "modifiedDate": 1458691311848,
  "name": "John Clam",
  "accountId": null,
  "contactIds": [ "56f1b2a8e4b0d37eabe91b9d" ],
  "fieldValues": {
    "0": [ { "raw": "1" } ],
    "1": [ { "raw": "56155a21e4b0fee51b1cb043" } ],
    "3": [ { "raw": "1500" } ],
    "7": [ 
      { "raw": "1" },
      { "raw": "3" }
    ],
    "12": [ { "raw": "56df75a4e4b03009e48e8e76" } ],
    "14": [ { "raw": "Hello World" } ],
    "process_close_date": [ { "raw": "1558685591983" } ],
    "process_created_date": [ { "raw": "1458691311706" } ]
  },
  "linkedItemIds": {
    "5660e898e4b08148fc41667f.contacts": [
      { "itemId": "56f1b2a8e4b0d37eabe91b9d" }
    ]
  }
}

GET /lists/{listId}/listitems/{listItemId}

A GET request to a specified List which fetches a single List Item by it’s unique identifier.

Query Parameters

Parameter Type Required Description
listId String true Id for the List to be fetched.
listItemId String true Id for the List Item to be fetched.

Get All List Items

Request

# Request first 50 List Items on a List
curl 'https://api.salesforceiq.com/v2/lists/56f087b0e4b0584aa39fbba8/listitems'
  -X GET
  -u $API_KEY:$API_SECRET
  -H 'Content-Type: application/json'

# Request a set of List Items on a List based on an array of Ids
curl 'https://api.salesforceiq.com/v2/lists/56f087b0e4b0584aa39fbba8/listitems?_ids=56f1dcefe4b047357c2c03e6,56f1b645e4b0d37eabea22b0'
  -X GET
  -u $API_KEY:$API_SECRET
  -H 'Content-Type: application/json'

# Request List Items modified after 1458691311848
curl 'https://api.salesforceiq.com/v2/lists/56f087b0e4b0584aa39fbba8/listitems?modifiedDate=1458691311848'
  -X GET
  -u $API_KEY:$API_SECRET
  -H 'Content-Type: application/json'

# Request all List Items by contactIds (Account-based List)
curl 'https://api.salesforceiq.com/v2/lists/56f1b185e4b0d37eabe8c2b0/listitems?contactIds=56b12644e4b08b67fd722d75'
  -X GET
  -u $API_KEY:$API_SECRET
  -H 'Content-Type: application/json'

# Request all List Items by accountIds (Account-based List)
curl 'https://api.salesforceiq.com/v2/lists/56f1b185e4b0d37eabe8c2b0/listitems?accountIds=56abd666e4b07f4066b7bcdc'
  -X GET
  -u $API_KEY:$API_SECRET
  -H 'Content-Type: application/json'

# Paginating

# Retrieve the First Page
curl 'https://api.salesforceiq.com/v2/lists/56f087b0e4b0584aa39fbba8/listitems?_start=0&_limit=200'
  -X GET
  -u $API_KEY:$API_SECRET
  -H 'Content-Type: application/json'

# Retrieve the Second Page
curl 'https://api.salesforceiq.com/v2/lists/56f087b0e4b0584aa39fbba8/listitems?_start=200&_limit=200'
  -X GET
  -u $API_KEY:$API_SECRET
  -H 'Content-Type: application/json'

Response

HTTP/1.1 200 OK
{
  "totalSize": 0,
  "offset": 0,
  "limit": 0,
  "queryId": null,
  "objects": [
    {
      "id": "56f1b645e4b0d37eabea22b0",
      "listId": "56f087b0e4b0584aa39fbba8",
      "version": 2,
      "createdDate": 1458681413000,
      "modifiedDate": 1458685100530,
      "name": "Cecilia Avocado",
      "accountId": null,
      "contactIds": [ "56b12644e4b08b67fd722d75" ],
      "fieldValues": {
        "0": [ { "raw": "0" } ],
        "1": [ { "raw": "56155a21e4b0fee51b1cb043" } ],
        "6": [ { "raw": "03397194-1219-431c-a055-bc03a1d70cef" } ],
        "8": [ { "raw": "http://linkedin.com/in/cavocado" } ],
        "9": [ { "raw": "+14152990341" } ],
        "10": [ { "raw": "Avocado, Inc." } ],
        "process_close_date": [ { "raw": "1461273413819" } ],
        "process_created_date": [ { "raw": "1458681413819" } ]
      },
      "linkedItemIds": {
        "5660e898e4b08148fc41667f.contacts": [ { "itemId": "56b12644e4b08b67fd722d75" } ]
      }
    },
    {
      "id": "56f1dcefe4b047357c2c03e6",
      "listId": "56f087b0e4b0584aa39fbba8",
      "version": 1,
      "createdDate": 1458691311000,
      "modifiedDate": 1458691311848,
      "name": "John Clam",
      "accountId": null,
      "contactIds": [ "56f1b2a8e4b0d37eabe91b9d" ],
      "fieldValues": {
        "0": [ { "raw": "1" } ],
        "1": [ { "raw": "56155a21e4b0fee51b1cb043" } ],
        "3": [ { "raw": "1500" } ],
        "7": [ 
          { "raw": "1" },
          { "raw": "3" }
        ],
        "12": [ { "raw": "56df75a4e4b03009e48e8e76" } ],
        "14": [ { "raw": "Hello World" } ],
        "process_close_date": [ { "raw": "1558685591983" } ],
        "process_created_date": [ { "raw": "1458691311706" } ]
      },
      "linkedItemIds": {
        "5660e898e4b08148fc41667f.contacts": [ { "itemId": "56f1b2a8e4b0d37eabe91b9d" } ]
      }
    },
    {
      "id": "56f4623be4b07e586ec446da",
      "listId": "56f087b0e4b0584aa39fbba8",
      "version": 1,
      "createdDate": 1458856507000,
      "modifiedDate": 1458456507164,
      "name": "Tim Minutes",
      "accountId": null,
      "contactIds": [
        "56df75a4e4b03009e48e8e76"
      ],
      "fieldValues": {
        "0": [ { "raw": "0" } ],
        "1": [ { "raw": "56155a21e4b0fee51b1cb043" } ],
        "8": [ { "raw": "https://www.linkedin.com/in/tminutes" } ],
        "9": [ { "raw": "+14159365347" } ],
        "10": [ { "raw": "Model Minutes" } ],
        "process_close_date": [ { "raw": "1461448507176" } ],
        "process_created_date": [ { "raw": "1458856507176" } ]
      },
      "linkedItemIds": {
        "5660e898e4b08148fc41667f.contacts": [ { "itemId": "56df75a4e4b03009e48e8e76" } ]
      }
    }
  ],
  "size": 0,
  "errorSize": 0
}

GET /lists/{listId}/listitems/

Fetches a paginated collection of all of Items on a specified List.

Query Parameters

Parameter Type Required Description
_ids String[] false An optional, comma separated list of List Item identifiers.
_start Numeric false An optional starting point for the returned page of records (defaults to 0).
_limit Numeric false An optional page size for the returned result (defaults to 50, max size is 200).
modifiedDate Numeric false Fetch all List Items modified at or after this timestamp (in milliseconds since epoch).
contactIds String[] false An optional, comma separated list of contact identifiers.
accountIds String[] false An optional, comma separated list of account identifiers.

Update a List Item

Request


# Updating a List Item (Contact-based List)
curl 'https://api.salesforceiq.com/v2/lists/56f087b0e4b0584aa39fbba8/listitems/56f1b645e4b0d37eabea22b0'
  -X PUT
  -u $API_KEY:$API_SECRET
  -H 'Content-Type: application/json'
  -H 'Accept: application/json'
  -d '{
        "fieldValues": {
          "0": [ { "raw": "5" }]
        }
      }'

# Updating a List Item (Account-based List)
curl 'https://api.salesforceiq.com/v2/lists/56f1b185e4b0d37eabe8c2b0/listitems/56f1b20ee4b0d37eabe8e15f'
  -X PUT
  -u $API_KEY:$API_SECRET
  -H 'Content-Type: application/json'
  -H 'Accept: application/json'
  -d '{
        "fieldValues": {
          "0": [ { "raw": "5" } ]
        }
      }'

Response

# Updating a List Item (Contact-based List)
HTTP/1.1 200 OK
{
  "id": "56f1b645e4b0d37eabea22b0",
  "listId": "56f087b0e4b0584aa39fbba8",
  "version": 2,
  "createdDate": 1458681413000,
  "modifiedDate": 1458864805968,
  "name": "Cecilia Avocado",
  "accountId": null,
  "contactIds": [
    "56b12644e4b08b67fd722d75"
  ],
  "fieldValues": {
    "0": [ { "raw": "5" } ],
    "1": [ { "raw": "56155a21e4b0fee51b1cb043" } ],
    "6": [ { "raw": "03397194-1219-431c-a055-bc03a1d70cef" } ],
    "8": [ { "raw": "http://linkedin.com/cavocado" } ],
    "9": [ { "raw": "+14152990341" } ],
    "10": [ { "raw": "Avocado, Inc." } ],
    "process_close_date": [ { "raw": "1461273413819" } ],
    "process_created_date": [ { "raw": "1458681413819" } ]
  },
  "linkedItemIds": {
    "5660e898e4b08148fc41667f.contacts": [ { "itemId": "56b12644e4b08b67fd722d75" } ]
  }
}

# Updating a List Item (Account-based List)
HTTP/1.1 200 OK
{
  "id": "56f1b20ee4b0d37eabe8e15f",
  "listId": "56f1b185e4b0d37eabe8c2b0",
  "version": 1,
  "createdDate": 1458680334000,
  "modifiedDate": 1458931299914,
  "name": "Avocado, Inc.",
  "accountId": "56abd666e4b07f4066b7bcdc",
  "contactIds": [
    "56f1b2a8e4b0d37eabe91b9d",
    "56b12644e4b08b67fd722d75"
  ],
  "fieldValues": {
    "0": [ { "raw": "5" } ],
    "1": [ { "raw": "56155a21e4b0fee51b1cb043" } ],
    "process_close_date": [ { "raw": "1461272334831" } ],
    "process_created_date": [ { "raw": "1458680334831" } ]
  },
  "linkedItemIds": {}
}

PUT /lists/{listId}/listitems/{listItemId}

A PUT request which updates the details of a specific List Item.

Note: If you want to add a Point of Contact to a list item, you need to append the contactId to the existing contactIds array.

Query Parameters

Parameter Type Required Description
listId String true Id for the List to be fetched.
listItemId String true Id for the List Item to be updated

Payload

Parameter Type Required Description
listItem Object true A JSON representation of a List Item, without the id, modifiedDate, or createdDate fields (which will be generated on creation).

Delete a List Item

Request

curl 'https://api.salesforceiq.com/v2/lists/56f087b0e4b0584aa39fbba8/listitems/56f1b645e4b0d37eabea22b0'
  -X DELETE
  -u $API_KEY:$API_SECRET

Response

HTTP/1.1 200 OK
true

DELETE /lists/{listId}/listitems/{listItemId}

A DELETE request which removes a Item from an List and returns true or false as to whether the deletion completed successfully.

Query Parameters

Parameter Type Required Description
listId String true Id for the List to be fetched.
listItemId String true Id for the List Item to be updated.

Upsert a List Item

Request

# Upsert a List Item by contactIds
curl 'https://api.salesforceiq.com/v2/lists/56f087b0e4b0584aa39fbba8/listitems?_upsert=contactIds'
  -X POST
  -u $API_KEY:$API_SECRET
  -H 'Content-Type: application/json'
  -H 'Accept: application/json'
  -d '{
        "name": "Cecilia Avocado",
        "contactIds": ["56b12644e4b08b67fd722d75"],
        "fieldValues": {
          "0": [ { "raw": "5" }]
        }
      }'

# Upsert a List Item by accountId
curl 'https://api.salesforceiq.com/v2/lists/56f1b185e4b0d37eabe8c2b0/listitems?_upsert=accountId'
  -X POST
  -u $API_KEY:$API_SECRET
  -H 'Content-Type: application/json'
  -H 'Accept: application/json'
  -d '{
        "accountId": "56abd666e4b07f4066b7bcdc",
        "fieldValues": {
          "0": [ { "raw": "3" }]
        }
      }'

Response

# Upserted List Item by contactIds
HTTP/1.1 200 OK
{
  "id": "56f99519e4b0c3f938097ceb",
  "listId": "56f1b185e4b0d37eabe8c2b0",
  "version": 1,
  "createdDate": 1459197209000,
  "modifiedDate": 1459197209579,
  "name": "Avocado, Inc.",
  "accountId": "56abd666e4b07f4066b7bcdc",
  "contactIds": [
    "56f1b2a8e4b0d37eabe91b9d",
    "56b12644e4b08b67fd722d75"
  ],
  "fieldValues": {
    "0": [ { "raw": "5" } ],
    "1": [ { "raw": "56155a21e4b0fee51b1cb043" } ],
    "3": [ { "raw": "2500" } ],
    "process_close_date": [ { "raw": "1558685591983" } ],
    "process_created_date": [ { "raw": "1458690891320" } ]
  },
  "linkedItemIds": {}
}

# Upserted List Item by accountId
HTTP/1.1 200 OK
{
  "id": "56f1b20ee4b0d37eabe8e15f",
  "listId": "56f1b185e4b0d37eabe8c2b0",
  "version": 1,
  "createdDate": 1458680334000,
  "modifiedDate": 1459184818410,
  "name": "Avocado, Inc.",
  "accountId": "56abd666e4b07f4066b7bcdc",
  "contactIds": [
    "56f1b2a8e4b0d37eabe91b9d",
    "56b12644e4b08b67fd722d75"
  ],
  "fieldValues": {
    "0": [ { "raw": "3" } ],
    "1": [ { "raw": "56155a21e4b0fee51b1cb043" } ],
    "process_close_date": [ { "raw": "1459183098119" } ],
    "process_created_date": [ { "raw": "1458680334831" } ]
  },
  "linkedItemIds": {}
}

POST /lists/{listId}/listitems

A POST request which updates/inserts the details of a List Item based on query parameters.

If the value for the query parameter _upsert is ‘contactIds’, then SalesforceIQ will update the List Item associated with the contactIds provided in the Payload Attributes. If no List Item is found with the provided contactId, then the system will create a new List Item.

If the value for the query parameter _upsert is 'accountId’, then SalesforceIQ will update the List Item associated with the accountId provided in the Payload Attrtibutes. If no List Item is found with the provided accountId, then the system will create a new List Item.

Query Parameters

Parameter Type Required Description
listId String true Id for the List to be fetched.
_upsert String true The String literal 'contactIds’ or 'accountId’

Payload

Parameter Type Required Description
listItem Object true A JSON representation of a List Item, without the id, modifiedDate, or createdDate fields (which will be generated on creation).

Payload Attributes

Parameter Type Required Description
accountId String true (required for upsert by accountId) Id for the Account of the List Item
contactIds String[] true (required for upsert by contactIds) An array of unique identifiers for the Points of Contact of an Account or a Contact

Accounts

Accounts in SalesforceIQ generally represent companies or groups of people. Accounts can have any kind of relationship with your Organization - they could be leads, clients, former clients, or partners of your company.

The API can access all of your Organization’s Accounts, and all Accounts created by the API can be seen by your entire Organization. If you are trying to create an Account within a List please refer to the List Items (Relationship) API endpoint.

Account Object

Definition

{
  "id": "56abd666e4b07f4066b7bcdc",
  "modifiedDate": 1456874998553,
  "name": "Avocado, Inc.",
  "fieldValues": {
    "4": [ { "raw": "avocado@gmail.com" } ],  # Email (Text)
    "6": [ { "raw": "56155a21e4b0fee51b1cb043" } ], # Collaborators (User)
    "12": [ { "raw": "2" } ], # SLA (List)
    "14": [ { "raw": "94" } ],  # CSAT (Number)
    "16": [ { "raw": "2017-02-01" } ],  # Contract End Date (Date)
    "18": [                             # Industry (Picklist)
      { "raw": "0" },
      { "raw": "1" }
    ],
    "person_ids": [
      { "raw": "56f1b2a8e4b0d37eabe91b9d" },
      { "raw": "56b12644e4b08b67fd722d75" }
    ],
    "address": [ { "raw": "117 University Ave, Palo Alto, CA 94301" } ],  # Address (Location)
    "primary_contact": [ { "raw": "56b11a80e4b0b5663a53403e" } ]  # Primary Contact (Contact)
  }
}
Parameter Type Description
id String Id, created by the system
modifiedDate Numeric When the Account was last edited, measured in milliseconds since (UTC) the epoch
name String Account name as it will appear in SalesforceIQ
fieldValues Object A collection of values for Account Property objects. For details about saving account property data, reference our in-depth explanation of account properties.

Get All Accounts

Request

# Retrieve the first 50 Account in your Organization
curl 'https://api.salesforceiq.com/v2/accounts'
  -X GET
  -u $API_KEY:$API_SECRET
  -H 'Accept: application/json'

# Retrieve two Accounts by Ids in your Organization
curl 'https://api.salesforceiq.com/v2/accounts?_ids=56abd666e4b07f4066b7bcdc, 56b3acf5e4b0a8f6a0711488'
  -X GET
  -u $API_KEY:$API_SECRET
  -H 'Accept: application/json'

# Retrieve all Accounts where modifiedDate > 1456874990000
curl 'https://api.salesforceiq.com/v2/accounts?modifiedDate=1456874990000'
  -X GET
  -u $API_KEY:$API_SECRET
  -H 'Accept: application/json' 

# Retrieve two Accounts starting at index 1 
curl 'https://api.salesforceiq.com/v2/accounts?_start=1&_limit=2'
  -X GET
  -u $API_KEY:$API_SECRET
  -H 'Accept: application/json' 

Response

HTTP/1.1 200 OK
{
  "objects": [
    {
      "id": "56abd666e4b07f4066b7bcdc",
      "modifiedDate": 1456874998553,
      "name": "Avocado, Inc.",
      "fieldValues": {
        "2": [ { "raw": "0" } ],                       
        "4": [ { "raw": "avocado@gmail.com" } ],
        "6": [ { "raw": "56155a21e4b0fee51b1cb043" } ],
        "12": [ { "raw": "2" } ],
        "14": [ { "raw": "94" } ],
        "16": [ { "raw": "2017-02-01" } ],
        "18": [ 
          { "raw": "0" },
          { "raw": "1" }
        ],
        "address": [ { "raw": "117 University Ave, Palo Alto, CA 94301" } ],
        "address_city": [ { "raw": "Palo Alto" } ],
        "address_state": [ { "raw": "CA" } ],
        "address_country": [ { "raw": "US" } ],
        "address_postal_code": [ { "raw": "94301" } ],
        "primary_contact": [ { "raw": "56b11a80e4b0b5663a53403e" } ],
        "person_ids": [
          { "raw": "56f1b2a8e4b0d37eabe91b9d" },
          { "raw": "56b12644e4b08b67fd722d75" }
        ]
      }
    },
    {
      "id": "56df7a47e4b0f4b562879dfb",
      "modifiedDate": 1457486407906,
      "name": "Fitbot",
      "fieldValues": {}
    }
  ],
  "nextPage": null
}

GET /accounts

This endpoint fetches all Accounts. Responses are paginated, max of 200 at a time.

Query Parameters

Parameter Type Required Description
_ids String[] false An optional, comma separated list of Account identifiers.
_start Numeric false An optional starting point for the returned page of records (defaults to 0). If you start at 50 you will retrieve records starting at the index 51 to your _limit.
_limit Numeric false An optional page size for the returned result (defaults to 50, max size is 200).
modifiedDate Numeric false Fetch all accounts modified at or after this timestamp (in milliseconds since epoch).

Get a Single Account

Request

curl 'https://api.salesforceiq.com/v2/accounts/56abd666e4b07f4066b7bcdc'
  -X GET
  -u $API_KEY:$API_SECRET
  -H 'Accept: application/json'

Response

HTTP/1.1 200 OK
{
  "id": "56abd666e4b07f4066b7bcdc",
  "modifiedDate": 1456874998553,
  "name": "Avocado, Inc.",
  "fieldValues": {
    "2": [ { "raw": "0" } ],                       
    "4": [ { "raw": "avocado@gmail.com" } ],
    "6": [ { "raw": "56155a21e4b0fee51b1cb043" } ],
    "12": [ { "raw": "2" } ],
    "14": [ { "raw": "94" } ],
    "16": [ { "raw": "2017-02-01" } ],
    "18": [ 
      { "raw": "0" },
      { "raw": "1" }
    ],
    "address": [ { "raw": "117 University Ave, Palo Alto, CA 94301" } ],
    "address_city": [ { "raw": "Palo Alto" } ],
    "address_state": [ { "raw": "CA" } ],
    "address_country": [ { "raw": "US" } ],
    "address_postal_code": [ { "raw": "94301" } ],
    "primary_contact": [ { "raw": "56b11a80e4b0b5663a53403e" } ],
    "person_ids": [
      { "raw": "56f1b2a8e4b0d37eabe91b9d" },
      { "raw": "56b12644e4b08b67fd722d75" }
    ]
  }
}

GET /accounts/{id}

A GET request which pulls a specific Account by ID. Accounts can only be queried by Account ID.

Query Parameters

Parameter Type Required Description
id String true Id of the Account to be fetched.

Create an Account

Request

curl "https://api.salesforceiq.com/v2/accounts"
  -X POST
  -u $API_KEY:$API_SECRET
  -H 'Content-Type: application/json'
  -H 'Accept: application/json'
  -d '{ 
        "name": "Avocado, Inc.",
        "fieldValues": { 
          "address": [ { "raw": "502 Emerson St, Palo Alto, CA 94301" } ],
          "primary_contact": [ { "raw": "56b11a80e4b0b5663a53403e" } ],
          "person_ids": [ 
            { "raw": "56f1b2a8e4b0d37eabe91b9d" },
            { "raw": "56b12644e4b08b67fd722d75" }
          ],
          "2": [ { "raw": "CEO" } ],
          "6": [ { "raw": "jmcsales@sales.com" } ],
          "12": [ { "raw": "2" } ],
          "14": [ { "raw": "93" } ],
          "16": [ { "raw": "2017-2-1" } ],
          "18": [ 
            { "raw": "0" }, 
            { "raw": "1" } 
          ]
        }
      }'

Response

HTTP/1.1 200 OK
{
  "id": "56abd666e4b07f4066b7bcdc",
  "name": "Avocado, Inc.",
  "fieldValues": { 
    "address": [ { "raw": "502 Emerson St, Palo Alto, CA 94301" } ],
    "primary_contact": [{"raw": "56b11a80e4b0b5663a53403e"}],
    "2": [ { "raw": "CEO" } ],
    "6": [ { "raw": "jmcsales@sales.com" } ],
    "12": [ { "raw": "2" } ],
    "14": [ { "raw": "93" } ],
    "16": [ { "raw": "2017-2-1" } ],
    "18": [ 
      { "raw": "0" }, 
      { "raw": "1" } 
    ]
  }
}

POST /accounts

A POST request which creates a new Account object and returns the created Account with its new unique ID.

Payload

Parameter Type Required Description
newAccount Object true A JSON representation of an Account, without the id or modifiedDate fields (which will be generated on creation).

Payload Attributes

Parameter Type Required Description
name String true The name of the Account to be created.
fieldValues Object false A collection of values for Account Property objects. For details about saving account propery data, see that section.

Update an Account

Request

curl 'https://api.salesforceiq.com/v2/accounts/568ed01fe4b0b69244577452'
  -X PUT
  -u $API_KEY:$API_SECRET
  -H 'Content-Type: application/json'
  -H 'Accept: application/json'
  -d '{
      "id" : "568ed01fe4b0b69244577452",
      "name": "Jamjilla"
    }'

Response

HTTP/1.1 200 OK
{ 
  "id": "568ed01fe4b0b69244577452",
  "modifiedDate": 1457546646286,
  "name":"Jameroo",
  "fieldValues": {}
}

PUT /accounts/{id}

A PUT request which updates the details of a specific Account. The id and name are required keys in the body.

If an Account Contact is a Point of Contact on a List Item, the API will return a status code 400. This is because all Points of Contact must be an Account Contact.

Query Parameters

Parameter Type Required Description
id String true The unique identifier for the Account to be updated.

Payload

Parameter Type Required Description
updatedAccount Object true An Account object which includes only the fieldValues that need to be updated. This object should be included in the body of the request.

Payload Attributes

Parameter Type Required Description
id String true Id of the Account to be updated.
name String true The existing or updated name of the Account.
fieldValues Object false A collection of values for Account Property objects. For details about saving account property data, reference our in-depth explanation of account properties.

Delete an Account

Request

curl "https://api.salesforceiq.com/v2/accounts/56fc1244e4b0cb31e6288c61"
  -X DELETE
  -u $API_KEY:$API_SECRET

Response

HTTP/1.1 200 OK
true

DELETE /accounts/{id}

A DELETE request which removes an Account from the Organization and returns true or false as to whether the deletion completed successfully.

The request will fail if the Account is associated with a List Item.

Query Parameters

Parameter Type Required Description
id String true Id for the Account to be deleted.

Account Properties

Request

curl 'https://api.salesforceiq.com/v2/accounts/fields' 
  -X GET 
  -u $API_KEY:$API_SECRET 
  -H 'Accept: application/json'

Response

HTTP/1.1 200 OK
{
  "fields": [
    {
      "id": "address",
      "name": "Address",
      "listOptions": [],
      "isMultiSelect": false,
      "isEditable": true,
      "dataType": "Location"
    },
    {
      "id": "address_city",
      "name": "City",
      "listOptions": [],
      "isMultiSelect": false,
      "isEditable": false,
      "dataType": "Location"
    },
    {
      "id": "address_state",
      "name": "State/Province",
      "listOptions": [],
      "isMultiSelect": false,
      "isEditable": false,
      "dataType": "Location"
    },
    {
      "id": "address_postal_code",
      "name": "Zip/Postal Code",
      "listOptions": [],
      "isMultiSelect": false,
      "isEditable": false,
      "dataType": "Location"
    },
    {
      "id": "address_country",
      "name": "Country",
      "listOptions": [],
      "isMultiSelect": false,
      "isEditable": false,
      "dataType": "Location"
    },
    {
      "id": "primary_contact",
      "name": "Primary Contact",
      "listOptions": [],
      "isMultiSelect": false,
      "isEditable": true,
      "dataType": "Contact"
    },
    {
      "id": "2",
      "name": "Title",
      "listOptions": [
        {
          "id": "0",
          "display": "CEO"
        },
        {
          "id": "1",
          "display": "Sales Rep"
        },
        {
          "id": "2",
          "display": "Principal"
        }
      ],
      "isMultiSelect": false,
      "isEditable": true,
      "dataType": "List"
    },
    {
      "id": "4",
      "name": "Email",
      "listOptions": [],
      "isMultiSelect": false,
      "isEditable": true,
      "dataType": "Text"
    },
    {
      "id": "6",
      "name": "Collaborators",
      "listOptions": [],
      "isMultiSelect": true,
      "isEditable": true,
      "dataType": "User"
    },
    {
      "id": "12",
      "name": "SLA",
      "listOptions": [
        {
          "id": "0",
          "display": "Basic"
        },
        {
          "id": "1",
          "display": "Business"
        },
        {
          "id": "2",
          "display": "Premium"
        }
      ],
      "isMultiSelect": false,
      "isEditable": true,
      "dataType": "List"
    },
    {
      "id": "14",
      "name": "CSAT",
      "listOptions": [],
      "isMultiSelect": false,
      "isEditable": true,
      "dataType": "Numeric"
    },
    {
      "id": "16",
      "name": "Contract End Date",
      "listOptions": [],
      "isMultiSelect": false,
      "isEditable": true,
      "dataType": "Date"
    },
    {
      "id": "18",
      "name": "Industry",
      "listOptions": [
        {
          "id": "0",
          "display": "Tech"
        },
        {
          "id": "1",
          "display": "Energy"
        },
        {
          "id": "2",
          "display": "Restaurant"
        },
        {
          "id": "3",
          "display": "Services"
        },
        {
          "id": "4",
          "display": "IT"
        },
        {
          "id": "5",
          "display": "VC"
        },
        {
          "id": "6",
          "display": "Real Estate"
        },
        {
          "id": "7",
          "display": "Transportation"
        }
      ],
      "isMultiSelect": true,
      "isEditable": true,
      "dataType": "List"
    }
  ]
}

GET /accounts/fields

Account properties are custom properties that your organization’s admin creates that allow you to store information at the Account level, rather than tied to a specific lead, opportunity, etc. on a List. If you find yourself tracking the same fields for Accounts on multiple Lists, think about leveraging Account properties to reduce the need to input redundant data. Read this article for more information about Account properties.

A GET request which fetches metadata information of the Account Property fields.

When updating fieldValues on Accounts, make sure to use this endpoint first to programmatically pull back a mapping between the user defined field names and the field ids for Account Properties. You will need to use this map when passing fieldValue changes to the Accounts endpoint.

Contacts

Contacts represent people in an Organization’s address book. SalesforceIQ has two types of Contacts: private and shared. Shared Contacts are accessible by the entire Organization and can be viewed and updated by the API. If you are trying to associate a Contact within a List please refer to the List Items (Relationship) API endpoint.

SalesforceIQ is designed to handle and merge multiple Contacts for the same person elegantly based on the Contact properties. Lets say that we have two Cecilia Avocado Contacts. Cecilia Avocado (1) has four properties A,B,C,D and Cecilia Avocado (2) has three properties A,B,C, then the two Contacts will be automatically merged to be Cecilia Avocado with properties A,B,C,D.

Now lets say we have two Contacts Tim Minutes. Tim Minutes (1) has three properties A,B,C and Tim Minutes (2) has properties A,D, then the two Contacts will not be merged because the properties of Tim Minutes (2) are not a subset of the other proprties.

The API can access all of your Organization’s Contacts, and all Contacts created by the API can be seen by your entire Organization. If you are trying to associate an Contact within a List please refer to the List Items (Relationship) API endpoint.

Contact Object

Definition

{
  "id": "56b12644e4b08b67fd722d75",
  "modifiedDate": 1457564297403,
  "requestedIds": [
    "56b11a80e4b0b5663a53403e"
  ],
  "mergedIds": null,
  "properties": {
    "liurl": [
      {
        "value": "https://www.linkedin.com/in/cavocado",
        "metadata": {}
      }
    ],
    "address": [
      {
        "value": "117 University Ave, Palo Alto, CA 94301",
        "metadata": {}
      }
    ],
    "phone": [
      {
        "value": "+14152990341",
        "metadata": {
          "stype": "work",
          "raw_val": "+1 415-299-0341",
          "primary": "true"
        }
      },
      {
        "value": "+15103139867",
        "metadata": {
          "raw_val": "+1 510-313-9867"
        }
      }
    ],
    "twhan": [
      {
        "value": "@cavocado",
        "metadata": {}
      }
    ],
    "name": [
      {
        "value": "Cecilia Avocado",
        "metadata": {}
      }
    ],
    "experience": [
      {
        "value": "Avocado, Inc.",
        "metadata": {
          "company_name": "Avocado, Inc.",
          "job_title": "CEO"
        }
      },
      {
        "value": "IQ.Tempo",
        "metadata": {
          "company_name": "IQ.Tempo",
          "job_title": "VP of Sales"
        }
      }
    ],
    "email": [
      {
        "value": "c.avocado@gmail.com",
        "metadata": {
          "stype": "personal",
          "primary": "false"
        }
      },
      {
        "value": "c.avocado@avocado.com",
        "metadata": {
          "stype": "work",
          "primary": "true"
        }
      }
    ]
  },
  "state": "ACTIVE"
}
Parameter Type Description
id String Id, created by the system
modifiedDate Numeric milliseconds since (UTC) epoch
properties Object A collection of properties that are associated with the Contact.

Create a Contact

Request

curl 'https://api.salesforceiq.com/v2/contacts'
  -X POST
  -u $API_KEY:$API_SECRET
  -H 'Content-Type: application/json'
  -H 'Accept: application/json'
  -d '{      
        "properties": {
          "liurl": [ { "value": "https://www.linkedin.com/in/cavocado" } ],
          "address": [ { "value": "117 University Ave, Palo Alto, CA 94301" } ],
          "phone": [
            {
              "value": "+14152990341",
              "metadata": {
                "stype": "work",
                "raw_val": "+1 415-299-0341",
                "primary": "true"
              }
            },
            {
              "value": "+15103139867",
              "metadata": {
                "raw_val": "+1 510-313-9867"
              }
            }
          ],
          "twhan": [ { "value": "@cavocado" } ],
          "name": [ { "value": "Cecilia Avocado" } ],
          "experience": [
            {
              "value": "Avocado, Inc.",
              "metadata": {
                "company_name": "Avocado, Inc.",
                "job_title": "CEO"
              }
            },
            {
              "value": "IQ.Tempo",
              "metadata": {
                "company_name": "IQ.Tempo",
                "job_title": "VP of Sales"
              }
            }
          ],
          "email": [
            {
              "value": "c.avocado@gmail.com",
              "metadata": {
                "stype": "personal",
                "primary": "false"
              }
            },
            {
              "value": "c.avocado@avocado.com",
              "metadata": {
                "stype": "work",
                "primary": "true"
              }
            }
          ]
        }
      }'

Response

HTTP/1.1 200 OK
{
  "id": "56b12644e4b08b67fd722d75",
  "modifiedDate": 1457564297403,
  "requestedIds": [
    "56b11a80e4b0b5663a53403e"
  ],
  "mergedIds": null,
  "properties": {
    "liurl": [
      {
        "value": "https://www.linkedin.com/in/cavocado",
        "metadata": {}
      }
    ],
    "address": [
      {
        "value": "117 University Ave, Palo Alto, CA 94301",
        "metadata": {}
      }
    ],
    "phone": [
      {
        "value": "+14152990341",
        "metadata": {
          "stype": "work",
          "raw_val": "+1 415-299-0341",
          "primary": "true"
        }
      },
      {
        "value": "+15103139867",
        "metadata": {
          "raw_val": "+1 510-313-9867"
        }
      }
    ],
    "twhan": [
      {
        "value": "@cavocado",
        "metadata": {}
      }
    ],
    "name": [
      {
        "value": "Cecilia Avocado",
        "metadata": {}
      }
    ],
    "company": [
      {
        "value": "Avocado, Inc.",
        "metadata": {}
      }
    ],
    "title": [
      {
        "value": "CEO",
        "metadata": {}
      }
    ],
    "experience": [
      {
        "value": "Avocado, Inc.",
        "metadata": {
          "company_name": "Avocado, Inc.",
          "job_title": "CEO"
        }
      },
      {
        "value": "IQ.Tempo",
        "metadata": {
          "company_name": "IQ.Tempo",
          "job_title": "VP of Sales"
        }
      }
    ],
    "email": [
      {
        "value": "c.avocado@gmail.com",
        "metadata": {
          "stype": "personal",
          "primary": "false"
        }
      },
      {
        "value": "c.avocado@avocado.com",
        "metadata": {
          "stype": "work",
          "primary": "true"
        }
      }
    ]
  },
  "state": "ACTIVE"
}

POST /contacts

A POST request which creates a new Contact object and returns the created Contact with its new unique ID.

Payload

Parameter Type Required Description
newContact Object true A JSON representation of a Contact, without the id or modifiedDate fields (which will be generated on creation).

Payload Attributes

Parameter Type Required Description
properties Object false A collection of Contact properties that include name, email, phone, address, company, tite, experience, liurl (LinkedIn url), twhan (Twitter handle) for a Contact object.

Get All Contacts

Request

# Retrieve all Contacts in your Organization
curl 'https://api.salesforceiq.com/v2/contacts'
  -X GET
  -u $API_KEY:$API_SECRET
  -H 'Accept: application/json'

# Retrive two Contacts by Ids in your Organization
curl 'https://api.salesforceiq.com/v2/contacts?_ids=56b12644e4b08b67fd722d75, 56df75a4e4b03009e48e8e76'
  -X GET
  -u $API_KEY:$API_SECRET
  -H 'Accept: application/json'

# Retrieve all Contacts where modifiedDate > 1458165069813
curl 'https://api.salesforceiq.com/v2/contacts?modifiedDate=1458165069813'
  -X GET
  -u $API_KEY:$API_SECRET
  -H 'Accept: application/json'

# Retrieve two Contacts starting at index 1
curl 'https://api.salesforceiq.com/v2/contacts?_start=1&_limit=2'
  -X GET
  -u $API_KEY:$API_SECRET
  -H 'Accept: application/json'

# Retrieve Contacts by email address
curl 'https://api.salesforceiq.com/v2/contacts?properties.email="c.avocado@avocado.com"'
  -X GET
  -u $API_KEY:$API_SECRET
  -H 'Accept: application/json'

# Retrieve Contacts by phone number
curl 'https://api.salesforceiq.com/v2/contacts?properties.phone="14152990341"'
  -X GET
  -u $API_KEY:$API_SECRET
  -H 'Accept: application/json'

Response

HTTP/1.1 200 OK
{
  "objects": [
    {
      "id": "56b12644e4b08b67fd722d75",
      "modifiedDate": 1457564297403,
      "requestedIds": [ "56b12644e4b08b67fd722d75" ],
      "mergedIds": [ "56b11a80e4b0b5663a53403e" ],
      "properties": {
        "liurl": [ 
          {
            "value": "https://www.linkedin.com/in/cavocado",
            "metadata": {}
          }
        ],
        "address": [
          {
            "value": "117 University Ave, Palo Alto, CA 94301",
            "metadata": {}
          }
        ],
        "phone": [
          {
            "value": "+14152990341",
            "metadata": {
              "stype": "work",
              "raw_val": "+1 415-299-0341",
              "primary": "true"
            }
          },
          {
            "value": "+15103139867",
            "metadata": { "raw_val": "+1 510-313-9867" }
          }
        ],
        "twhan": [
          {
            "value": "@cavocado",
            "metadata": {}
          }
        ],
        "name": [
          {
            "value": "Cecilia Avocado",
            "metadata": {}
          }
        ],
        "experience": [
          {
            "value": "Avocado, Inc.",
            "metadata": {
              "company_name": "Avocado, Inc.",
              "job_title": "CEO"
            }
          },
          {
            "value": "IQ.Tempo",
            "metadata": {
              "company_name": "IQ.Tempo",
              "job_title": "VP of Sales"
            }
          }
        ],
        "email": [
          {
            "value": "c.avocado@gmail.com",
            "metadata": {
              "stype": "personal",
              "primary": "false"
            }
          },
          {
            "value": "c.avocado@avocado.com",
            "metadata": {
              "stype": "work",
              "primary": "true"
            }
          }
        ]
      },
      "state": "ACTIVE"
    }
  ]
}

GET /contacts

This endpoint fetches all Contacts. Responses are paginated, max of 200 at a time.

Query Parameters

Parameter Type Required Description
_ids String[] false An optional, comma separated list of Contact identifiers.
_start Numeric false An optional starting point for the returned page of records (defaults to 0). If you start at 50 you will retrieve records starting at the index 51 to your _limit.
_limit Numeric false An optional page size for the returned result (defaults to 50, max size is 200).
modifiedDate Numeric false Fetch all accounts modified at or after this timestamp (in milliseconds since epoch).

Get a Single Contact

Request

curl 'https://api.salesforceiq.com/v2/contacts/56b12644e4b08b67fd722d75'
  -X GET
  -u $API_KEY:$API_SECRET
  -H 'Accept: application/json'

Response

HTTP/1.1 200 OK
{
  "id": "56b12644e4b08b67fd722d75",
  "modifiedDate": 1457564297403,
  "requestedIds": [ "56b11a80e4b0b5663a53403e" ],
  "mergedIds": null,
  "properties": {
    "liurl": [
      {
        "value": "https://www.linkedin.com/in/cavocado",
        "metadata": {}
      }
    ],
    "address": [
      {
        "value": "117 University Ave, Palo Alto, CA 94301",
        "metadata": {}
      }
    ],
    "phone": [
      {
        "value": "+14152990341",
        "metadata": {
          "stype": "work",
          "raw_val": "+1 415-299-0341",
          "primary": "true"
        }
      },
      {
        "value": "+15103139867",
        "metadata": { "raw_val": "+1 510-313-9867" }
      }
    ],
    "twhan": [
      {
        "value": "@cavocado",
        "metadata": {}
      }
    ],
    "name": [
      {
        "value": "Cecilia Avocado",
        "metadata": {}
      }
    ],
    "experience": [
      {
        "value": "Avocado, Inc.",
        "metadata": {
          "company_name": "Avocado, Inc.",
          "job_title": "CEO"
        }
      },
      {
        "value": "IQ.Tempo",
        "metadata": {
          "company_name": "IQ.Tempo",
          "job_title": "VP of Sales"
        }
      }
    ],
    "email": [
      {
        "value": "c.avocado@gmail.com",
        "metadata": {
          "stype": "personal",
          "primary": "false"
        }
      },
      {
        "value": "c.avocado@avocado.com",
        "metadata": {
          "stype": "work",
          "primary": "true"
        }
      }
    ]
  },
  "state": "ACTIVE"
}

GET /contacts/{id}

A GET request which pulls a specific Contact by ID. Contacts can only be queried by Contact ID.

Query Parameters

Parameter Type Required Description
id String true The unique identifier for the Account to be fetched.

Update a Contact

Request

curl 'https://api.salesforceiq.com/v2/contacts/56b12644e4b08b67fd722d75'
  -X PUT
  -u $API_KEY:$API_SECRET
  -H 'Content-Type: application/json'
  -H 'Accept: application/json'
  -d '{
        "id": "56b12644e4b08b67fd722d75",
        "properties": {
          "email": [
            {
              "value": "c.avocado@gmail.com",
              "metadata": {
                "stype": "personal",
                "primary": "true"
              }
            },
            {
              "value": "c.avocado@avocado.com",
              "metadata": {
                "stype": "work",
                "primary": "false"
              }
            }
          ]
        }
      }'

Response

HTTP/1.1 200 OK
{
  "id": "56b12644e4b08b67fd722d75",
  "modifiedDate": 1458168762562,
  "requestedIds": null,
  "mergedIds": null,
  "properties": {
    "email": [
      {
        "value": "c.avocado@gmail.com",
        "metadata": {
          "stype": "personal",
          "primary": "true"
        }
      },
      {
        "value": "c.avocado@avocado.com",
        "metadata": {
          "stype": "work",
          "primary": "false"
        }
      }
    ]
  },
  "state": "ACTIVE"
}

PUT /contacts/{id}

A PUT request which updates the details of a specific Contact.

Query Parameters

Parameter Type Required Description
id String true The unique identifier for the Contact to be updated.

Payload

Parameter Type Required Description
updatedContact Object true A Contact object which includes only the properties that need to be updated. This object should be included in the body of the request.

Payload Attributes

Parameter Type Required Description
id String true Id of the Contact to be updated.
properties Object true A collection of Contact properties that include name, email, phone, address, company, tite, experience, liurl (LinkedIn url), twhan (Twitter handle) for a Contact object.

Upsert a Contact

Request

curl 'https://api.salesforceiq.com/v2/contacts?_upsert=email'
  -X POST
  -u $API_KEY:$API_SECRET
  -H 'Content-Type: application/json'
  -H 'Accept: application/json'
  -d '{
        "properties": {
          "email": [
            {
              "value": "rdreesen@gmail.com",
              "metadata": {
                  "primary": "false"
              }
            },
            {
              "value": "r.dreesen@imt.com",
              "metadata": {
                  "stype": "work",
                  "primary": "true"
              }
            }
          ]
        }
      }'

Response

HTTP/1.1 200 OK
{
  "id": "56e9d27de4b0b397dfa971cb",
  "properties": {
    "liurl": [
      {
        "value": "https://www.linkedin.com/in/rdreesen",
        "metadata": {}
      }
    ],
    "phone": [
      {
        "value": "+14154873698",
        "metadata": {
          "raw_val": "+1 415-487-3698"
        }
      }
    ],
    "name": [
      {
        "value": "Ray Dreesen",
        "metadata": {}
      }
    ],
    "email": [
      {
        "value": "rdreesen@gmail.com",
        "metadata": {
            "primary": "false"
        }
      },
      {
        "value": "r.dreesen@imt.com",
        "metadata": {
            "stype": "work",
            "primary": "true"
        }
      }
    ]
  }
}

POST /contacts

A POST request which creates or updates a Contact object.

Query Parameters

Parameter Type Required Description
_upsert String true The only value this parameter may have is “email”.

Payload

Parameter Type Required Description
updatedContact Object true A Contact object which includes only the properties that need to be updated. This object should be included in the body of the request.

Payload Attributes

Parameter Type Required Description
properties Object true A collection of Contact properties that include name, email, phone, address, company, tite, experience, liurl (LinkedIn url), twhan (Twitter handle) for a Contact object.

Archive a Contact

Request

curl "https://api.salesforceiq.com/v2/contacts/56fc1244e4b0cb31e6288c61"
  -X DELETE
  -u $API_KEY:$API_SECRET

Response

HTTP/1.1 200 OK
true

DELETE /contacts/{id}

A DELETE request which archives a Contact and returns true or false as to whether the deletion completed successfully.

The request will fail if the Contact is associated with a List Item.

Query Parameters

Parameter Type Required Description
id String true Id for the Contact to be deleted.

Events

Events represent interactions involving a Contact associated with a List Item. Instead of appearing as new content in List columns, Events appear in the “Stream View” associated with the appropriate List Item. If the same Contact is associated with more than one List Item, then the Event will appear in all relevant Stream Views.

For example, let’s say a sales rep (James) using SalesforceIQ takes calls with a lead (Cecilia) and an Event (the call, with notes) is recorded through the API. Let’s say Cecilia or his company have List Items in two Lists to which James has access – one List that tracks active clients, and another which tracks upsell opportunities. James’ call Event will appear in both List Item’s Stream views as an Event. The Event will not appear in reporting for either List. Alternatively, if Sam is not in any SalesforceIQ List, then no Event appears in any Stream.

Events do not appear in reporting and do not affect intelligence fields. If you build an integration with your VOIP system which logs calls, the calls logged by the API will not appear as phone calls in SalesforceIQ reporting.

Event Object

Definition

{
  "subject": "Call with Cecilia Avocado",
  "body": "Negotiated pricing and sent out a contract during the call."
  "participantIds": [
    { 
      "type": "email",
      "value": "james.mcsales@salesforceiq.com"
    },
    {
      "type": "phone",
      "value": "14152990341"
    }
  ]
}
Parameter Type Description
subject String (required) a title or subject of the event
body String (required) notes about the event
participantIds Object[] (required) A collection of Contact emails or phone numbers

Create an Event

Request

curl 'https://api.salesforceiq.com/v2/events'
  -X PUT
  -u $API_KEY:$API_SECRET
  -H 'Content-Type: application/json'
  -H 'Accept: application/json'
  -d '{
        "subject": "Phone Call",
        "body": "Discussed contract negotiations",
        "participantIds": [
          { 
            "type": "email",
            "value": "james.mcsales@salesforceiq.com"
          },
          {
            "type": "phone",
            "value": "14152990341"
          }
        ]
      }'

Response

# Nothing
HTTP/1.1 204 NO CONTENT

PUT /events

A PUT request which creates a new Event and begins propogating the details out to associated streams.

Payload

Parameter Type Required Description
newEvent Object true A JSON representation of an Event

Payload Attributes

Parameter Type Required Description
subject String true The subject or title of the event
body String true The body of the event
participantIds Object[] true A collection of Contact emails or phone numbers

Users

Users are individuals with login access to your SalesforceIQ organization. The user object consists of a name, email address, and unique identifier. The unique identifier can be queried through the API end point to return the user’s name and email address for a specific contactID and userID.

Definition

  {
    "id" : d9013f21g411f3ea1b1cbd33,
    "name" : "James McSales",
    "email" : "james.mcsales@salesforceiq.com"
  }
Parameter Type Description
id String Id, created by the system
name String Name of the User
email String The Email address used to sign in by the User

Get a Single User

Request

curl 'https://api.salesforceiq.com/v2/users/56b12644e4b08b67fd722d75'
  -X GET
  -u $API_KEY:$API_SECRET
  -H 'Accept: application/json'

Response

HTTP/1.1 200 OK
{
  "id" : d9013f21g411f3ea1b1cbd33,
  "name" : "James McSales",
  "email" : "james.mcsales@salesforceiq.com"
}

GET /users

Query Parameters

Parameter Type Required Description
id String true Id for the User to be fetched.

Example Use Cases

Below we describe a few of our customers’s most common use cases for integrations. We will continue to add descriptions and example code as we grow our platform and support more complex integrations.

Web Form

Many of our clients capture information about potential leads from a form on their website. Entering these leads into SalesforceIQ using the API is an easier and less error-prone process than having someone enter the data manually.

Let’s say the “contact us” form collects the following information:

To represent this new lead, you would want to take the following steps:

Use the Contact endpoint to create a new Contact with the “name,” “email,” and ‘“phone” fields You can add multiple emails or phone numbers if relevant. You don’t need to check for an existing duplicate Contact — SalesforceIQ will automatically associate duplicate Contacts with each other based on the rules mentioned in the Contact section, and will keep all information in both Contact entries. The Contact endpoint will provide an ID for the new Contact.

Use the Account edpoint to create a new Account with the “Company name” as the name and “address” as the address You don’t need to check for an existing duplicate Account — SalesforceIQ will automatically associate duplicate Accounts with each other based on name, and will keep all information in both Contact entries. The Account endpoint will return an ID for the new Account.

Create a new List Item in an existing List Make sure the API has access to this List; if you can’t see it through the List endpoint, you will need to ask the List administrator for access.

For this example, let’s say the List you are updating is called “Leads.” Let’s assume this is an “Account” type List and has the following schema:

List Field Information to Populate Account
Account ID for the new Account you just created. Optional: Associate the ID of the Contact you just created to the Account in this List. This will cause email between the Contact and List collaborators to be captured in the Stream.
Status Choose from among the existing “status” options, or leave blank to set to the default value (status options and default value are defined by the List administrator)
Owner ID for a SalesforceIQ User associated with this List, or leave blank
Contact Preferences Text from the “best time to call” field on the form
Lead Source “Contact us” form (or another label that’s helpful for your users)
Time of Contact Timestamp when the user submitted the form
Additional Information Can leave blank

The new lead from the web form will now be available in your SalesforceIQ List

Website Event

Example use case: User registers for an Event through your website

Through a form on your website, the user enters the following information to register for your training webinar:

Use the Contact endpoint to identify an existing Contact or create a new Contact with the “name” and “email” fields. You can add multiple emails if relevant. You don’t need to check for an existing duplicate Contact — SalesforceIQ will automatically associate duplicate Contacts with each other based on the rules mentioned in the Contact section, and will keep all information in the merged Contact. The Contact endpoint will provide an ID for the new or existing Contact.

Use the Event endpoint to create a new registration Event associated with the Contact you created or identified

Event attribute Data entered
Identifier Email
Title Training webinar registration
Body text [Name], [title] registered for a training webinar on 3/18/2014 at 10 AM PT. [Name] is interested in learning more about [areas of interest].
Activity timestamp Use registration timestamp from your own website or leave blank
Created timestamp Leave blank; will be populated automatically with the time you created the activity
Creator Leave blank; will be populated with the name of your API Key

Event will appear in the Stream for any List Item associated with the Contact Assuming the API has access to the relevant List(s), your company’s SalesforceIQ Users will see the Event registration in the Stream.