SalesNexus.com 713.862.0001 800.862.0134 support@salesnexus.com  
Salesnexus logo

API Documentation

This document describes how this API works and provides example requests.

Last Updated: 04/23/2019

  1. API Keys and Authorization Tokens
    1. API Keys
    2. Authorization Token
  2. API URL
  3. Request Structure
    1. Examples
      1. Hello World
      2. Echo
      3. Sending multiple API requests in a single HTTP request
  4. API Calls
    1. Session Management
      1. Get Session Token
    2. Field Management
      1. Get All Fields
      2. Get All Layouts
    3. User Management
      1. Get All Users
    4. Contact Management
      1. Create Contact
      2. Get Contacts
      3. Get All Data for a Contact
      4. Get All Notes for a Contact
      5. Get All Sales Opportunities for a Contact
      6. Update Contact
    5. Activities
      1. Create Activity
      2. Complete Activity
      3. Update Activity
      4. Get All Data for an Activity
    6. Campaigns
      1. Get Campaigns
      2. Add to Campaigns
    7. Sales Opportunities
      1. Get Sales Opportunities
      2. Create Sales Opportunity
    8. Notes
      1. Create Notes


API Keys and Authorization Tokens

These identifiers are needed for some API functions to be fulfilled. Accessing or modifying any potentially sensitive data requires an API key. Accessing or modifying any data from any SalesNexus clients requires an authorization token.

API Keys

The API Key is a unique identifier that identifies your service. It should be sent with any request that is documented as needing it.

Authorization Token

The authorization token is a unique identifier which is given by a SalesNexus client. It must be sent with any request for a function that will access or modify a user database. Temporary authorization tokens can be obtained by a call to get-login-token or a permanent authorization token can obtained by arrangement with Salesnexus.

URLs

Requests should be sent as POST requests to https://logon.salesnexus.com/api/call-v1. Accessing this URL without a POST body will only redirect to this document.

Request structure

The API uses JSON to communicate both in accepting requests and in returning results. Every request is it's own JSON object, and all function calls should be put in an array, even if there is only one request being made.

Examples

Hello World

This request block contains one function call. The "function" parameter identifies the API function that should be called, and is also how the function is identified in the documentation. The "request-id" is an optional piece of data provided by the callee, and it will be returned without modification. The intention of "request-id" is that it is used to associate returned values with particular function calls.
The result is the greeting that we requested, and the "request-id" is returned as expected.
                    
                        [{
                            "function":"greet",
                            "request-id":"simple hello world request"
                        }]  
                    
                

Echo

This request shows how parameters are sent to the Salesnexus API as a JSON object. The keys within the object are specific to the API call in question. In this case, the echo function accepts "data" as a key in the parameter object.
The result is the text that was stored in the data parameter, and the "request-id" is returned as expected.
                    
                        [{
                            "function":"echo",
                            "parameters": {
                                            "data" : "ECHO ECHO ECHO ECHO ECHO ECHO ECHO Echo Echo Echo echo echo echo ᵉᶜʰᵒ ᵉᶜʰᵒ ᵉᶜʰᵒ"
                                            },
                            "request-id":"Echo request"
                        }]  
                      

                

Multiple requests

This request shows how multiple API calls can be sent in a single HTTP request by having multiple request objects within the JSON array.
The result returned is a JSON array that contains the result of each API request. Each result is returned with the request id which can be use to map each result to the request that produced it.
                    
                        [{
                            "function":"echo",
                            "parameters": {
                                            "data" : "Echo what I say, world!"
                                            },
                            "request-id":"Echo request 1"
                        },{
                            "function":"greet",
                            "request-id":"Hello World 1"
                        },{
                            "function":"echo",
                            "parameters": {
                                            "data" : "ECHO ECHO ECHO ECHO ECHO ECHO ECHO Echo Echo Echo echo echo echo ᵉᶜʰᵒ ᵉᶜʰᵒ ᵉᶜʰᵒ"
                                            },
                            "request-id":"Echo request 2"
                        }]  
                    
                

API Calls

Session management

A session token is used to access most APIs. It is produced from an email address and a password, and is only valid for a limited amount of time. If the session token has expired, then most APIs will fail. Actions performed by the API will be undertaken by the user that has the supplied email address. If you need a permanent authorization token that will not expire, then please contact Salesnexus support.

Get Session Token

                    
                        [{
                            "function":"get-login-token",
                            "parameters": {
                                            "email-address" : "user@example.com",
                                            "password" : "p4ssw0rd"
                                            },
                            "request-id":"request to get a temporary auth token"
                        }]  
                    
                

Field management

Fields are the individual data points associated with a record in Salesnexus. For example, a contact record will have multiple fields associated with it, such as the first and last names, the email address, the company name, and the phone number. Fields are identified by an integer value. API calls that access or modify records will often need the field id to determine what data points are being accessed.
Note: all API calls will reference the Unique Id of the field that is in the result object.

Get all fields

                    
                        [{
                            "function":"get-all-fields",
                            "parameters": {
                                            "login-token" : "token"
                                            },
                            "request-id":"request to get all fields in the database"
                        }]  
                    
                
Layouts are sets of fields that are grouped by user configuration.
Each layout is associated with only one user. Layouts have a name and a list of fields associated with them, and the type of the layout. The layout type refers to the database table that the fields are associated with, which means that each layout can only include fields from a single table. Some layouts can be standard, and are included as part of Salesnexus, and cannot be deleted. Each type of layout for each user can have only one default layout.
Note: all API calls will reference the Unique Id of the field that is in the result object.

Get all layouts

                    
                        [{
                            "function":"get-user-layouts",
                            "parameters": {
                                            "login-token" : "token"
                                            },
                            "request-id":"request to get all fields in the database"
                        }]  
                    
                

User management

This set of APIs concern the management of users in the Salesnexus database.

Get all users

                    
                        [{
                            "function":"get-users",
                            "parameters": {
                                            "login-token" : "token"
                                            },
                            "request-id":"request to get all users in the database"
                        }]  
                    
                

Contact management

This set of APIs are used to manage contacts.

Create Contact

This API creates a new contact. The parameter contact-field-data is a JSON dictionary that maps the ids of each field to the value of that field. If the record manager is not specified, the user associated with the current session is used. The returned value is the id of the new contact.
Note: the ids in the "contact-field-data" are unique ids, which can be retrieved using the get-all-fields API
                    
                        [{
                            "function":"create-contact",
                            "parameters": {
                                            "login-token" : "token",
                                            "contact-field-data" : {"48": "full name", "47" : "company name", "133" : "email@addr.ess"}
                                            },
                            "request-id":"Create a contact"
                        }]  
                      
                

Get Contacts

Gets a list of contacts. The parameter filter-value is used to search on contact names, company names, and email addresses. The start-after is the position that the resulting list should start at, and the page-size parameter is the size of the result list. The order of the returned list is guarenteed, so that a the combined results of two requests made with start-after = 0 and page-size = 50 followed by a start-after = 50 and page-size = 50 will result in the same contact ids as start-after = 0 and page-size = 100.
The result contains a list of contact ids and a list of JSON objects that contains the values in each field for the contacts.
                    
                        [{
                            "function":"get-contacts",
                            "parameters": {
                                            "login-token" : "token",
                                            "filter-value" : "",
                                            "start-after" : "0",
                                            "page-size" : "50"
                                            },
                            "request-id":"Get a list of contacts"
                        }]  
                      
                

Get All Data for a Contact

Gets a all the information associated with a contact. The parameter contact-id is used to specify the contact to look up.
The result contains a list of contact ids and a list of JSON objects that contains the values in each field for the contacts.
                    
                        [{
                            "function":"get-contact-info",
                            "parameters": {
                                            "login-token" : "token",
                                            "contact-id" : ""
                                            },
                            "request-id": "Get all information for a particular contact"
                        }]  
                      
                

Get Notes For Contact

Gets all the notes associated with a contact. The parameter contact-id is used to specify the contact to look up.
The result contains a list of JSON objects that contains the values in each field of the note.
                    
                        [{
                            "function":"get-notes-for-contact",
                            "parameters": {
                                            "login-token" : "token",
                                            "contact-id" : ""
                                            },
                            "request-id": "Get all notes for a particular contact"
                        }]  
                      
                

Get Sales Opportunities For Contact

Gets all the sales opportunities associated with a contact. The parameter contact-id is used to specify the contact to look up.
The result contains a list of JSON objects that contains the values in each field of the note.
                    
                        [{
                            "function":"get-sales-for-contact",
                            "parameters": {
                                            "login-token" : "token",
                                            "contact-id" : ""
                                            },
                            "request-id": "Get all sales for a particular contact"
                        }]  
                      
                

Update Contact

Updates all contacts that match the criteria in the match-by-field-data array, with the values specified in the contact-field-data array.
The optional parameter "create-if-not-updated" is used to create a contact with the values specified in the contact-field-data array if no contact matches the "match-by-field-data". By default, it will NOT create a contact in case there is no match.
Note: the ids in the "match-by-field-data" and "contact-field-data" are unique ids, which can be retrieved using the get-all-fields API
                    
                        [
                            {
                                "function": "update-contact",
                                "parameters": {
                                    "login-token": "token",
                                    "match-by-field-data": {
                                        "99": "field-value-to-match",
                                        "100": "field2-value-to-match"
                                    },
                                    "create-if-not-updated": "false",
                                    "contact-field-data": {
                                        "101": "field-value-to-update",
                                        "102": "field2-value-to-update"
                                    }
                                },
                                "request-id": "Update a contact"
                            }
                        ]
                      
                

Import Contacts

This is a bulk version of update contact. This will take in an array of contacts to update.
Each contact to update will have a "_toMatch" array. This is an array of integers corresponding to the fieldids which should be checked for matches.
If _toMatch is not defined or empty it will skip the search for a match. A call that does not include a _toMatch field and has create-if-not-updated set to false will have no effect.
Note: An empty or missing value is considered a match. For example, if you attempt to update a contact matching by phone number and email any contact
that matches either all of the fields or some of the fields and some empty or null values will be updated. If this is not intended you need to set an optional variable "match-nulls" to false.
the ids in the "match-by-field-data" and "contact-field-data" are unique ids, which can be retrieved using the get-all-fields API
Below is an example of the array that contains the data for the contacts to update. This json array must be passed into the "contacts" parameter as an escaped string, not as a json. [ { "_toMatch": [200], "200": "barney@blackmesa.net", "35": "281-555-5554", "78": "Barn", "79": "Cal", "94": "" }, { "_toMatch": [79], "78": "Gordon", "79": "Freeman" } ]
                    
                        [
                            {
                                "function": "import-contacts",
                                "parameters": 
                                {
                                    "login-token": "f7291fab-fd28-48e3-bf85-0043edd8fc0c",
                                    "contacts": "[\r\n{\r\n\t\"_toMatch\": [200],\r\n\t\"200\": \"barney@blackmesa.net\",\r\n\t\"35\": \"281-555-5554\",\r\n\t\"78\": \"Barn\",\r\n\t\"79\": \"Cal\",\r\n\t\"94\": \"\"\r\n},\r\n{\r\n\t\"_toMatch\": [79],\r\n\t\"78\": \"Gordon\",\r\n\t\"79\": \"Freeman\"\r\n}\r\n]",
                                "create-if-not-updated": "true"
                                },

                                "request-id": "import-contacts"
                            }
                        ]
                      
                

Activities and Tasks

Get activities

Gets a list of activities associated with a user. The parameter filter-value is used to search on contact names, company names, email addresses, and regarding messages. The start-after is the position that the resulting list should start at, and the page-size parameter is the size of the result list. The order of the returned list is guarenteed, so that a the combined results of two requests made with start-after = 0 and page-size = 50 followed by a start-after = 50 and page-size = 50 will result in the same contact ids as start-after = 0 and page-size = 100. There is an optional parameter user-id that can be a user id, or if not specified is the currently logged in user .
The result contains a list of activities ids and a list of JSON objects that contains the values in each field for the activity.
                    
                        [{
                            "function":"get-activities",
                            "parameters": {
                                            "login-token" : "token",
                                            "filter-value" : "",
                                            "start-after" : "0",
                                            "page-size" : "50"
                                            },
                            "request-id":"Get a list of activity"
                        }]  
                      
                

Create activities

Schedules a new activity with the given parameters. The parameter schedule-with is the contact id that the activity will be specified for.
The parameter schedule-for is the user id that the activity will be assigned for.
The parameter regarding is a short subject for the activity.
The parameter details is the long description of the activity.
The parameter color is the hex encoded color, in RRBBGG format with no other characters.
The parameter start-time is the start time of the activity.
The parameter end-time is the end time of the activity.
The parameter type, either call, meeting, or todo.
The parameter timeless means that the activity has no specific time, only a day.
                    
                        [{
                            "function":"create-activity",
                            "parameters": {
                                            "login-token" : "token",
                                            "schedule-with" : "",
                                            "regarding" : "",
                                            "schedule-for" : "",
                                            "details" : "",
                                            "color" : "",
                                            "start-time" : "",
                                            "end-time" : "",
                                            "type" : "",
                                            "timeless" : "false"
                                            },
                            "request-id":"Make an activity"
                        }] 
                      
                

Update activities

Updates an existing activity with the given parameters. The parameter activity-id is the activity id to get updated.
The parameter schedule-with is the contact id that the activity will be specified for.
The parameter schedule-for is the user id that the activity will be assigned for.
The parameter regarding is a short subject for the activity.
The parameter details is the long description of the activity.
The parameter color is the hex encoded color, in RRBBGG format with no other characters.
The parameter start-time is the start time of the activity.
The parameter end-time is the end time of the activity.
The parameter type, either call, meeting, or todo.
The parameter timeless means that the activity has no specific time, only a day.
                    
                        [{
                            "function":"update-activity",
                            "parameters": {
                                            "login-token" : "token",
                                            "activity-id" : "",
                                            "schedule-with" : "",
                                            "regarding" : "",
                                            "schedule-for" : "",
                                            "details" : "",
                                            "color" : "",
                                            "start-time" : "",
                                            "end-time" : "",
                                            "type" : "",
                                            "timeless" : "false"
                                            },
                            "request-id":"Make an activity"
                        }] 
                      
                

Complete activities

Closes an activity and creates a note on the contact record. The parameter activity-id is the activity id to get updated.
The parameter schedule-with is the contact id that the activity will be specified for.
The parameter regarding is a short subject for the activity.
The parameter schedule-for is the user id that the activity will be assigned for.
The parameter type, either call, meeting, or todo.
The parameter color is the hex encoded color, in RRBBGG format with no other characters.
The parameter details is the start time of the activity.
The parameter result is the result of the activity, will be recorded in the note.
                    
                        [{
                            "function":"complete-activity",
                            "parameters": {
                                            "login-token" : "token",
                                            "activity-id" : "",
                                            "schedule-with" : "",
                                            "regarding" : "",
                                            "schedule-for" : "",
                                            "type" : "",
                                            "details" : "",
                                            "result" : ""
                                            },
                            "request-id":"Make an activity"
                        }] 
                      
                

Get All Data for an Activity

Gets a all the information associated with a contact. The parameter activity-id is used to specify the activity to look up.
The result contains a list of contact ids and a list of JSON objects that contains the values in each field for the contacts.
                    
                        [{
                            "function":"get-activity-info",
                            "parameters": {
                                            "login-token" : "token",
                                            "activity-id" : ""
                                            },
                            "request-id": "Get all information for a particular activity"
                        }]  
                      
                

Campaigns

Get All Campaigns


The result contains a list of JSON objects that contains the values in each field for the campaign.
                    
                        [{
                            "function":"get-campaigns",
                            "parameters": {
                                            "login-token" : "token"
                                            },
                            "request-id": "Get all campaigns as a list"
                        }]  
                      
                

Add To Campaigns

Adds a list of contact ids to a given campaign.
                    
                        [{
                            "function":"add-to-campaign",
                            "parameters": {
                                            "login-token" : "token",
                                            "campaign-id" : "campaign-id",
                                            "contact-ids" : ["contact-id list"]
                                            },
                            "request-id": "Adds a list of contacts to a campaign"
                        }]  
                      
                

Sales Opportunities

Get Sales Opportunities

Get a list of sales opportunities.
                    
                        [{
                            "function":"get-sales",
                            "parameters": {
                                            "login-token" : "token",
                                            "start-after" : "start-after",
                                            "page-size" : "page-size",
                                            "filter-value" : ""
                                            },
                            "request-id": "Get a list of sales opportunities"
                        }]  
                      
                

Create Sales Opportunity

Create a sales opportunity. The status field is marked as follows: 0 - open, 1 - won, 2 - lost.
Note: the ids in the "sales-field-data" are unique ids, which can be retrieved using the get-all-fields API
                    
                        [{
                            "function":"create-sales-opp",
                            "parameters": {
                                            "login-token" : "token",
                                            "sales-field-data" : {
                                                "220" : "contact-id",
                                                "231" : "details",
                                                "222" : "status",
                                                "234" : "sales state"
                                            }
                                        },
                            "request-id": "Get a list of sales opportunties"
                        }]  
                      
                

Notes Management

Create Note

Create a note for a given contact. Type codes can be found here.
If no user-id is specified, the user-id associated with the login token is used.
                    
                        [{
                            "function":"create-note",
                            "parameters": {
                                            "login-token" : "token",
                                            "details" : "details",
                                            "contact-id" : "contact-id",
                                            "user-id" : "user-id",
                                            "type" : "type"
                                        },
                            "request-id": "Create a note"
                        }]