Nimble API Documentation

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

Nimble API Documentation Release 1.3.0 Nimble Feb 03, 2020 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 Get user information 13 3.1 Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 3.2 Response: OK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 4 Company API 15 4.1 Users API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 5 Contacts API 17 5.1 Basic Contacts API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 5.2 Contact Notes API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 5.3 Contacts Metadata API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 5.4 Contact Tags API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 6 Full description of Nimble default contact fields 55 6.1 Field types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 6.2 Nimble default fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 6.3 Nimble default field groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 6.4 Nimble fields presentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 7 Activities API 63 7.1 Tasks API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 8 Tutorial: Obtain Nimble API Key 65 8.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 8.2 Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 8.3 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 8.4 Authorization process overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 8.5 Requesting Authorization Grant Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 8.6 Requesting Access Token . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 8.7 API requests using Access Token . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 8.8 Refresh token after expiration without user input . . . . . . . . . . . . . . . . . . . . . . . . . . 69 8.9 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 8.10 Troubleshooting & Feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 9 Tutorial: Making authenticated requests 71 i 9.1 Authenticating your request with URL parameter . . . . . . . . . . . . . . . . . . . . . . . . . . 71 9.2 Authenticating your request with HTTP header . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 10 Examples and libraries 73 10.1 Javascript . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 10.2 NodeJS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 10.3 Python . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 10.4 Ruby . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 11 Nimble API changes history 75 12 Getting help 77 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", (continues on next page) 5 Nimble API Documentation, Release 1.3.0 (continued from previous page) "fields": { "parent company": [ { "modifier": "", "extra_value": "5c459c56ceee1868ee3ab468", "value": "Nimble", "label": "parent company" } ], "description": [ { "value": "description", "label": "description", "modifier": "other" }, { "value": "description", "label": "description", "modifier": "linkedin" } ], "last name": [ { "modifier": "", "value": "Akopyan", "label": "last name" } ], "phone": [ { "modifier": "mobile", "value": "+7 (917) 202-456-1111", "label": "phone" }, { "modifier": "home", "value": "+7 244 231 84 22", "label": "phone" } ], "URL": [ { "modifier": "other", "value": "https://nimble.com", "label": "URL" }, { "modifier": "other", "value": "https://app.nimble.com", "label": "URL" } ], "source": [ { "modifier": "", "value": "csv", "label": "source" } ], "address": [ { (continues on next page) 6 Chapter 2. Nimble API Responses Nimble API Documentation, Release 1.3.0 (continued from previous page) "modifier": "other", "value": "{'city': 'Dushanbe', 'street': 'First str. 15', 'zip →˓': '54055', 'country': 'Farganistan'}", "label": "address" } ], "email": [ { "modifier": "other", "value": "fake_person@nimble.com", "label": "email" } ], "first name": [ { "modifier": "", "value": "Amayak", "label": "first name" } ] }, "object_type": "contact", "id": "5049fb849b85f669e40000dc", "last_contacted": { "user_id": "5c459c52ceee1868ee3ab41f", "deletion_tstamp": null, "type": "LCType", "object_id": "ed5afbee-37f5-db6b-7f71-c7d6b8750bbb", "tstamp": "2019-01-22T21:57:30+0000" }, "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. • user_id — unique id of owner in BSON format • object_id — id of object of corresponding type in BSON format 2.1. Contacts details 7 Nimble API Documentation, Release 1.3.0 • type — last contacted provider’s type • tstamp — timestamp of last outbound message • deletion_tstamp — timestamp of object deleting 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 • 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 } ], (continues on next page) 8 Chapter 2. Nimble API Responses Nimble API Documentation, Release 1.3.0 (continued from previous page) "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" } ], "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: 2.1. Contacts details 9 Nimble API Documentation, Release 1.3.0 • 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.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 10 Chapter 2. Nimble API Responses Nimble API Documentation, Release 1.3.0 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 empty", "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. 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 subscription.\nDon't worry, you can upgrade your account and add more →˓contacts right now.", "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 Get user information For many use-cases it is useful to obtain basic user information. For that purpose we provide the GET /api/v1/myself endpoint. 3.1 Request Example: GET https://api.nimble.com/api/v1/myself 3.2 Response: OK On success, server returns response with HTTP code 200 { "user_id": "4f2acc3142a053dda595f00b", "company_id": "4c2118ad54397f271b000000", "email": "some@user.com", "name": "John Doe", "company_size": 3 } 13 Nimble API Documentation, Release 1.3.0 14 Chapter 3. Get user information CHAPTER 4 Company API Contents: 4.1 Users API Contents: 4.1.1 Get company users short information We provide an opportunity to get shortened information about the users of the company. Request Example: GET https://api.nimble.com/api/v1/company/users Response: OK On success, server returns response with HTTP code 200 { "users": [ { "avatar_url": "https://app.nimble.com/api/v1/company/user/ →˓5ce69c1fceee1836160c2887/avatar?version=1", "is_active": true, "name": "Amayak Akopyan", "email": "fake_person@nimble.com" } ] } 15 Nimble API Documentation, Release 1.3.0 16 Chapter 4. Company API CHAPTER 5 Contacts API Contents: 5.1 Basic Contacts API Contents: 5.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 17 Nimble API Documentation, Release 1.3.0 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. 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 1: Special sortings Name Meaning Note recently viewed sorts by user’s recently viewed contacts When sorting by recently viewed, these parameters are disabled: keyword, record type, page and per_page. Nim- ble 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 con- tains type of occurrence. users last contacted sorts by recently contacted by user con- tacts 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: 18 Chapter 5. Contacts API Nimble API Documentation, Release 1.3.0 { "meta": { "page": 1, "pages": 1, "per_page": 30, "total": 2 }, "resources": [ "4f69fb852ab3740c5e000004", "5e69fb852ab3f40d5e050017" ] } Response: Errors Possible errors: • Validation Error 5.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) “čar” is the same as “car” 3) “ČAR” 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. 5.1. Basic Contacts API 19 Nimble API Documentation, Release 1.3.0 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 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 ] }] } 20 Chapter 5. Contacts API Nimble API Documentation, Release 1.3.0 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. Note: In the table below (old) means only another(previously used) behaviour of search operator, API param- eters is still same. 5.1. Basic Contacts API 21 Nimble API Documentation, Release 1.3.0 Table 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 result 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 descend- ing 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 documents 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 expected to be in UTC in rfc3339 format. {"company last contacted": {"range": {"start_date": "2013-03-19", "end_date": "2013-03-19"}}} {"company last contacted": {"range": {"start_datetime": "2013-04-23 00:00:10", "end_datetime": "2013-04-26T00:00:10"}}} gt Field value with specified name have lower value than provided in the search criteria {"rating": {"gt": "3"}} lt Field value with specified name have greater value than provided in the search criteria {"rating": {"gt": "3"}} gte Field value with specified name have lower or equal value than provided in the search crite- ria {"rating": {"gte": "3"}} lte Field value with specified name have greater or equal value than provided in the search cri- teria {"rating": {"lte": "3"}} 22 Chapter 5. Contacts API Nimble API Documentation, Release 1.3.0 Available search fields Table 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: 5.1. Basic Contacts API 23 Nimble API Documentation, Release 1.3.0 {"city": {"is_empty": False}} Search for contacts, created in given date range: { "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|city|state|zip|country|lead type|company →˓name|custom_fields|name|first name|lead source|created|address|tag|or|and|record →˓type)$": { "required": true, "type": "object" } }, (continues on next page) 24 Chapter 5. Contacts API Nimble API Documentation, Release 1.3.0 (continued from previous page) "type": "object", "description": "top level (all fields) validation rule" } Joins validation schema { "additionalProperties": false, "patternProperties": { "^(or|and)$": { "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|country|company name|title)$": { "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/company name/title validation rule" } 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 5.1. Basic Contacts API 25 Nimble API Documentation, Release 1.3.0 { "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" } } } 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": { (continues on next page) 26 Chapter 5. Contacts API Nimble API Documentation, Release 1.3.0 (continued from previous page) "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"] } } } } } ] } } } 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 5.1. Basic Contacts API 27 Nimble API Documentation, Release 1.3.0 { "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"] } } } } } } } 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"] } } } } } 28 Chapter 5. Contacts API Nimble API Documentation, Release 1.3.0 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: https://api.nimble.com/api/v1/contacts?query=%7B%22first%20name%22%3A%20%7B%22is%22 →˓%3A%20%22Anton%22%7D%7D&tags=0&per_page=5&fields=first%20name 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%22is%22%3A%20%22Ferrara%22%7D%7D%2C%20%7B%22first%20name%22%3A%20%7B →˓%22is%22%3A%20%22Jon%22%7D%7D%5D%7D&tags=0&per_page=5&fields=last%20name,first →˓%20name 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. 5.1. Basic Contacts API 29 Nimble API Documentation, Release 1.3.0 Response: Errors Possible errors: • Validation Error 5.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,5049fba29b85f669e40004fb 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 30 Chapter 5. Contacts API Nimble API Documentation, Release 1.3.0 5.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. 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" } ] (continues on next page) 5.1. Basic Contacts API 31 Nimble API Documentation, Release 1.3.0 (continued from previous page) }, "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": [ { "modifier": "", "value": "Jack", "label": "first name" } ], "last name": [ { "modifier": "", "value": "Daniels", "label": "last name" } ], "phone": [ { "modifier": "work", "value": "123123123", "label": "phone" }, { "modifier": "work", "value": "2222", "label": "phone" } ], "source": [ { "modifier": "", "value": "m", "label": "source" } ] }, "id": "526644c7837d4e249372f091", "is_important": null, "last_contacted": { "user_id": null, "deletion_tstamp": null, "type": null, "object_id": null, (continues on next page) 32 Chapter 5. Contacts API Nimble API Documentation, Release 1.3.0 (continued from previous page) "tstamp": null }, "object_type": "contact", "owner_id": "4decc6b662100441e200000b", "record_type": "person", "reminder": null, "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. Response: Errors Possible errors: • Validation Error • Quota Error 5.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" }, { (continues on next page) 5.1. Basic Contacts API 33 Nimble API Documentation, Release 1.3.0 (continued from previous page) "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" }, { "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", (continues on next page) 34 Chapter 5. Contacts API Nimble API Documentation, Release 1.3.0 (continued from previous page) "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. Example: { "fields": { "first name": [ { "value": "Jack", "modifier": "" (continues on next page) 5.1. Basic Contacts API 35 Nimble API Documentation, Release 1.3.0 (continued from previous page) } ], "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": [ { "modifier": "", "value": "Daniels", "label": "last name" } ], "source": [ { "modifier": "", "value": "m", "label": "source" } ], "first name": [ { "modifier": "", "value": "Jack", "label": "first name" } ] }, "object_type": "contact", "id": "509a751c262b37af05000011", "last_contacted": { "user_id": "5c459c52ceee1868ee3ab41f", "deletion_tstamp": null, "type": "LCType", "object_id": "ed5afbee-37f5-db6b-7f71-c7d6b8750bbb", "tstamp": "2019-01-22T21:57:30+0000" }, "record_type": "person", "creator": "Nimble API test", "children": [], "tags": [], (continues on next page) 36 Chapter 5. Contacts API Nimble API Documentation, Release 1.3.0 (continued from previous page) "owner_id": "5049f696a694620a0700001c" } For more details see: Contact resources. Response: Errors Possible errors: • Validation Error • Quota Error • NotFound Error 5.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 5.1. Basic Contacts API 37 Nimble API Documentation, Release 1.3.0 Advanced contacts delete Allows bulk removal of contacts by keyword or advanced search query. 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 38 Chapter 5. Contacts API Nimble API Documentation, Release 1.3.0 5.2 Contact Notes API Contents: 5.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": [ { "avatar_url": "https://app.nimble.com/api/contacts/avatars/ →˓5049fb849b85f669e40000dc", "subtitle": "CEO", "name": "Jack Daniels", "contact_type": "person", "phones": [ { "value": "123456789", "label": "work" } ], "title": "CEO", "id": "5c459c56ceee1868ee3ab46f", "email": [ "care@nimble.com" ] } ], "note_preview": "note 1", "author_name": "Nimble API test", "note": "%3Cfont%20face%3D%22Arial%2C%20Tahoma%2C%20Verdana%2C%20Helvetica%2C →˓%20sans-serif%22%3Enote%201%3C%2Ffont%3E", "id": "50b7360e837d4e4404000013", "owner_id": "5049f696a694620a0700001c" } 5.2. Contact Notes API 39 Nimble API Documentation, Release 1.3.0 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 objects that are a shortened contact data view 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": [ { "avatar_url": "https://app.nimble.com/api/contacts/avatars/ →˓5049fb849b85f669e40000dc", "subtitle": "CEO", "name": "Jack Daniels", "contact_type": "person", "phones": [ { "value": "123456789", "label": "work" } ], "title": "CEO", "id": "5c459c56ceee1868ee3ab46f", "email": [ "care@nimble.com" ] } ], "note_preview": "note 1", "author_name": "Nimble API test", "note": "%3Cfont%20face%3D%22Arial%2C%20Tahoma%2C%20Verdana%2C%20Helvetica%2C →˓%20sans-serif%22%3Enote%201%3C%2Ffont%3E", "id": "50b7360e837d4e4404000013", "owner_id": "5049f696a694620a0700001c" } Response: Errors Possible errors: • Validation Error • NotFound Error 5.2.2 Get contact notes list Request Base endpoint: 40 Chapter 5. Contacts API Nimble API Documentation, Release 1.3.0 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 page Current page number Contact note { "created": "2012-11-29T10:16:46+0000", "contacts": [ { "avatar_url": "https://app.nimble.com/api/contacts/avatars/ →˓5049fb849b85f669e40000dc", "subtitle": "CEO", "name": "Jack Daniels", "contact_type": "person", "phones": [ { "value": "123456789", "label": "work" } (continues on next page) 5.2. Contact Notes API 41 Nimble API Documentation, Release 1.3.0 (continued from previous page) ], "title": "CEO", "id": "5c459c56ceee1868ee3ab46f", "email": [ "care@nimble.com" ] } ], "note_preview": "note 1", "author_name": "Nimble API test", "note": "%3Cfont%20face%3D%22Arial%2C%20Tahoma%2C%20Verdana%2C%20Helvetica%2C →˓%20sans-serif%22%3Enote%201%3C%2Ffont%3E", "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 objects that are a shortened contact data view 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": [ { "avatar_url": "https://app.nimble.com/api/contacts/avatars/ →˓5049fb849b85f669e40000dc", "subtitle": "CEO", "name": "Jack Daniels", "contact_type": "person", "phones": [ { "value": "123456789", "label": "work" } ], "title": "CEO", "id": "5c459c56ceee1868ee3ab46f", "email": [ "care@nimble.com" ] } (continues on next page) 42 Chapter 5. Contacts API Nimble API Documentation, Release 1.3.0 (continued from previous page) ], "note_preview": "note 1", "author_name": "Nimble API test", "note": "%3Cfont%20face%3D%22Arial%2C%20Tahoma%2C%20Verdana%2C%20Helvetica →˓%2

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