Nimble API Documentation

Feb 13, 2018 | Publisher: edocr | Category: Business & Jobs |  | Collection: Business Ideas | Views: 13 | Likes: 2

Nimble API Documentation Release 1.3.0 Nimble September 07, 2016 Contents 1 Overview 3 2 Nimble API Responses 5 2.1 Contacts details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 2.2 Contact list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 2.3 API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 3 Contacts API 13 3.1 Basic Contacts API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 3.2 Contact Notes API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 3.3 Contacts Metadata API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 4 Full description of Nimble default contact fields 47 4.1 Field types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 4.2 Nimble default fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 4.3 Nimble default field groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 4.4 Nimble fields presentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 5 Activities API 55 5.1 Tasks API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 6 Tutorial: Obtain Nimble API Key 57 6.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 6.2 Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 6.3 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 6.4 Authorization process overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 6.5 Requesting Authorization Grant Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 6.6 Requesting Access Token . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 6.7 API requests using Access Token . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 6.8 Refresh token after expiration without user input . . . . . . . . . . . . . . . . . . . . . . . . . . 60 6.9 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 6.10 Troubleshooting & Feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 7 Tutorial: Making authenticated requests 63 7.1 Authenticating your request with URL parameter . . . . . . . . . . . . . . . . . . . . . . . . . . 63 7.2 Authenticating your request with HTTP header . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 8 Examples and libraries 65 8.1 Javascript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 8.2 NodeJS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 8.3 Python . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 8.4 Ruby . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 i 9 Nimble API changes history 67 10 Getting help 69 ii Nimble API Documentation, Release 1.3.0 Actual Nimble API version - 1.3 Contents: Contents 1 Nimble API Documentation, Release 1.3.0 2 Contents CHAPTER 1 Overview Nimble is a social relationship management tool that brings together your contacts from many disparate locations into one place; gives you a dynamic, 360 view of each contact; and helps you nurture the new and important contacts in your network. The Nimble platform offers access to the stored data via our APIs. Currently, only contact data is accessible via our REST API, and this data is available with limited functionality under the "beta" label. We plan on releasing additional functionality in the following order: GET contact list and contact detail, includes simple SEARCH available CREATE/UPDATE/DELETE contact - available GET contact list with advanced SEARCH - available GET/CREATE/UPDATE/DELETE custom fields and groups via metadata API - available GET/CREATE/UPDATE/DELETE notes related to contacts - available CREATE related activities - available GET related activities - TBD GET related messages - TBD GET related social - TBD MERGE contact - TBD Given the early state of the API, some aspects of the API are subject to change. We are building the API with a few main use cases in mind: widgets/extensions to Nimble, web clients (including our own), mobile clients. and ultimately 2-way data integrations with other services. We aspire to make an API that is simple to use, easy to read, and flexible. Your feedback is greatly appreciated while we continue to shape our API offering. 3 Nimble API Documentation, Release 1.3.0 4 Chapter 1. Overview CHAPTER 2 Nimble API Responses Contents Nimble API Responses Contacts details * Contact resources * Contacts metadata Contact list * Pagination metadata API Errors * Validation Error * Quota Error * Server error * NotFound Error 2.1 Contacts details Typical response to this request is a dictionary with 2 keys (unless otherwise specified by the specific API): meta and resources. 2.1.1 Contact resources This field usually contains all data for the contacts you've requested. Here is an example of a Nimble contact 'resources': [{ 'updated': '2012-09-07T16:49:56+0300', 'created': '2012-09-07T16:49:56+0300', 'fields': { "parent company": [ { "group": "Basic Info", "name": "parent company", "label": "parent company", "modifier": "", "presentation": {}, "id": "5049f697a694620a0700004d", "multiples": false } ], 'description': [{ "group": "Extra Info", "name": "description", 5 Nimble API Documentation, Release 1.3.0 "label": "description", "modifier": "other", "presentation": {}, "id": "5049f697a694620a0700007f", "multiples": true }, { "group": "Extra Info", "name": "description", "label": "description", "modifier": "linkedin", "presentation": {}, "id": "5049f697a694620a07000082", "multiples": true }], 'last name': [{ 'field_id': '5049f697a694620a07000045', 'modifier': '', 'group': 'Basic Info', 'value': 'Akopyan', 'label': 'last name' }], 'phone': [{ 'field_id': '5049f697a694620a07000058', 'modifier': 'mobile', 'group': 'Contact Info', 'value': '+7 (917) 202-456-1111', 'label': 'phone' }, { 'field_id': '5049f697a694620a07000056', 'modifier': 'home', 'group': 'Contact Info', 'value': '+7 244 231 84 22', 'label': 'phone' }], 'URL': [{ 'field_id': '5049f697a694620a0700007d', 'modifier': 'other', 'group': 'Extra Info', 'value': 'https://nimble.com', 'label': 'URL' }, { 'field_id': '5049f697a694620a0700007d', 'modifier': 'other', 'group': 'Extra Info', 'value': 'https://app.nimble.com', 'label': 'URL' }], 'source': [{ 'field_id': '5049f697a694620a0700004f', 'modifier': '', 'group': 'Basic Info', 'value': 'csv', 'label': 'source' }], 'address': [{ 'field_id': '5049f697a694620a07000075', 'modifier': 'other', 'group': 'Contact Info', 'value': '{"city": "Dushanbe", "street": "First str. 15", "zip": "54055", "country": " 'label': 'address' }], 'email': [{ 'field_id': '5049f697a694620a07000065', 6 Chapter 2. Nimble API Responses Nimble API Documentation, Release 1.3.0 'modifier': 'other', 'group': 'Contact Info', 'value': 'fake_person@nimble.com', 'label': 'email' }], 'first name': [{ 'field_id': '5049f697a694620a07000043', 'modifier': '', 'group': 'Basic Info', 'value': 'Amayak', 'label': 'first name' }] }, 'object_type': 'contact', 'id': '5049fb849b85f669e40000dc', 'last_contacted': { 'last_contacted': '2012-09-17T11:43:51+0300',, 'thread_id': 5049f697a694620a07000062, 'message_id': 5049f697a694620a17000075 }, 'avatar_url': 'https://app.nimble.com/api/contacts/avatars/5049fb849b85f669e40000dc' 'record_type': 'person', 'creator': 'Emil Kio', 'children': [], 'tags': [{ 'tag': 'csv import', 'id': '5049fa0c9b85f62cb4000639' }], 'owner_id': '5049f696a694620a0700001c' }] Here is a description of the response in detail: updated Timestamp of contact's last update time created Timestamp of contact's creation time fields Dictionary containing contact's fields data. Keys are field names and values are lists of field values. All default contact fields are described here. object_type String specifying document type. For contacts it's contact. id Unique contact id in BSON format. last_contacted Information about last outbound message to this contact (if any). Contains following fields. last_contacted timestamp of last outbound message thread_id unique id of message thread in BSON format message_id unique id of message in BSON format avatar_url URL of image that can be used as contact's avatar. Value of null is used to indicate that contact has no avatar associated. record_type Type of contact. This can have one of two values: person and company. creator Name of the person who created the contact children For company contacts this field contains list of person contacts associated with the company. tags List of tags associated with the contact. Each tag is represented as a dictionary having following keys. tag tag's text 2.1. Contacts details 7 Nimble API Documentation, Release 1.3.0 id unique id of tag in BSON format owner_id Id of the person owning the contact in BSON format 2.1.2 Contacts metadata Contact's metadata contains information about all basic and custom fields created in Nimble for a user. Below is it's typical structure. Please note that this listing doesn't contain all metadata as the full list is very big. The typical records are shown here. All default contact fields are described here. 'contacts_meta': { 'fields': { 'first name': [{ "group": "Basic Info", "name": "first name", "label": "first name", "modifier": "", "presentation": {}, "id": "5049f697a694620a07000043", "multiples": false }], 'email': [{ "group": "Contact Info", "name": "email", "label": "email", "modifier": "other", "presentation": {}, "id": "5049f697a694620a07000065", "multiples": true }, { "group": "Contact Info", "name": "email", "label": "email", "modifier": "personal", "presentation": {}, "id": "5049f697a694620a07000064", "multiples": true }], 'lead status': [{ "group": "Lead Details", "name": "lead status", "label": "lead status", "modifier": "", "presentation": { "width": "1", "next_id": "5", "values": [ { "id": "1", "value": "Open" }, { "id": "2", "value": "Contacted" }, { "id": "3", "value": "Qualified" }, { "id": "4", "value": "Unqualified" 8 Chapter 2. Nimble API Responses Nimble API Documentation, Release 1.3.0 } ], "type": "select-box" }, "id": "5049f697a694620a0700008d", "multiples": false }] }, 'groups': { 'Basic Info': { "name": "Basic Info", "order": [ "first name", "last name", "middle name", "company name", "title", "parent company", "source", "last contacted" ], "is_standard": true, "label": "Basic Info", "type": "both", "id": "5049f696a694620a07000031" } } } Here is a description of the response in detail: fields Information about the fields in Nimble. Represented by dictionary where keys are fields names, and values are lists containing details about all possible modifications of this field. If field have no modifiers (like first name on example above), this list contains only one element. Information stored in dictionaries with following keys: group unique name of the group containing this field. label unique name representing the field in human-readable form. modifier name of the field's modifier id unique id of the field in BSON format multiples - indicates whether field could have multiple values (under different modifiers). presentation - dict with the information which should help to display this field on client. More details are at described here. groups Information about field groups. Represented by dictionary where keys are unique group names and values are diction id unique id of the group in BSON format. order list containing names of the fields as they appeared in group. name unique name of the group. (Outdated: as we have field name as the key of groups dictionary.) label unique name representing the field in human-readable form. is_standard - whether this group belongs to standard Nimble groups. type - type (belonging) of group, could be among person, company, both. 2.1. Contacts details 9 Nimble API Documentation, Release 1.3.0 2.2 Contact list Contact list request is similar to Contacts details. It has the same key with resources, described here. Difference is in meta key value. For contact listing it returns pagination details. 2.2.1 Pagination metadata 'meta': { 'per_page': 30, 'total': 45, 'pages': 2, 'page': 1 } Keys meaning: per_page Number of contacts returned per page total Total number of contacts pages Total pages count page Current page number 2.3 API Errors Errors in Nimble are returned as a JSON dictionary with appropriate HTTP error codes and following keys: message Message about the error code Extended error code 2.3.1 Validation Error Sent on invalid parameters. Returns with HTTP code 409 and code field equal to 245. This response looks like common error dictionary: { "message": "You can specify either`keyword` or`query` parameter, not both!", "code": 245 } On contact creation and update additional data is returned. { "message": "Validation errors", "code": 245, "errors": { "first name": [{ "message": "First name or last name field is required for person and should not be emp "field_id": "5049f697a694620a07000043" }] } } Here errors are a dictionary, containing information about field that caused the error. Key is field name and values are extended error message and unique id of the field that caused the error. 10 Chapter 2. Nimble API Responses Nimble API Documentation, Release 1.3.0 2.3.2 Quota Error Sent if user exceeded his quota values. Returns with HTTP code 402 and code field equal to 108. { "message": "You have created the maximum number of contact records allowed for your subscripti "code": 108 } 2.3.3 Server error Sent if unrecoverable Nimble server occurs. Returns with HTTP code 500 and code field equal to 107. { "message": "Internal error handling request", "code": 107 } 2.3.4 NotFound Error Sent on attempt to get some object by invalid identifier (in most cases identifier of object is its ID in our database). This response will contain dictionary with object_type and object_id fields: { "object_type": "contact field", "object_id": "111111111111111111111111" } 2.3. API Errors 11 Nimble API Documentation, Release 1.3.0 12 Chapter 2. Nimble API Responses CHAPTER 3 Contacts API Contents: 3.1 Basic Contacts API Contents: 3.1.1 Get contacts list Request For contacts listing we support two endpoints: base, returning full contact info, and ids-only endpoint that return only contact ids. Last one works faster then base one, so if you need only ids please use it. Base endpoint: GET https://api.nimble.com/api/v1/contacts/ IDs endpoint: GET https://api.nimble.com/api/v1/contacts/ids/ Parameters All parameters are optional. Unrecognized parameters are ignored. Unrecognized values will return an error. fields default: all fields in contact Specifies a comma separated list of fields to return. If this parameter is excluded, all fields will be returned. For example: fields=first%20name,my%20custom%20field. For more detailed info on Nimble's fields see Nimble default fields. Note: If field name contains "," (comma) it should be shielded with "\". For exam- ple: we have some custom field with name "hello, Jon Doe" it should be HTML-encoded in hello%5C%2C%20John%20Doe (hello\, John Doe). tags default: 1 Specifies whether tags should be included in the results. per_page default: 30 Specifies the number of items to return per page of results. 13 Nimble API Documentation, Release 1.3.0 page default: 1 Specifies which page to display. Numeration starts from 1. sort default: none Identifies the sort field and sort order. Sort order is required when this parameter is used. An single sort field can be specified. Any field can be sorted in either asc or desc order. All searchable fields which aren't multiple and aren't custom fields are sortable. Note: There is no way to sort requests which have size more then 100 contacts. In order to sort results you should set per_page with number less or equal 100. We suggest to use score sorting if contain type of occurrence or keyword parameter is used. Information about if field is multiple can be retrieved from fields metadata. There are some notes for special fields: Table 3.1: Special sortings Name Meaning Note re- cently viewed sorts by user's recently viewed contacts When sorting by recently viewed, these parameters are disabled: keyword, record type, page and per_page. Nimble stores only the 30 most recently viewed records. score sorts by relevance to search request This sorting only have sense when you are performing search request with contains type of occurrence. users last con- tacted sorts by recently contacted by user contacts When sorting by user's last contacted, these parameters are disabled: keyword and record type. record_type default: all Identifies the record type. Possible value are person, company, and all. keyword default: empty Specifies a set of simple search criteria for the query. This simple search is performed on any (indexed in our search engine) fied of contact. For example: keyword=Jon%20Smith We suggest to use score sorting with this parameter. query default: empty Specifies query for contacts advanced search. Please note, that this parameter not com- patible with parameters record_type and keyword. For more details about search see Search contacts. Response: OK List and Detail response format is the basically the same. List allows search terms, sort orders, and fields as parameters, whereas detail returns all of the fields with the option of adding metadata. In more details, this format described here. Example response for IDs only request: { "meta": { "page": 1, "pages": 1, "per_page": 30, "total": 2 }, "resources": [ "4f69fb852ab3740c5e000004", "5e69fb852ab3f40d5e050017" 14 Chapter 3. Contacts API Nimble API Documentation, Release 1.3.0 ] } Response: Errors Possible errors: Validation Error 3.1.2 Search contacts Basic concepts All values putted to search (values of the objects by which search is performed and the text of search request) are converted to lowercase and are subjected to procedure of ascii folding Examples: 1. "cAr" is the same as "car" 2. "car" is the same as "car" 3. "CAR" is the same as "car" No any another normalization procedures are used. (plural, phonetic, etc) For some fields like social network profiles, emails, phones special chars escaping are being done. Advanced search query syntax Query language for Advanced search is JSON encoded structure. Short example of querying all persons with skype "john.doe": { "and": [ { "skype id": { "is": "john.doe", } }, { "record type": { "is": "person" } } ] } For more examples, see examples. Terminology Based on example above, let's define basic terminology: and is join operator for occurrences skype id (john.doe) is a term to search by is is occurrence of term in search index record_type (person) is a value for occurrence 3.1. Basic Contacts API 15 Nimble API Documentation, Release 1.3.0 Joins Possible variants for join operators are and and or. They could be combined in different ways and priorities. Some examples with explanations will be listed below. Let's define several occurrences: o1 = { "skype id": { "is": "john.doe" } }; o2 = { "record type": { "is": "person" } }, o3 = { "first name": { "contain": "John" } }, o4 = { "created": { "range": { "start_date": "2012-02-13", "end_date": "2012-02-23", } } } Join like o1 and o2 and o3 and o4: { "and": [o1, o2, o3, o4] } Join like (o1 and o2) or o3 and o4: { "and": [o4, {"or": [o3, {"and": [ o1, o2 ] } ] } ] } Join like (o1 and o2) or (o3 and o4): { "or": [{"and": [ o1, o2 ] }, {"and": [ o3, o4 ] }] } Note: Maximum limit of occurrences in one request query is 11; If request could be done without join operators then it should contain only single occurrence. Search operators Note: To get relevant results you may use sorting by relevance. 16 Chapter 3. Contacts API Nimble API Documentation, Release 1.3.0 Note: In the table below (old) means only another(previously used) behaviour of search operator, API param- eters is still same. 3.1. Basic Contacts API 17 Nimble API Documentation, Release 1.3.0 Table 3.2: Full list of available search operators Operator Description Example contain looks for EXACT match of ANY word from provided request in the words of specified contact field. Only WHOLE words from query and contact data are used. There is no additional analysis for part of word. Some of words in provided search request (one or more) for specified field is equal to some word (one or more) in field of contact (contacts). This contacts will be returned as re- sult of search request. For example you are searching for Jon Pupken in name field So contacts with the following name will be matched: JON PUPKEN, JON travolta, James PUPKEN Contacts with this names will not be matched: JaN PUPKEr, JONy PoPov As more equal words from request string are in contact field as higher contact is in returned list if sorting set to by relevance in de- scending order. Query exapmle: {"address": {"contain": "Greater LA"}} contain(old) Provided value matches field value from LEFT OR RIGHT side. For example *document_value or document_value*. But not both. For example you are searching for POPOV in last_name field So contacts with the following name will be matched: POPOV, POPOVa, POPOVenko, podPOPOV Contacts with this names will not be matched: PuPken, podPOPOVenko Query example: {"first name": {"contain": "aaa"}} starts_with Provided value matches field value from LEFT side. For example document_value*. For example you are searching for POPOV in last_name field So contacts with the following name will be matched: POPOV, POPOVa, POPOVenko Contacts with this names will not be matched: PuPken, podPOPOVenko, podPOPOV Query example: {"first name": {"starts_with": "value"}} is Provided value is equal to field value {"record type": {"is": "all"}} is_empty Feild value with specified name is absent or empty {"last name": {"is_empty": True}} in_the_last Date field value of matched documents is within last X days/weeks/monthes {"created": {"in_the_last": {"unit": "day", "quantity": 2}}} range Date field value of matched doc- uments is within specified period. There are two types of selector for range occurrence type. date - simple case. Provided date will be converted to user timezone. Expected format is %Y-%m-%d datetime - provided date is ex- pected to be in UTC in rfc3339 for- {"company last contacted": {"range": {"start_date": "2013-03-19", "end_date": "2013-03-19"}}} {"company last contacted": {"range": {"start_datetime": 18 Chapter 3. Contacts API Nimble API Documentation, Release 1.3.0 Available search fields Table 3.3: Full list of available field types for searching on them Field name Possible operators email is, is_not, contain(old), not_contain(old), is_empty skype id is, is_not, contain(old), not_contain(old), is_empty twitter is, is_not, contain(old), not_contain(old), is_empty linkedin is, is_not, contain(old), not_contain(old), is_empty facebook is, is_not, contain(old), not_contain(old), is_empty phone is, is_not, contain(old), not_contain(old), is_empty last name is, is_not, contain(old), not_contain(old), is_empty street is, is_not, contain, not_contain, is_empty city is, is_not, contain, not_contain, is_empty state is, is_not, contain, not_contain, is_empty zip is, is_not, contain, not_contain, is_empty country is, is_not, contain, not_contain, is_empty company name is, is_not, contain, not_contain, is_empty title is, is_not, contain, not_contain, is_empty name is, is_not, contain(old), not_contain first name is, is_not, contain(old), not_contain lead source is, is_not, is_empty lead type is, is_not, is_empty lead status is, is_not, is_empty rating is, is_not, is_empty, gt, lt, lte, gte created in_the_last, range updated in_the_last, range company last contacted in_the_last, range address contain, not_contain, is_empty tag is custom_fields is, is_not, contain, not_contain, is_empty record type is description contain, not_contain, is_empty More search examples Search all contacts with specified type: {"record type": {"is": "person"}} Search contacts with name, containing "Gal" and tagged with specific tag: { "and": [{ "first name": { "contain": "Gal" } }, { "tag": { "is": "csv import2" } }] } Search for contacts without values in city field: {"city": {"is_empty": False}} Search for contacts, created in given date range: 3.1. Basic Contacts API 19 Nimble API Documentation, Release 1.3.0 { "created": { "range": { "start_date": "2012-10-16", "end_date": "2012-10-18" } } } Search for specific value in custom field: {"custom_fields": {"custom field1": {"is": "value"}}} Note: If your custom field is select-box, in search you should specify not it's value, but id of this value. For example, if you have field with following values: "values": [ { "id": "1", "value": "Open" }, { "id": "2", "value": "Closed" } ] You should use 2 as value, if you want to find contacts with field equal to closed. For example: {"custom_fields": {"comminication state": {"is": "2"}}} Validation To validate join operators, occurrences and values we're using "Json Schema" standard. Current implementation of rules is built with json-schema Draft 3. Please, use this draft for better understanding of query language rules. In Nimble we're using json-schema python library to validate user search queries. Also, on github you can find the library from one of the json-schema authors json-schema-validator. It's fully implementing draft 3 spec, and can be used as reference library. Top level validation schema { "additionalProperties": false, "patternProperties": { "^(email|skype id|twitter|linkedin|facebook|phone|last name|title|description|street|c "required": true, "type": "object" } }, "type": "object", "description": "top level (all fields) validation rule" } Joins validation schema { "additionalProperties": false, "patternProperties": { "^(or|and)$": { 20 Chapter 3. Contacts API Nimble API Documentation, Release 1.3.0 "minItems": 2, "type": "array" } }, "type": "object" } Schema for validation of default fields occurrences { "patternProperties": { "^(email|skype id|twitter|linkedin|facebook|phone|last name|street|city|state|zip|coun "additionalProperties": false, "patternProperties": { "^(is|is_not|contain|not_contain|is_empty)$": { "minLength": 2, "required": true, "type": ["string", "boolean"] } }, "type": "object" } }, "type": "object", "description": "/twitter/linkedin/facebook/phone/last name/street/city/state/zip/country/compa } Schema for validation of full name/first name fields { "patternProperties": { "^(name|first name)$": { "additionalProperties": false, "patternProperties": { "^(is|is_not|contain|not_contain)$": { "minLength": 2, "required": true, "type": "string" } }, "type": "object" } }, "type": "object", "description": "name/first name validation rules. name == first name + last name" } Schema for validation of lead source/lead type field { "type": "object", "description": "lead source/lead type validation rules", "patternProperties": { "^(lead source|lead type)$": { "additionalProperties": false, "patternProperties": { "^(is|is_not|is_empty)$": { "required": true, "type": ["string", "boolean"] } }, "type": "object" } } 3.1. Basic Contacts API 21 Nimble API Documentation, Release 1.3.0 } Schema for validation of created occurrences { "type": "object", "description": "created validation rule", "properties": { "created": { "type": [ { "type": "object", "description": "sub-schema for validation range type occurrence", "properties": { "range": { "additionalProperties": false, "required": true, "type": "object", "properties": { "start_date": { "required": true, "type": "string", "description": "start date in format YYYY-MM-DD", "format": "date" }, "end_date": { "required": true, "type": "string", "description": "end date in format YYYY-MM-DD", "format": "date" } } } } }, { "type": "object", "description": "sub-schema for validation in the last type occurrence", "properties": { "in_the_last": { "additionalProperties": false, "required": true, "type": "object", "properties": { "quantity": { "required": true, "type": "integer", "description": "quantity of units, like 10 days, 2 months etc" }, "unit": { "required": true, "type": "string", "description": "possible types of period", "enum": ["day", "month", "week"] } } } } } ] } } } 22 Chapter 3. Contacts API Nimble API Documentation, Release 1.3.0 Schema for validation of address occurrences { "type": "object", "description": "address validation rule", "properties": { "address": { "additionalProperties": false, "patternProperties": { "^(contain|not_contain|is_empty| )$": { "minLength": 2, "required": true, "type": ["string", "boolean"] } }, "type": "object" } } } Schema for validation of tag occurrences { "type": "object", "description": "tag validation rule", "properties": { "tag": { "additionalProperties": false, "type": "object", "properties": { "is": { "minLength": 2, "required": true, "type": "string" } } } } } Schema for validation of custom fields { "type": "object", "description": "custom field validation rule", "properties": { "custom_fields": { "type": "object", "patternProperties": { "^.{1,150}$": { "additionalProperties": false, "required": true, "type": "object", "patternProperties": { "^(is|is_not|contain|not_contain|is_empty)$": { "required": true, "type": ["string", "boolean"] } } } } } } } 3.1. Basic Contacts API 23 Nimble API Documentation, Release 1.3.0 Schema for validation of record type { "type": "object", "description": "record type validation rule", "properties": { "record type": { "additionalProperties": false, "type": "object", "properties": { "is": { "minLength": 2, "required": true, "type": "string", "enum": ["all", "person", "company"] } } } } } Schema for validation of description { "type": "object", "description": "description validation rule", "properties": { "description": { "additionalProperties": false, "patternProperties": { "^is_empty|contain|not_contain$": { "minLength": 2, "required": true, "type": ["string", "boolean"] } } } } } API endpoints Advanced search requests should be done through statard contacts listing entry point: GET /api/v1/contacts Parameters are the same as for regular listing, except new one: query Should contain url-encoded JSON. Syntax of queries is described above. Note: Parameter record_type will be ignored, if query parameter was specified. To filter per- sons/companies, please use corresponding sub query in query. Note: Parameter keyword will be ignored, if query parameter was specified. Request example 1: 24 Chapter 3. Contacts API Nimble API Documentation, Release 1.3.0 https://api.nimble.com/api/v1/contacts?query=%7B%22first%20name%22%3A%20%7B%22is%22%3A%20%22Anton% Advanced search query in this request is: { "first name": { "is": "Anton" } } Request example 2: https://api.nimble.com/api/v1/contacts?query=%7B%22and%22%3A%20%5B%7B%22last%20name%22%3A%20%7B%22 Advanced search query in this request is: { "and": [ { "last name": { "is": "Ferrara" } }, { "first name": { "is": "Jon" } } ] } Response: OK On success, results are returned in format, similar to contacts listing response. Response: Errors Possible errors: Validation Error 3.1.3 Get contacts details Single and bulk requests ore formatted and returned in the same way. The response format for each field is the same as returned in a contacts listing response. Metadata can be included in the response. Request Base endpoint: GET https://api.nimble.com/api/v1/contact/[,,,...] Example: GET https://api.nimble.com/api/v1/contact/5049fb9b9b85f669e4000447,5049fb7d9b85f669e4000066,5049fb 3.1. Basic Contacts API 25 Nimble API Documentation, Release 1.3.0 Parameters All parameters are optional. Unrecognized parameters are ignored. Unrecognized values will return an error. meta default: 0 When included and equal to 1, the meta parameter will add an additional component to the response which describes all fields, field types, and possible values available on the record. For further reference see Contacts metadata. fields default: all fields in contact Specifies a comma separated list of fields to return. If this parameter is ex- cluded, all fields will be returned. For example: fields=first%20name,my%20custom%20field. For more detailed info on Nimble's fields see Nimble default fields. Note: If field name contains "," (comma) it should be shielded with "\". For example: we have some cus- tom field with name "hello, Jon Doe" it should be HTML-encoded in hello%5C%2C%20John%20Doe (hello\, John Doe). tags default: 1 Specifies whether tags should be included in the results. Response: OK List and Detail response format is the basically the same. List allows search terms, sort orders, and fields as parameters, whereas detail can only limit fields to return and provide the option of adding metadata. In more details, this format described here. Response: Errors Possible errors: Validation Error 3.1.4 Create contact Request Example: POST https://api.nimble.com/api/v1/contact Parameters All parameters are passed as JSON in request body. record_type required Specifies the type of contact to create - the record type. This parameter could be one of two values: company or person. fields required Describes a dictionary organized in the same structure as a contact listing response. In this structure, each key is field name. Values are lists of dictionaries, having two fields: value - actual value to store in contact field, modifier - field modifier to use, if field can have one. At a minimum, contacts require a name (first or last for a person, company name for a company). tags optional, default: None Comma separated list of tags to assign to contacts. If you need to create tags, containing comma sign escape it with backslash. E.g. our customers,best\,premium will create tags our customers and best,premium. Note: Maximum 5 tags are allowed in this list during contact creation. 26 Chapter 3. Contacts API Nimble API Documentation, Release 1.3.0 avatar_url optional, default: None String, pointing to avatar, that should be assigned to the contact. Note: Nimble uses lazy loading mechanism for avatars, and didn't perform any checks for URL validness during avatar_url setting. If you'll pass invalid parameter here no avatar will be displayed for contact. Example: { "fields": { "first name": [{ "value": "Jack", "modifier": "" }], "last name": [{ "value": "Daniels", "modifier": "" }], "phone": [{ "modifier": "work", "value": "123123123" }, { "modifier": "work", "value": "2222" }] }, "record_type": "person", "tags": "our customers,best" } Response: OK On success, server returns response with HTTP code 201 and newly created contact resource. { "avatar_url": null, "children": [], "company_last_contacted": { "in": null, "out": null }, "created": "2013-10-22T12:26:31+0300", "creator": "NimbleAPItest", "fields": { "first name": [ { "field_id": "4eabb0b64fb88d334c000ab6", "group": "Basic Info", "label": "first name", "modifier": "", "value": "Jack" } ], "last name": [ { "field_id": "4eabb0b64fb88d334c000ab8", "group": "Basic Info", "label": "last name", "modifier": "", "value": "Daniels" } 3.1. Basic Contacts API 27 Nimble API Documentation, Release 1.3.0 ], "phone": [ { "field_id": "4eabb0b74fb88d334c000ac5", "group": "Contact Info", "label": "phone", "modifier": "work", "value": "123123123" }, { "field_id": "4eabb0b74fb88d334c000ac5", "group": "Contact Info", "label": "phone", "modifier": "work", "value": "2222" } ], "source": [ { "field_id": "4eabb0b74fb88d334c000ac2", "group": "Basic Info", "label": "source", "modifier": "", "value": "m" } ] }, "id": "526644c7837d4e249372f091", "is_important": null, "last_contacted": { "message_id": null, "thread_id": null, "tstamp": null, "user_id": null }, "object_type": "contact", "owner_id": "4decc6b662100441e200000b", "record_type": "person", "reminder": null, "social_connections": { "facebook": {}, "linkedin": {}, "twitter": {} }, "tags": [ { "id": "52664434837d4e249372f081", "tag": "our customers" }, { "id": "52664434837d4e249372f083", "tag": "best" } ], "updated": "2013-10-22T12:26:31+0300", "updater": null } For more details see: Contact resources. 28 Chapter 3. Contacts API Nimble API Documentation, Release 1.3.0 Response: Errors Possible errors: Validation Error Quota Error 3.1.5 Update contact Request Example: PUT https://api.nimble.com/api/v1/contact/?replace=1 Parameters replace Optional url parameter that identifies whether to replace all other values for this kind of field or not. Can take 1 or 0 as true or false state, default 0. For example if contact has such set of fields: { "fields": { "first name": [{ "value": "Jack", "modifier": '' }], "email": [{ "value": "user@nimble.com", "modifier": "work" }, { "value": "jack@gmail.com", "modifier": "personal" }] } } then update it with: { "fields": { "email": [{ "value": "user@nimble.com", "modifier": "personal" }] } } will update field value with modifier "personal", but leave fields with other modifiers untouched. Result will be: { "fields": { "first name": [{ "value": "Jack", "modifier": '' }], "email": [{ "value": "user@nimble.com", "modifier": "work" }, { 3.1. Basic Contacts API 29 Nimble API Documentation, Release 1.3.0 "value": "user@nimble.com", "modifier": "personal" }] } } With replace parameter set to 1 if contacts that has: { "fields": { "first name": [{ "value": "Jack", "modifier": '' }], "email": [{ "value": "user@nimble.com", "modifier": "work" }, { "value": "jack@gmail.com", "modifier": "personal" }] } } and then UPDATE with: { "fields": { "email": [{ "value": "user@nimble.com", "modifier": "personal" }] } } will replace email fields with all modifiers. Result will be: { "fields": { "first name": [{ "value": "Jack", "modifier": '' }], "email": [{ "value": "user@nimble.com", "modifier": "personal" }] } } fields and avatar_url parameters are passed as JSON in request body. You should pass at least one of the parameters: fields or avatar_url (or both). fields Describes a dictionary organized in the same structure as a contact listing response. In this structure, each key is field name. Values are lists of dicts, having two fields: value - actual value to store in contact field, modifier - field modifier to use, if field can have one. Values provided in this list will replace actual field's values for contact. If you want to remove all values from field pass null as value. avatar_url optional, default: None String, pointing to avatar, that should be assigned to the contact. Note: Nimble uses lazy loading mechanism for avatars, and didn't perform any checks for URL validness during avatar_url setting. If you'll pass invalid parameter here no avatar will be displayed for contact. 30 Chapter 3. Contacts API Nimble API Documentation, Release 1.3.0 Example: { 'fields': { 'first name': [{ 'value': 'Jack', 'modifier': '' }], 'last name': [{ 'value': 'Daniels', 'modifier': '' }], 'phone': [{ 'value': null, 'modifier': 'work' }] } } Response: OK Updated contact is returned and encoded in the same way that is used in contacts listings. { 'updated': '2012-11-07T16:50:04+0200', 'created': '2012-11-07T16:50:04+0200', 'fields': { 'last name': [{ 'field_id': '5049f697a694620a07000045', 'modifier': '', 'group': 'Basic Info', 'value': 'Daniels', 'label': 'last name' }], 'source': [{ 'field_id': '5049f697a694620a0700004f', 'modifier': '', 'group': 'Basic Info', 'value': 'm', 'label': 'source' }], 'first name': [{ 'field_id': '5049f697a694620a07000043', 'modifier': '', 'group': 'Basic Info', 'value': 'Jack', 'label': 'first name' }] }, 'object_type': 'contact', 'id': '509a751c262b37af05000011', 'last_contacted': { 'last_contacted': null, 'thread_id': null, 'message_id': null }, 'record_type': 'person', 'creator': 'Nimble API test', 'children': [], 'tags': [], 'owner_id': '5049f696a694620a0700001c' } 3.1. Basic Contacts API 31 Nimble API Documentation, Release 1.3.0 For more details see: Contact resources. Response: Errors Possible errors: Validation Error Quota Error NotFound Error 3.1.6 Delete contact Simple contacts delete Performs deletion of contacts by their ids. Request Example: DELETE https://api.nimble.com/api/v1/contact/,,... Parameters None, all contact's IDs specifies in URL, separated by comma Response: OK Request returns HTTP code 200, body contains OK status and list of IDs of deleted contacts. Example: { "status": "ok", "data": { "ids": [ "5049f697a694620a0700007f", "5049f697a694620a07000082", "5049f697a694620a07000045" ] } } Response: Errors Possible errors: Validation Error Advanced contacts delete Allows bulk removal of contacts by keyword or advanced search query. 32 Chapter 3. Contacts API Nimble API Documentation, Release 1.3.0 Request Example: DELETE https://api.nimble.com/api/v1/contacts/list Parameters Parameters are similar to contact's listing ones. keyword Delete all contacts where fields are containing value from this parameter record_type default: all Delete all contacts with provided record_type (person or company). This pa- rameter could be combined with keyword parameter in order to delete contacts of specific record_type query Json-encoded advanced search query to find contact for deletion. For more details on query syntax, see Advanced search query syntax. Note: If query parameter presented in request record_type parameter will be ignored. limit default: all Number of contacts to delete by specified criteria (query, keyword, record_type). Warning: query and keyword parameters are mutually exclusive. If you'll try to specify both validation error will be returned. Response: OK Example request: DELETE https://api.nimble.com/api/v1/contacts/list?keyword=DoeAPItest Response will be: { "status": "ok", "data": { "ids": [ "50941746837d4e3df20001d1", "50941746837d4e3df1000144" ] } } Response: Errors Possible errors: Validation Error NotFound Error 3.2 Contact Notes API Contents: 3.2. Contact Notes API 33 Nimble API Documentation, Release 1.3.0 3.2.1 Show single note Request Base endpoint: GET https://api.nimble.com/api/v1/contacts/notes/ Parameters note_id Single note id to show GET https://api.nimble.com/api/v1/contacts/notes/508a4750084abd28bc00016f Response: OK Response to this request is dictionary with JSON serialised note body. Contact note { "created": "2012-11-29T10:16:46+0000", "contacts": [{ "id": "508a4750084abd28bc00016f", "name": "Jack Daniels" }], "note_preview": "note 1", "author_name": "Nimble API test", "note": "%3Cfont%20face%3D%22Arial%2C%20Tahoma%2C%20Verdana%2C%20Helvetica%2C%20sans-serif%22% "id": "50b7360e837d4e4404000013", "owner_id": "5049f696a694620a0700001c" } Keys meaning: id Id of the note. Can be used to identify it in update and delete operations. created Date and time when the note was created encoded in ISO 8601 contacts List of id-name pairs for each of contacts associated with the note note_preview Note content with all formatting removed note Note content with all formatting mark up in place author_name Readable name of company user who created this note owner_id Id of company user who created this note Response example { "created": "2012-11-29T10:16:46+0000", "contacts": [{ "id": "508a4750084abd28bc00016f", "name": "Jack Daniels" }], "note_preview": "note 1", 34 Chapter 3. Contacts API Nimble API Documentation, Release 1.3.0 "author_name": "Nimble API test", "note": "%3Cfont%20face%3D%22Arial%2C%20Tahoma%2C%20Verdana%2C%20Helvetica%2C%20sans-serif%22% "id": "50b7360e837d4e4404000013", "owner_id": "5049f696a694620a0700001c" } Response: Errors Possible errors: Validation Error NotFound Error 3.2.2 Get contact notes list Request Base endpoint: GET https://api.nimble.com/api/v1/contact//notes Example: GET https://api.nimble.com/api/v1/contact/5049fba29b85f669e40004fb/notes Parameters All parameters are optional. Unrecognized parameters are ignored. Unrecognized values will return an error. per_page default: 5 Specifies the number of items to return per page of results. page default: 1 Specifies which page to display. Numeration starts from 1. Response: OK Response to this request is dictionary formed out of two keys: meta and resources. Metadata coming under meta key is common structure used among different listing in Nimble. Value under resources key is list of notes entries. Pagination metadata 'meta': { 'per_page': 30, 'total': 45, 'pages': 2, 'page': 1 } Keys meaning: per_page Number of contacts returned per page total Total number of contacts pages Total pages count 3.2. Contact Notes API 35 Nimble API Documentation, Release 1.3.0 page Current page number Contact note { "created": "2012-11-29T10:16:46+0000", "contacts": [{ "id": "508a4750084abd28bc00016f", "name": "Jack Daniels" }], "note_preview": "note 1", "author_name": "Nimble API test", "note": "%3Cfont%20face%3D%22Arial%2C%20Tahoma%2C%20Verdana%2C%20Helvetica%2C%20sans-serif%22% "id": "50b7360e837d4e4404000013", "owner_id": "5049f696a694620a0700001c" } Keys meaning: id Id of the note. Can be used to identify it in update and delete operations. created Date and time when the note was created encoded in ISO 8601 contacts List of id-name pairs for each of contacts associated with the note note_preview Note content with all formatting removed note Note content with all formatting mark up in place author_name Readable name of company user who created this note owner_id Id of company user who created this note Response example { "meta": { "per_page": 5, "total": 1, "pages": 1, "page": 1 }, "resources": [{ "created": "2012-11-29T10:16:46+0000", "contacts": [{ "id": "508a4750084abd28bc00016f", "name": "Jack Daniels" }], "note_preview": "note 1", "author_name": "Nimble API test", "note": "%3Cfont%20face%3D%22Arial%2C%20Tahoma%2C%20Verdana%2C%20Helvetica%2C%20sans-serif "id": "50b7360e837d4e4404000013", "owner_id": "5049f696a694620a0700001c" }] } Response: Errors Possible errors: Validation Error 36 Chapter 3. Contacts API Nimble API Documentation, Release 1.3.0 3.2.3 Create contact note Request Base endpoint: POST https://api.nimble.com/api/v1/contacts/notes Parameters All parameters are passed as JSON in request body. All parameters are mandatory. contact_ids List of contacts' IDs in BSON format to which the note will be attached. Contacts count should be between 1 and 10. note Sting, containing note itself. note_preview Short version of note, that will be used for preview purposes. Example: { "contact_ids": ["50c07a69e5ef834edb000080", "50c07a53084abd5f61000aac"], "note": "Just contact note, with some longer text", "note_preview": "Just contact note" } Response: OK Response to this request is dictionary with JSON serialised note body. Contact note { "created": "2012-11-29T10:16:46+0000", "contacts": [{ "id": "508a4750084abd28bc00016f", "name": "Jack Daniels" }], "note_preview": "note 1", "author_name": "Nimble API test", "note": "%3Cfont%20face%3D%22Arial%2C%20Tahoma%2C%20Verdana%2C%20Helvetica%2C%20sans-serif%22% "id": "50b7360e837d4e4404000013", "owner_id": "5049f696a694620a0700001c" } Keys meaning: id Id of the note. Can be used to identify it in update and delete operations. created Date and time when the note was created encoded in ISO 8601 contacts List of id-name pairs for each of contacts associated with the note note_preview Note content with all formatting removed note Note content with all formatting mark up in place 3.2. Contact Notes API 37 Nimble API Documentation, Release 1.3.0 author_name Readable name of company user who created this note owner_id Id of company user who created this note Response example { "created": "2012-11-29T10:16:46+0000", "contacts": [ { "id": "508a4750084abd28bc00016f", "name": "Jack Daniels" } ], "note_preview": "note 1", "author_name": "Nimble API test", "note": "%3Cfont%20face%3D%22Arial%2C%20Tahoma%2C%20Verdana%2C%20Helvetica%2C%20sans-serif%22% "id": "50b7360e837d4e4404000013", "owner_id": "5049f696a694620a0700001c" } Response: Errors Possible errors: Validation Error 3.2.4 Update contact note Request Base endpoint: PUT https://api.nimble.com/api/v1/contacts/notes/ Parameters All parameters are passed as JSON in request body. All parameters are mandatory. contact_ids List of contacts' IDs in BSON format to which the note will be attached. Contacts count should be between 1 and 10. note Sting, containing note itself. note_preview Short version of note, that will be used for preview purposes. Example: { "contact_ids": ["50c07a69e5ef834edb000080", "50c07a53084abd5f61000aac"], "note": "Just contact note, with some longer text", "note_preview": "Just contact note" } 38 Chapter 3. Contacts API Nimble API Documentation, Release 1.3.0 Response: OK Response to this request is dictionary with JSON serialised note body. Contact note { "created": "2012-11-29T10:16:46+0000", "contacts": [{ "id": "508a4750084abd28bc00016f", "name": "Jack Daniels" }], "note_preview": "note 1", "author_name": "Nimble API test", "note": "%3Cfont%20face%3D%22Arial%2C%20Tahoma%2C%20Verdana%2C%20Helvetica%2C%20sans-serif%22% "id": "50b7360e837d4e4404000013", "owner_id": "5049f696a694620a0700001c" } Keys meaning: id Id of the note. Can be used to identify it in update and delete operations. created Date and time when the note was created encoded in ISO 8601 contacts List of id-name pairs for each of contacts associated with the note note_preview Note content with all formatting removed note Note content

Nimble: Your Smart CRM for Office 365 and G Suite

Business planning ideas from around the internet.

Publishing documents on edocr is a proven way to start demand generation for your products and services. Thousands of professionals and businesses publish marketing (brochures, data sheets, press releases, white papers and case studies), sales (slides, price lists and pro-forma agreements), operations (specifications, operating manuals, installation guides), customer service (user manuals) and financial (annual reports and financial statements) documents making it easier for prospects and customers to find content, helping them to make informed decisions. #SEO #leadgen #content #analytics

About edocr

I am an accomplished content marketing professional helping you to build your brand and business. In my current role, I fulfill a multi-faceted solution marketplace including: publishing and sharing your content, embedding a document viewer on your website, improving your content’s search engine optimization, generating leads with gated content and earning money by selling your documents. I gobble up documents, storing them for safekeeping and releasing the text for excellent search engine optimization, lead generation and earned income. 

Publishing documents on edocr.com is a proven way to start demand generation for your products and services. Thousands of professionals and businesses publish marketing, sales, operations, customer service and financial documents making it easier for prospects and customers to find content, helping them to make informed decisions.

Get publishing now!

×

Modal Header

Modal body