API Documentation

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

Last Updated: 08/01/2024

API Keys and Authorization Tokens
1. API Keys
2. Authorization Token
API URL
Request Structure
1. Examples
API Calls

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 ᵉᶜʰᵒ ᵉᶜʰᵒ ᵉᶜʰᵒ"
                                            },
                            "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 ᵉᶜʰᵒ ᵉᶜʰᵒ ᵉᶜʰᵒ"
                                            },
                            "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"
                        }]

Get Documents for Contact

Gets all the documents 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 documents.

                    
                        [
                            {
                                "function": "get-docs-for-contact",
                                "parameters": {
                                    "login-token": "token",
                                    "contact-id" : ""
                                },
                                "request-id": "Get documents for a contact"
                            }
                        ]

Upload a Document to a Contact

Upload a document to a contact by encoding the document's binary to base64 and adding it as parameter. The parameter contact-id is used to specify the contact to look up.
The result contains validation of uploaded document.

                    
                        [
                            {
                                "function": "add-doc-to-contact",
                                "parameters": {
                                    "login-token": "token",
                                    "contact-id" : "",
                                    "file-name" : "",
                                    "base64-data" : ""
                                },
                                "request-id": "Uplaod a document to a 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"
                            }
                        ]

Delete Contacts

Remove the contact from the contacts list.
Parameters:
"contact-ids-to-delete" - is used to specify the contacts that you want to delete. An array of GUID string.
Reasons a call will not proceed:
- Invalid paramaters.
- Invalid contact id format.
- All contact ids in the parameter does not exist in the contact list
Note:
- Deletion of contact can not be undone.
- Contact's asssociated information such as Sales, Notes/History, Task/Activity, and uploaded documents are also deleted.

                    
                        [{
                            "function":"delete-contacts",
                            "parameters": {
                                            "login-token" : "token",
                                            "contact-ids-to-delete" : [""]
                                          },
                            "request-id": "Delete Contacts"
                        }]

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": "token",
                                    "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"
                            }
                        ]

Group management

This set of APIs are used to manage groups.

Get Groups

Gets a list of groups. The parameter filter-value is used to search on group names. 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 group ids as start-after = 0 and page-size = 100.
The result contains a list of groups ids and a list of JSON objects that contains the values in each field for the groups.

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

Get All Data for a Group

Gets a all the information associated with a group. The parameter group-id is used to specify the group 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-group-info",
                            "parameters": {
                                            "login-token" : "token",
                                            "group-id" : ""
                                            },
                            "request-id": "Get all information for a particular group"
                        }]

Get All Activities for a Group

Gets a list of activities associated with a group. The parameter group-id is used to specify the group to look up. 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 activity as start-after = 0 and page-size = 100.
The result contains a list of JSON objects that contains the values in each field of the activities.

                    
                        [{
                            "function":"get-activities-for-group",
                            "parameters": {
                                            "login-token" : "token",
                                            "group-id" : "",
                                            "start-after" : "0",
                                            "page-size" : "50"
                                            },
                            "request-id": "Get activities for a particular group"
                        }]

Get All Sales for a Group

Gets a list of sales associated with a group. The parameter group-id is used to specify the group to look up.
The result contains a list of JSON objects that contains the values in each field of the sales.

                    
                        [{
                            "function":"get-sales-for-group",
                            "parameters": {
                                            "login-token" : "token",
                                            "group-id" : ""
                                            },
                            "request-id": "Get sales for a particular group"
                        }]

Get All Notes for a Group

Gets a list of notes associated with a group. The parameter group-id is used to specify the group to look up.
The result contains a list of JSON objects that contains the values in each field of the notes.

                    
                        [{
                            "function":"get-notes-for-group",
                            "parameters": {
                                            "login-token" : "token",
                                            "group-id" : ""
                                            },
                            "request-id": "Get notes for a particular group"
                        }]

Update a Group

Updates all groups 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 group with the values specified in the contact-field-data array if no group matches the "match-by-field-data". By default, it will NOT create a group 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-group",
                                "parameters": {
                                    "login-token": "token",
                                    "match-by-field-data": {
                                        "99": "field-value-to-match",
                                        "100": "field2-value-to-match"
                                    },
                                    "create-if-not-updated": false,
                                    "group-field-data": {
                                        "101": "field-value-to-update",
                                        "102": "field2-value-to-update"
                                    }
                                },
                                "request-id": "Update a group"
                            }
                        ]

Delete Groups

Remove the group from the groups list.
Parameters:
"group-ids-to-delete" - is used to specify the groups that you want to delete. An array of GUID string.
Reasons a call will not proceed:
- Invalid paramaters.
- Invalid group id format.
- All group ids in the parameter does not exist in the group list
Note:
- Deletion of group can not be undone.
- Group's asssociated information such as Sales, Notes/History, Task/Activity are also deleted.
- But asssociated information such as Sales and Task/Activity that are assgined to a contact will not be deleted.

                    
                        [{
                            "function":"delete-groups",
                            "parameters": {
                                            "login-token" : "token",
                                            "group-ids-to-delete" : [""]
                                          },
                            "request-id": "Delete groups"
                        }]

Create Note for Group

Create a note for a Group
Parameters:
"details" - is the text details of the note
"group-id" - group Id of the note taken for
"user-id" - the ID of the user who made the note. If no user-id is specified, the user-id associated with the login token is used.
"type": - type codes can be found [here]

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": "create-note-for-group",
                                "parameters": {
                                    "login-token": "token",
                                    "details": "details",
                                    "group-id": "group-id",
                                    "user-id": "user-id",
                                    "type": "type"
                                },
                                "request-id": "Create a note"
                            }
                        ]

Create Activity for Group

Create a activity for a Group
Parameters:
"group-id" - is the group id that the activity will be specified for.
"schedule-with" - is the contact id that the activity will be specified for.
"schedule-for" - is the user id that the activity will be assigned for.
"regarding" - is a short subject for the activity.
"details" - is the long description of the activity.
"color" - is the hex encoded color, in RRBBGG format with no other characters.
"start-time" - is the start time of the activity.
"end-time" - is the end time of the activity.
"type" - either call, meeting, or todo.
"timeless" - means that the activity has no specific time, only a day.

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": "create-activity-for-group",
                                "parameters": {
                                    "login-token": "token",
                                    "group-id": "",
                                    "schedule-with": "",
                                    "regarding": "",
                                    "schedule-for": "",
                                    "details": "",
                                    "color": "",
                                    "start-time": "",
                                    "end-time": "",
                                    "type": "",
                                    "timeless": "false"
                                },
                                "request-id": "Make an activity"
                            }
                        ]

Get Contacts for a Group

Gets a list of contacts associated with a group. The parameter group-id is used to specify the group to look up.
The result contains a list of JSON objects that contains the values in each field of the contact.

                    
                        [{
                            "function":"get-contacts-for-group",
                            "parameters": {
                                            "login-token" : "token",
                                            "group-id" : ""
                                          },
                            "request-id": "Get contacts for a particular group"
                        }]

Add Contacts to a Group

Add a list of contacts to a group.
Parameters:
"group-id" - is used to specify the group to add contacts to. Is GUID string.
"contact-ids" - is used to specify the contacts to add to the group. An array of GUID string.
Reasons a call will not proceed:
- Invalid paramaters.
- Invalid group id format.
- Invalid contact id format.
Reasons a contact will not be added:
- The contact is aready added to the group.
- The contact does not exist in the contacts table.

                    
                        [{
                            "function":"add-contacts-to-group",
                            "parameters": {
                                            "login-token" : "token",
                                            "group-id" : "",
                                            "contact-ids" : [""]
                                          },
                            "request-id": "Add contacts to a particular group"
                        }]

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"
                        }]