Download OpenAPI specification:Download
Nimble is a relationship-focused CRM for your entire team. With customizable contact records and easy-to-use Kanban-style workflows, managing client information has never been simpler. Nimble effortlessly integrates with both Microsoft 365 and Google Workspace, gathering contacts and leads from all your platforms, while our automation tools handle the busy work. Focus on what matters most – growing your business and nurturing relationships, as Nimble streamlines your workflow for maximum productivity.
The document below offers an overview of currently available APIs & how to utilize them. If you're missing some APIs for an integration you want to build, please contact us at [email protected].
Currently available APIs:
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 2-way data integrations with other services. We aim 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.
This document will describe authorization flow that return the authorization token that allow to make requests to Nimble API and access resources to which access has been granted for user. For For authorization Nimble use OAuth 2.0 protocol with bearer tokens. All technical details can be read in RFC6749 and RFC6750, but you don't need to read them (unless you want to know more details on OAuth 2.0) every detail that need to obtain access token and use this token for requesting resource on behalf of user will be described in this document.
User - Person who has an account inside Nimble and owner of resources to which API provide access
Client - Service that request a token and want to make requests to the Nimble API on behalf of User
Authorization server - Server that allow User to grant access for Client to use his resources
Resource server - Server that returns User's resources to Client if it was granted for access by User
Bearer token - Token that Client received after User has granted access. Possession of this token allows client to make requests to Resource server in order to receive Client's resources.
In order to create a Client for Nimble API you need to have to register your application in our DB and get Client Secret and Client Id. Its can be done on the page with this link: https://support.nimble.com/third-party-integrations/nimble-api-access/nimble-api-access. You probably have done this already.
For giving you a good overview of process we will use scheme and give a brief explanation to the each step on scheme. Steps are shown by the arrows and has a letters assigned to each step on scheme.
Let's go over a scheme step by step.
application/x-www-form-urlencoded
request to the
Authorization Server where in body you put code retrieved on
previous step, your Client Secret, Client Id and Grant Type you want
to receive. It is always authorization code. For
details see Request access tokenYou should use this request on step B of Authorization Process. You need to open a page for user with this endpoint and provide a Redirect URI on which your handler will be able to catch the code from Authorization Server that will be returned when User successfully grant you a permission to use Nimble API.
Endpoint:
GET https://app.nimble.com/oauth/authorize
Params:
client_id - required - Your Client Key from Application Page.
redirect_uri- required - URI where you have a handler who will catch a code and finish the Process, see note below.
response_type - required - must be set to code
. We don't support Implicit
Flow, so code
is the only available option now.
scope - required - there are 3 scopes in Nimble: Basic (User & Company Info), Contacts and Deals
Please note, that main value for redirect URL is specified in
application settings on developer portal. redirect_uri
parameter
in URL could be used only to overwrite path part in redirect URL.
So, redirect_uri
should have exactly same URI, as specified in
application settings.
Example request:
GET https://app.nimble.com/oauth/authorize?client_id=5f96b5e9adaxzca93x1213123132&redirect_uri=https%3A%2F%2Fyourportal.com%2Fauth%2Fpassed&response_type=code
Successful response:
First, user will be redirected to the page on Authorization Server with hostname
https://app.nimble.com/oauth/authorize
As soon as he provided his credentials, you will receive a request like listed below on your
Redirect URI
:https://yourportal.com/auth/passed?code=LTM4M
Error response:
If the request is missing or has incorrect parameters, the user-agent will be redirected back to the redirect URI provided. The redirection will contain parameters specifying the error.
Example Invalid Authorization Request Redirect:
http://www.myapp.com/oauth?error=invalid_request&error_description=Invalid%20URL
After selecting Login, the user will be validated. If user validation is successful, a consent page is displayed. If user validation is unsuccessful, the user-agent will be redirected to the redirect URI provided in the initial request. This redirection will include additional parameters specifying the error.
Example Unsuccessful Validation Redirect:
http://www.myapp.com/oauth?error=access_denied&error_descripton=Validation%20errors
If user click Deny on the grant permission page then another error will be sent.
Example Deny Consent Redirect:
http://www.myapp.com/oauth?error=access_denied&error_description=User%20denied%20access
To get OAuth app credentials, please email api-support@nimble.com and include the following:
As soon as User complete step C your handler will catch step D. You need to listen for redirect on your Redirect URI. Code returned to you isn't access token yet! You still need to obtain the authorization token. Note, that this code is valid for a short period time and if you not intiate request to access token as soon as you receive a code then received code can become invalid and User will need to reinitiate a process once again. So, on step E you need to receive access to token for which user granted you.
The Client should use the authorization code obtained to request an
access token. When requesting an access token, you SHOULD specify
required data as form parameters. Client application secret is needed
for client authentication. When specifying client_id and client_secret
as form parameters, the Content-Type
header MUST be set to
application/x-www-form-urlencoded
. Request should be done via HTTPS
only.
Endpoint:
POST https://app.nimble.com/api/oauth/token
Parameters:
authorization_code
. You need to receive an Access token.redirect_uri
, provided during Requesting grant codeHeaders:
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
- required - you need to specify this header alwaysExample Request:
POST /api/oauth/token HTTP/1.1
Host: app.nimble.com
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
Body : client_id=5f96b5e9a6b7478e15ee574a426aa063&redirect_uri=http%3A%2F%2Flocalhost%3A3000%2Fauth&code=LTM4M&grant_type=authorization_code&client_secret=89bb4ffb4f264bff
Successfull Response JSON:
{
"access_token": "bf086611-9e97-4d11-9cd7-3c86dec0bbd4",
"token_type": "bearer",
"expires_in": 599,
"refresh_token": "515ac59b-6518-49a2-81d6-54f91ee74c4a",
"scope": "basic"
}
Now when we have Access Token Received you need to store it and use for any requests for Nimble Data on behalf of user. This process described in Making requests tutorial
The application uses the refresh token to extend the validity of the
access token provided with the refresh token. When refreshing an access
token, you should specify required data as a form parameters. Client
application secret is needed for client authentication. Content-Type
header must be set to application/x-www-form-urlencoded
.
Parameters:
refresh_token
redirect_uri
, provided during Request grant codeExample Request:
POST /api/oauth/token HTTP/1.1
Host: https://app.nimble.com/
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
client_id=3e8471e7516a0c85ef35ab1d23f1bdf1&client_secret=737d10deba3fd124&grant_type=refresh_token&refresh_token=5f752714eddb07a3e41c2a3311f514e1&redirect_uri=http%3A%2F%2Flocalhost%3A3000%2Fauth
Example Response:
{
"access_token": "1d7bc7328b402f4826e17607e364bc6a",
"expires_in": 559,
"refresh_token": "f35c2165112fda74f79b408cc253485fcdfd888a"
}
For your convinience we created some examples:
Python authorization example. Actual code implementation on Python and Tornado
Ruby authorization example. Implementation of authorization process in Ruby
If you have any problems or want to submit feedback feel free to go to our support forum or email us at api-support@nimble.com
When you've received token, using the process described in Obtaining API key guide, you are ready to call Nimble API. You can use one of two ways, described below. They both are equal.
In order to use this token code you just add it into URL as request
parameter with name access_token
.
Endpoint:
Any of available endpoint of Nimble API
Params:
No matter what request POST
, GET
or any other HTTP method, just add
an access_token
as parameter to URL.
Example Request:
POST https://api.nimble.com/api/v1/contacts?access_token=e0f7b053200672c2ff6ede59c8e2bfc7
Successful Response:
All API responses described on their corresponding pages.
You can also pass your token in HTTP header Authorization
in format:
Bearer <your token>
.
Example request:
PUT /api/v1/contact/4f60a873fcf7b752ed006b7a HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate, compress
Authorization: Bearer c0b5f46631455b543c309b8cb18b8dae
Content-Type: application/json; charset=utf-8
{
"fields": {
"first name": [
{
"modifier": "",
"value": "1name"
}
]
}
}
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
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.
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
}
Sent if unrecoverable Nimble server occurs. Returns with HTTP code 500 and code field equal to 107.
{
"message": "Internal error handling request",
"code": 107
}
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]{.title-ref} and [object_id]{.title-ref} fields:
{
"object_type": "contact field",
"object_id": "111111111111111111111111"
}
Typical response to this request is a dictionary with 2 keys (unless otherwise specified by the specific API): meta and 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": [
{
"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": [
{
"modifier": "other",
"value": "{'city': 'Dushanbe', 'street': 'First str. 15', 'zip': '54055', 'country': 'Farganistan'}",
"label": "address"
}
],
"email": [
{
"modifier": "other",
"value": "[email protected]",
"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<message>",
"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
- *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
Contact list request is similar to
contact details response. It has the
same key with resources,
described here. Difference is in meta
key value. For contact listing it
returns pagination details.
Deletes a list of contacts by specified advanced search query. Requires bulk delete permission for authenticated user.
keyword | Array of strings Delete all contacts where fields are containing value from this parameter |
query | string Json-encoded advanced search query to find contact for deletion. For more details on query syntax, see Advanced search query syntax. If query parameter presented in request — record_type parameter will be ignored. |
record_type | string Default: "all" Enum: "person" "company" "all" Delete all contacts with provided record_type. This parameter could be combined with keyword parameter in order to delete contacts of specific record_type |
preflight_checks | boolean Default: false check query's contacts are editable |
{- "data": {
- "ids": [
- "string"
], - "push_data": {
- "action": "single_message_sent",
- "created": "2019-08-24T14:15:22Z",
- "id": "string",
- "is_new": true,
- "object": { },
- "object_type": "notification"
}
}, - "status": "string"
}
Returns list of contacts filtered by specified parameters. Allows filters by advanced search query, tags, keyword. You can receive all fields or specify a list of fields to return.
keyword | string Specifies a set of simple search criteria for the query. This simple search is performed on any (indexed in our search engine) field of contact |
fields | string Specifies a comma separated list of fields to return. If this parameter is excluded, all fields will be returned |
tags | boolean Default: true Specifies whether tags should be included in the results. |
last_contacted (DEPRECATED; use contexts) | boolean Default: true True if return last contacted information, False otherwise |
sort | Array of strings 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. |
query | Array of strings Specifies query for contacts advanced search. Please note, that this parameter not compatible with parameters record_type and keyword |
record_type | string Default: "all" Enum: "person" "company" "all" |
page | integer Default: 1 Specifies which page to display |
per_page | integer Default: 30 Specifies the number of items to return per page of results. |
files_data (DEPRECATED; use contexts) | boolean Deprecated Default: false if response should include the contacts files in this listing |
contexts | any (Contacts.ContactViewContextKinds) Enum: "last_contacted_data" "employers_data" "leads_data" "sequences_data" "contact_files" comma-separated additional contexts that should be returned with in this contact |
{- "meta": {
- "page": 0,
- "pages": 0,
- "per_page": 0,
- "total": 0
}, - "resources": [
- {
- "avatar_url": "string",
- "children": [
- "string"
], - "employers_info": [
- {
- "company_name": "string",
- "contact_id": "string"
}
], - "company_last_contacted": {
- "in": {
- "deletion_tstamp": { },
- "object_id": { },
- "tstamp": { },
- "type": { },
- "user_id": { },
- "direction": "inbound"
}, - "out": {
- "deletion_tstamp": { },
- "object_id": { },
- "tstamp": { },
- "type": { },
- "user_id": { },
- "direction": "inbound"
}
}, - "lc": {
- "company_lc": {
- "in": {
- "deletion_tstamp": { },
- "object_id": { },
- "tstamp": { },
- "type": { },
- "user_id": { },
- "direction": "inbound"
}, - "out": {
- "deletion_tstamp": { },
- "object_id": { },
- "tstamp": { },
- "type": { },
- "user_id": { },
- "direction": "inbound"
}, - "last": {
- "deletion_tstamp": { },
- "object_id": { },
- "tstamp": { },
- "type": { },
- "user_id": { },
- "direction": "inbound"
}
}, - "user_lc": {
- "in": {
- "deletion_tstamp": { },
- "object_id": { },
- "tstamp": { },
- "type": { },
- "user_id": { },
- "direction": "inbound"
}, - "out": {
- "deletion_tstamp": { },
- "object_id": { },
- "tstamp": { },
- "type": { },
- "user_id": { },
- "direction": "inbound"
}, - "last": {
- "deletion_tstamp": { },
- "object_id": { },
- "tstamp": { },
- "type": { },
- "user_id": { },
- "direction": "inbound"
}
}, - "last_user": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}
}, - "created": "string",
- "creator": "string",
- "fields": {
- "property1": [
- {
- "field_id": "string",
- "modifier": "string",
- "value": "string"
}
], - "property2": [
- {
- "field_id": "string",
- "modifier": "string",
- "value": "string"
}
]
}, - "id": "string",
- "is_important": { },
- "last_contacted": {
- "deletion_tstamp": { },
- "object_id": { },
- "tstamp": { },
- "type": { },
- "user_id": { },
- "direction": "inbound"
}, - "object_type": "contact",
- "last_contacted_user": "string",
- "owner_id": "string",
- "privacy": {
- "edit": {
- "group_ids": [
- "string"
], - "user_ids": [
- "string"
]
}, - "read": {
- "group_ids": [
- "string"
], - "user_ids": [
- "string"
]
}
}, - "record_type": "person",
- "reminder": {
- "active": true,
- "contact_id": "string",
- "days_till_triggered": 0,
- "period": 0,
- "triggered": true
}, - "tags": [
- "string"
], - "updated": "string",
- "updater": "string",
- "stages_info": [
- {
- "pipeline_id": "string",
- "pipeline_name": "string",
- "stage_name": "string",
- "entered_data": "string",
- "is_final": true,
- "days_limit": 0
}
], - "notice": {
- "created": "string",
- "updated": "string",
- "creator": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "updated_by": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "text": "string",
- "color": "string"
}, - "contexts": [
- {
- "context_key": { },
- "context": [
- {
- "source": "device",
- "metadata": {
- "file_id": "string",
- "contact_id": "string",
- "file_name": "string",
- "file_size": 0,
- "mime_type": "string",
- "uploader": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "uploaded_at": "string",
- "pipeline_ids": [
- "string"
]
}
}
]
}
]
}
]
}
Has same parameters as a regular contacts list, but returns only contact ids. Works faster than regular contact list.
keyword | string Specifies a set of simple search criteria for the query. This simple search is performed on any (indexed in our search engine) field of contact |
fields | string Specifies a comma separated list of fields to return. If this parameter is excluded, all fields will be returned |
tags | boolean Default: true Specifies whether tags should be included in the results. |
last_contacted | boolean Default: true True if return last contacted information, False otherwise |
sort | Array of strings 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. |
query | Array of strings Specifies query for contacts advanced search. Please note, that this parameter not compatible with parameters record_type and keyword |
record_type | string Default: "all" Enum: "person" "company" "all" |
page | integer Default: 1 Specifies which page to display |
per_page | integer Default: 30 Specifies the number of items to return per page of results. |
{- "meta": {
- "page": 0,
- "pages": 0,
- "per_page": 0,
- "total": 0
}, - "resources": [
- "string"
]
}
Returns a list of contacts for the specified identifiers
id required | string A list of contact ids (max 30), separated by a comma |
fields | string Field names to retrieve, otherwise all fields will be retrieved |
meta | boolean True if include fields matadata into response, False otherwise |
tags | boolean True if return tags information, False otherwise |
last_contacted (DEPRECATED, use contexts) | boolean True if return last contacted information, False otherwise |
contexts | any (Contacts.ContactViewContextKinds) Enum: "last_contacted_data" "employers_data" "leads_data" "sequences_data" "contact_files" comma-separated additional contexts that should be returned with in this contact |
{- "contacts_meta": {
- "fields": {
- "instagram": [
- {
- "group": "Contact Info",
- "id": "58e212d729e8e95e88606be5",
- "label": "instagram",
- "modifier": "",
- "multiples": true,
- "name": "instagram",
- "presentation": {
- "type": "single-line-text-box",
- "width": "1"
}, - "read_only": false
}
]
}, - "groups": {
- "Contact Info": {
- "id": "58e212d729e8e95e88606bc7",
- "is_standard": true,
- "label": "Contact Info",
- "name": "Contact Info",
- "order": [
- "instagram"
], - "type": "both"
}
}
}, - "resources": [
- {
- "avatar_url": "string",
- "children": [
- "string"
], - "employers_info": [
- {
- "company_name": "string",
- "contact_id": "string"
}
], - "company_last_contacted": {
- "in": {
- "deletion_tstamp": { },
- "object_id": { },
- "tstamp": { },
- "type": { },
- "user_id": { },
- "direction": "inbound"
}, - "out": {
- "deletion_tstamp": { },
- "object_id": { },
- "tstamp": { },
- "type": { },
- "user_id": { },
- "direction": "inbound"
}
}, - "lc": {
- "company_lc": {
- "in": {
- "deletion_tstamp": { },
- "object_id": { },
- "tstamp": { },
- "type": { },
- "user_id": { },
- "direction": "inbound"
}, - "out": {
- "deletion_tstamp": { },
- "object_id": { },
- "tstamp": { },
- "type": { },
- "user_id": { },
- "direction": "inbound"
}, - "last": {
- "deletion_tstamp": { },
- "object_id": { },
- "tstamp": { },
- "type": { },
- "user_id": { },
- "direction": "inbound"
}
}, - "user_lc": {
- "in": {
- "deletion_tstamp": { },
- "object_id": { },
- "tstamp": { },
- "type": { },
- "user_id": { },
- "direction": "inbound"
}, - "out": {
- "deletion_tstamp": { },
- "object_id": { },
- "tstamp": { },
- "type": { },
- "user_id": { },
- "direction": "inbound"
}, - "last": {
- "deletion_tstamp": { },
- "object_id": { },
- "tstamp": { },
- "type": { },
- "user_id": { },
- "direction": "inbound"
}
}, - "last_user": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}
}, - "created": "string",
- "creator": "string",
- "fields": {
- "property1": [
- {
- "field_id": "string",
- "modifier": "string",
- "value": "string"
}
], - "property2": [
- {
- "field_id": "string",
- "modifier": "string",
- "value": "string"
}
]
}, - "id": "string",
- "is_important": { },
- "last_contacted": {
- "deletion_tstamp": { },
- "object_id": { },
- "tstamp": { },
- "type": { },
- "user_id": { },
- "direction": "inbound"
}, - "object_type": "contact",
- "last_contacted_user": "string",
- "owner_id": "string",
- "privacy": {
- "edit": {
- "group_ids": [
- "string"
], - "user_ids": [
- "string"
]
}, - "read": {
- "group_ids": [
- "string"
], - "user_ids": [
- "string"
]
}
}, - "record_type": "person",
- "reminder": {
- "active": true,
- "contact_id": "string",
- "days_till_triggered": 0,
- "period": 0,
- "triggered": true
}, - "tags": [
- "string"
], - "updated": "string",
- "updater": "string",
- "stages_info": [
- {
- "pipeline_id": "string",
- "pipeline_name": "string",
- "stage_name": "string",
- "entered_data": "string",
- "is_final": true,
- "days_limit": 0
}
], - "notice": {
- "created": "string",
- "updated": "string",
- "creator": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "updated_by": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "text": "string",
- "color": "string"
}, - "contexts": [
- {
- "context_key": { },
- "context": [
- {
- "source": "device",
- "metadata": {
- "file_id": "string",
- "contact_id": "string",
- "file_name": "string",
- "file_size": 0,
- "mime_type": "string",
- "uploader": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "uploaded_at": "string",
- "pipeline_ids": [
- "string"
]
}
}
]
}
]
}
]
}
Creates contact with data provided. For contact-persons at least first name or last name is required. For contact-companies—company name is required field.
avatar_url | string |
fields required | object 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). |
owner_id | string or null (Contacts.OwnerId) Describes id of user who is owning this contact. Keep in mind that the creator and owner may be different. |
object (Contacts.ContactPrivacy) Defines scopes of object visibility and editability. | |
record_type | string (Contacts.ContactType) Enum: "person" "company" |
tags | string Comma separated list of tags to assign to contacts. If you need to create tags,
containing comma sign — escape it with backslash.
E.g. |
type | string (Contacts.ContactType) Enum: "person" "company" |
{- "avatar_url": "string",
- "fields": { },
- "owner_id": "string",
- "privacy": {
- "edit": {
- "group_ids": [
- "string"
], - "user_ids": [
- "string"
]
}, - "read": {
- "group_ids": [
- "string"
], - "user_ids": [
- "string"
]
}
}, - "record_type": "person",
- "tags": "string",
- "type": "person"
}
{- "avatar_url": "string",
- "children": [
- "string"
], - "employers_info": [
- {
- "company_name": "string",
- "contact_id": "string"
}
], - "company_last_contacted": {
- "in": {
- "deletion_tstamp": { },
- "object_id": { },
- "tstamp": { },
- "type": { },
- "user_id": { },
- "direction": "inbound"
}, - "out": {
- "deletion_tstamp": { },
- "object_id": { },
- "tstamp": { },
- "type": { },
- "user_id": { },
- "direction": "inbound"
}
}, - "lc": {
- "company_lc": {
- "in": {
- "deletion_tstamp": { },
- "object_id": { },
- "tstamp": { },
- "type": { },
- "user_id": { },
- "direction": "inbound"
}, - "out": {
- "deletion_tstamp": { },
- "object_id": { },
- "tstamp": { },
- "type": { },
- "user_id": { },
- "direction": "inbound"
}, - "last": {
- "deletion_tstamp": { },
- "object_id": { },
- "tstamp": { },
- "type": { },
- "user_id": { },
- "direction": "inbound"
}
}, - "user_lc": {
- "in": {
- "deletion_tstamp": { },
- "object_id": { },
- "tstamp": { },
- "type": { },
- "user_id": { },
- "direction": "inbound"
}, - "out": {
- "deletion_tstamp": { },
- "object_id": { },
- "tstamp": { },
- "type": { },
- "user_id": { },
- "direction": "inbound"
}, - "last": {
- "deletion_tstamp": { },
- "object_id": { },
- "tstamp": { },
- "type": { },
- "user_id": { },
- "direction": "inbound"
}
}, - "last_user": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}
}, - "created": "string",
- "creator": "string",
- "fields": {
- "property1": [
- {
- "field_id": "string",
- "modifier": "string",
- "value": "string"
}
], - "property2": [
- {
- "field_id": "string",
- "modifier": "string",
- "value": "string"
}
]
}, - "id": "string",
- "is_important": { },
- "last_contacted": {
- "deletion_tstamp": { },
- "object_id": { },
- "tstamp": { },
- "type": { },
- "user_id": { },
- "direction": "inbound"
}, - "object_type": "contact",
- "last_contacted_user": "string",
- "owner_id": "string",
- "privacy": {
- "edit": {
- "group_ids": [
- "string"
], - "user_ids": [
- "string"
]
}, - "read": {
- "group_ids": [
- "string"
], - "user_ids": [
- "string"
]
}
}, - "record_type": "person",
- "reminder": {
- "active": true,
- "contact_id": "string",
- "days_till_triggered": 0,
- "period": 0,
- "triggered": true
}, - "tags": [
- "string"
], - "updated": "string",
- "updater": "string",
- "stages_info": [
- {
- "pipeline_id": "string",
- "pipeline_name": "string",
- "stage_name": "string",
- "entered_data": "string",
- "is_final": true,
- "days_limit": 0
}
], - "notice": {
- "created": "string",
- "updated": "string",
- "creator": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "updated_by": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "text": "string",
- "color": "string"
}, - "contexts": [
- {
- "context_key": { },
- "context": [
- {
- "source": "device",
- "metadata": {
- "file_id": "string",
- "contact_id": "string",
- "file_name": "string",
- "file_size": 0,
- "mime_type": "string",
- "uploader": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "uploaded_at": "string",
- "pipeline_ids": [
- "string"
]
}
}
]
}
]
}
Returns contact
contact_id required | string id of a contact to operate on |
fields | string Field names to retrieve, otherwise all fields will be retrieved |
meta | boolean True if include fields matadata into response, False otherwise |
tags | boolean True if return tags information, False otherwise |
last_contacted (DEPRECATED, use contexts) | boolean True if return last contacted information, False otherwise |
leads_data (DEPRECATED, use contexts) | boolean Default: true True if return leads pipeline info, False otherwise |
contexts | any (Contacts.ContactViewContextKinds) Enum: "last_contacted_data" "employers_data" "leads_data" "sequences_data" "contact_files" comma-separated additional contexts that should be returned with in this contact |
{- "contacts_meta": {
- "fields": {
- "instagram": [
- {
- "group": "Contact Info",
- "id": "58e212d729e8e95e88606be5",
- "label": "instagram",
- "modifier": "",
- "multiples": true,
- "name": "instagram",
- "presentation": {
- "type": "single-line-text-box",
- "width": "1"
}, - "read_only": false
}
]
}, - "groups": {
- "Contact Info": {
- "id": "58e212d729e8e95e88606bc7",
- "is_standard": true,
- "label": "Contact Info",
- "name": "Contact Info",
- "order": [
- "instagram"
], - "type": "both"
}
}
}, - "resources": [
- {
- "avatar_url": "string",
- "children": [
- "string"
], - "employers_info": [
- {
- "company_name": "string",
- "contact_id": "string"
}
], - "company_last_contacted": {
- "in": {
- "deletion_tstamp": { },
- "object_id": { },
- "tstamp": { },
- "type": { },
- "user_id": { },
- "direction": "inbound"
}, - "out": {
- "deletion_tstamp": { },
- "object_id": { },
- "tstamp": { },
- "type": { },
- "user_id": { },
- "direction": "inbound"
}
}, - "lc": {
- "company_lc": {
- "in": {
- "deletion_tstamp": { },
- "object_id": { },
- "tstamp": { },
- "type": { },
- "user_id": { },
- "direction": "inbound"
}, - "out": {
- "deletion_tstamp": { },
- "object_id": { },
- "tstamp": { },
- "type": { },
- "user_id": { },
- "direction": "inbound"
}, - "last": {
- "deletion_tstamp": { },
- "object_id": { },
- "tstamp": { },
- "type": { },
- "user_id": { },
- "direction": "inbound"
}
}, - "user_lc": {
- "in": {
- "deletion_tstamp": { },
- "object_id": { },
- "tstamp": { },
- "type": { },
- "user_id": { },
- "direction": "inbound"
}, - "out": {
- "deletion_tstamp": { },
- "object_id": { },
- "tstamp": { },
- "type": { },
- "user_id": { },
- "direction": "inbound"
}, - "last": {
- "deletion_tstamp": { },
- "object_id": { },
- "tstamp": { },
- "type": { },
- "user_id": { },
- "direction": "inbound"
}
}, - "last_user": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}
}, - "created": "string",
- "creator": "string",
- "fields": {
- "property1": [
- {
- "field_id": "string",
- "modifier": "string",
- "value": "string"
}
], - "property2": [
- {
- "field_id": "string",
- "modifier": "string",
- "value": "string"
}
]
}, - "id": "string",
- "is_important": { },
- "last_contacted": {
- "deletion_tstamp": { },
- "object_id": { },
- "tstamp": { },
- "type": { },
- "user_id": { },
- "direction": "inbound"
}, - "object_type": "contact",
- "last_contacted_user": "string",
- "owner_id": "string",
- "privacy": {
- "edit": {
- "group_ids": [
- "string"
], - "user_ids": [
- "string"
]
}, - "read": {
- "group_ids": [
- "string"
], - "user_ids": [
- "string"
]
}
}, - "record_type": "person",
- "reminder": {
- "active": true,
- "contact_id": "string",
- "days_till_triggered": 0,
- "period": 0,
- "triggered": true
}, - "tags": [
- "string"
], - "updated": "string",
- "updater": "string",
- "stages_info": [
- {
- "pipeline_id": "string",
- "pipeline_name": "string",
- "stage_name": "string",
- "entered_data": "string",
- "is_final": true,
- "days_limit": 0
}
], - "notice": {
- "created": "string",
- "updated": "string",
- "creator": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "updated_by": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "text": "string",
- "color": "string"
}, - "contexts": [
- {
- "context_key": { },
- "context": [
- {
- "source": "device",
- "metadata": {
- "file_id": "string",
- "contact_id": "string",
- "file_name": "string",
- "file_size": 0,
- "mime_type": "string",
- "uploader": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "uploaded_at": "string",
- "pipeline_ids": [
- "string"
]
}
}
]
}
]
}
]
}
Updates contact
contact_id required | string id of a contact to operate on |
type | string Enum: "0" "1"
|
leads_data | boolean Default: true True if return leads pipeline info, False otherwise |
avatar_url | string |
fields | object 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). |
is_important | boolean |
{- "avatar_url": "string",
- "fields": { },
- "is_important": true
}
{- "avatar_url": "string",
- "children": [
- "string"
], - "employers_info": [
- {
- "company_name": "string",
- "contact_id": "string"
}
], - "company_last_contacted": {
- "in": {
- "deletion_tstamp": { },
- "object_id": { },
- "tstamp": { },
- "type": { },
- "user_id": { },
- "direction": "inbound"
}, - "out": {
- "deletion_tstamp": { },
- "object_id": { },
- "tstamp": { },
- "type": { },
- "user_id": { },
- "direction": "inbound"
}
}, - "lc": {
- "company_lc": {
- "in": {
- "deletion_tstamp": { },
- "object_id": { },
- "tstamp": { },
- "type": { },
- "user_id": { },
- "direction": "inbound"
}, - "out": {
- "deletion_tstamp": { },
- "object_id": { },
- "tstamp": { },
- "type": { },
- "user_id": { },
- "direction": "inbound"
}, - "last": {
- "deletion_tstamp": { },
- "object_id": { },
- "tstamp": { },
- "type": { },
- "user_id": { },
- "direction": "inbound"
}
}, - "user_lc": {
- "in": {
- "deletion_tstamp": { },
- "object_id": { },
- "tstamp": { },
- "type": { },
- "user_id": { },
- "direction": "inbound"
}, - "out": {
- "deletion_tstamp": { },
- "object_id": { },
- "tstamp": { },
- "type": { },
- "user_id": { },
- "direction": "inbound"
}, - "last": {
- "deletion_tstamp": { },
- "object_id": { },
- "tstamp": { },
- "type": { },
- "user_id": { },
- "direction": "inbound"
}
}, - "last_user": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}
}, - "created": "string",
- "creator": "string",
- "fields": {
- "property1": [
- {
- "field_id": "string",
- "modifier": "string",
- "value": "string"
}
], - "property2": [
- {
- "field_id": "string",
- "modifier": "string",
- "value": "string"
}
]
}, - "id": "string",
- "is_important": { },
- "last_contacted": {
- "deletion_tstamp": { },
- "object_id": { },
- "tstamp": { },
- "type": { },
- "user_id": { },
- "direction": "inbound"
}, - "object_type": "contact",
- "last_contacted_user": "string",
- "owner_id": "string",
- "privacy": {
- "edit": {
- "group_ids": [
- "string"
], - "user_ids": [
- "string"
]
}, - "read": {
- "group_ids": [
- "string"
], - "user_ids": [
- "string"
]
}
}, - "record_type": "person",
- "reminder": {
- "active": true,
- "contact_id": "string",
- "days_till_triggered": 0,
- "period": 0,
- "triggered": true
}, - "tags": [
- "string"
], - "updated": "string",
- "updater": "string",
- "stages_info": [
- {
- "pipeline_id": "string",
- "pipeline_name": "string",
- "stage_name": "string",
- "entered_data": "string",
- "is_final": true,
- "days_limit": 0
}
], - "notice": {
- "created": "string",
- "updated": "string",
- "creator": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "updated_by": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "text": "string",
- "color": "string"
}, - "contexts": [
- {
- "context_key": { },
- "context": [
- {
- "source": "device",
- "metadata": {
- "file_id": "string",
- "contact_id": "string",
- "file_name": "string",
- "file_size": 0,
- "mime_type": "string",
- "uploader": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "uploaded_at": "string",
- "pipeline_ids": [
- "string"
]
}
}
]
}
]
}
(DEPRECATED) This method return all available metadata for company's fields/groups.
{- "fields": {
- "instagram": [
- {
- "group": "Contact Info",
- "id": "58e212d729e8e95e88606be5",
- "label": "instagram",
- "modifier": "",
- "multiples": true,
- "name": "instagram",
- "presentation": {
- "type": "single-line-text-box",
- "width": "1"
}, - "read_only": false
}
]
}, - "groups": {
- "Contact Info": {
- "id": "58e212d729e8e95e88606bc7",
- "is_standard": true,
- "label": "Contact Info",
- "name": "Contact Info",
- "order": [
- "instagram"
], - "type": "both"
}
}
}
Creates a note on one or more contacts. At least one contact id is required as Nimble currently doesn't support notes without contacts.
contact_ids required | Array of strings List of contacts’ IDs in BSON format to which the note will be attached. Contacts count should be between 1 and 10. |
note required | string |
note_preview required | string Short version of note, that will be used for preview purposes |
{- "contact_ids": [
- "string"
], - "note": "string",
- "note_preview": "string"
}
{- "author_name": "string",
- "contacts": [
- {
- "avatar_url": "string",
- "contact_type": "person",
- "email": [
- "string"
], - "id": "string",
- "is_viewable": true,
- "name": "string",
- "employment": {
- "company_name": "string",
- "title": "string"
}, - "phones": {
- "label": "string",
- "value": "string"
}
}
], - "created": "string",
- "id": "string",
- "note": "string",
- "note_preview": "string",
- "owner_id": "string",
- "owner": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "updated": "string"
}
return single note
note_id required | string |
{- "author_name": "string",
- "contacts": [
- {
- "avatar_url": "string",
- "contact_type": "person",
- "email": [
- "string"
], - "id": "string",
- "is_viewable": true,
- "name": "string",
- "employment": {
- "company_name": "string",
- "title": "string"
}, - "phones": {
- "label": "string",
- "value": "string"
}
}
], - "created": "string",
- "id": "string",
- "note": "string",
- "note_preview": "string",
- "owner_id": "string",
- "owner": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "updated": "string"
}
create contact note
note_id required | string |
contact_ids required | Array of strings List of contacts’ IDs in BSON format to which the note will be attached. Contacts count should be between 1 and 10. |
note required | string |
note_preview required | string Short version of note, that will be used for preview purposes |
{- "contact_ids": [
- "string"
], - "note": "string",
- "note_preview": "string"
}
{- "author_name": "string",
- "contacts": [
- {
- "avatar_url": "string",
- "contact_type": "person",
- "email": [
- "string"
], - "id": "string",
- "is_viewable": true,
- "name": "string",
- "employment": {
- "company_name": "string",
- "title": "string"
}, - "phones": {
- "label": "string",
- "value": "string"
}
}
], - "created": "string",
- "id": "string",
- "note": "string",
- "note_preview": "string",
- "owner_id": "string",
- "owner": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "updated": "string"
}
update contact note
note_id required | string |
contact_ids required | Array of strings List of contacts’ IDs in BSON format to which the note will be attached. Contacts count should be between 1 and 10. |
note required | string |
note_preview required | string Short version of note, that will be used for preview purposes |
{- "contact_ids": [
- "string"
], - "note": "string",
- "note_preview": "string"
}
{- "author_name": "string",
- "contacts": [
- {
- "avatar_url": "string",
- "contact_type": "person",
- "email": [
- "string"
], - "id": "string",
- "is_viewable": true,
- "name": "string",
- "employment": {
- "company_name": "string",
- "title": "string"
}, - "phones": {
- "label": "string",
- "value": "string"
}
}
], - "created": "string",
- "id": "string",
- "note": "string",
- "note_preview": "string",
- "owner_id": "string",
- "owner": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "updated": "string"
}
Returns a list of notes for the specified contact
contact_id required | string id of a contact to operate on |
page | integer |
per_page | integer |
{- "meta": {
- "has_more": true,
- "page": 0,
- "pages": 0,
- "per_page": 0,
- "total": 0
}, - "resources": [
- {
- "author_name": "string",
- "contacts": [
- {
- "avatar_url": "string",
- "contact_type": "person",
- "email": [
- "string"
], - "id": "string",
- "is_viewable": true,
- "name": "string",
- "employment": {
- "company_name": "string",
- "title": "string"
}, - "phones": {
- "label": "string",
- "value": "string"
}
}
], - "created": "string",
- "id": "string",
- "note": "string",
- "note_preview": "string",
- "owner_id": "string",
- "owner": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "updated": "string"
}
]
}
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,
"read_only": false
}
],
"email": [
{
"group": "Contact Info",
"name": "email",
"label": "email",
"modifier": "other",
"presentation": {},
"id": "5049f697a694620a07000065",
"multiples": true,
"read_only": false
},
{
"group": "Contact Info",
"name": "email",
"label": "email",
"modifier": "personal",
"presentation": {},
"id": "5049f697a694620a07000064",
"multiples": true,
"read_only": false
}
],
"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,
"read_only": 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.
- *read_only* - if contacts field values is editable by user
groups
:
Information about field groups. Represented by dictionary where keys are unique group names and values are dictionaries with more info. Groups info dictionary contains following fields:
: - *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`.
Contact's metadata contains information about all basic and custom fields created in Nimble for a user. Below is it's typical structure. All default contact fields are described here
{
"tabs": [
{
"tab_id": "string",
"tab_name": "string",
"contact_types": "person",
"is_standard": true,
"members": [
{
"type": "group",
"name": "string",
"group_id": "string",
"logo_id": "string",
"fields": [
{
"type": "field",
"name": "string",
"field_id": "string",
"modifier": "string",
"multiples": true,
"read_only": true,
"field_type": {
"field_kind": "string",
"validation_rule": {
"type": "email"
}
},
"presentation": {
"number_type": "integer"
},
"available_actions": "edit_all"
}
]
}
],
"available_actions": "edit_all"
}
]
}
Here is a description of the response in detail:
tabs
: - tab_id --- unique id of the tab.
- tab_name --- name representing the tab in human-readable form.
- contact_types --- contact types that could have fields of the
tab. Possible values: person
, company
- is_standard --- whether this tab belongs to standard Nimble
tabs.
- available_actions - possible values: edit_all
,
rearrange_only
, view_only
.
- members - list of tab members. Its could be groups and fields
without groups.
groups
: - type --- tab member type. It is always "group" here. - name --- name representing group in human-readable form. - group_id --- unique id of the group. - logo_id --- id of logo to show - is_standard - whether this group belongs to standard Nimble groups. - fields - list of fields contained in group.
fields
: - type --- tab member type. It is always "field" here.
- name --- name representing field in human-readable form.
- field_id --- unique id of the field.
- modifier --- name of the field's modifier
- multiples - indicates whether field could have multiple values
(under different modifiers).
- read_only - if field values available for editing
- field_type - dictionary describing field type. More details
are at described here <field-type>
{.interpreted-text
role="ref"}.
- presentation - dictionary describing how field should be
presented in Nimble client. More details are at
described here <field-presentations>
{.interpreted-text
role="ref"}.
- available_actions - possible values: edit_all
,
edit_choices_only
, view_only
.
The image below shows schema of fields metadata. Blue rectangle - tab, green rectangle - group, red rectangle - field. As you can see, fields could be a member of a tab or a group. The same metadata schema is used for deals metadata.
Simple text fields, like first name
, last name
, title
,
description
, etc.
Field Name | Type | Multiple field | Modificators | Notes |
---|---|---|---|---|
first name | default |
- | N/A | For person contact |
last name | default |
- | N/A | For person contact |
middle name | default |
- | N/A | |
company name | default |
- | N/A | For company contact |
title (deprecated, use contact employment |
default |
- | N/A | |
parent company (deprecated, use contact employment |
parent company |
- | N/A | |
contact employment | contact employment |
+ | N/A | |
domain | domain |
- | N/A | Unique. For company contact |
phone | default |
+ | work home mobile main home fax work fax other |
|
default |
+ | work personal other |
||
skype id | default |
+ | N/A | |
social |
+ | N/A | ||
social |
+ | N/A | ||
social |
+ | N/A | ||
google plus | social |
+ | N/A | |
foursquare | social |
+ | N/A | |
address | address |
+ | work home other |
|
hubspot | default |
- | N/A | |
URL | default |
+ | work personal blog other |
|
description | default |
+ | other google+ foursquare |
If possible, fetches descriptions from social networks |
annual revenue | default |
- | N/A | |
# of employees | dropdown |
- | N/A | |
lead status | dropdown |
- | N/A | |
rating | dropdown |
- | N/A | |
lead source | dropdown |
- | N/A | |
lead type | dropdown |
- | N/A | |
birthday | default |
- | N/A |
Tab Name | Description | Fields |
---|---|---|
Personal Info | Personal contact's details | - first name, - last name, - middle name, - title, - parent company, - birthday - employment |
Company Info | Extended information about contact's company | - annual revenue, - company name, - domain, - # of employees |
Contact Info | How to reach this contact | - phone, - email, - skype id, - twitter, - facebook, - linkedin, - google+, - foursquare, - address, - description, - URL, - hubspot |
Lead Details | Information about contact as lead | - rating, - lead stage |
Additional Lead Fields | Legacy fields | - lead status, - lead source, - lead type |
Extra Info | Contact's extended information | * Files |
The domain field. Example: nimble.com
. This field satisfies the
following conditions:
- Unique in terms of team. It is possible to have only one company record with particular value in the whole account.
- Properly formatted. No protocol or path is allowed, it can have 3rd level domain at most.
- It can be assigned to company records only
Show data about field type. You can't change it after creation. It is a dictionary with at least one field - field_kind.
field_kind --- represents type of field in nimble. It can have one of the following values:
- string --- simple field with one line of text
- long_string --- field, containing multiline text
- choice --- drop-down list with predefined values, require additional parameter
values
. Value of the field contains id of one of choice values- number - field with integer or decimal number
- datetime - string formatted in ISO 8601
- boolean - field with true/false value
- address --- field with address, that will allow input of address in Nimble default format
- user - field, containing id of the Nimble user
Examples:
"field_type": {
"field_kind": "string"
}
"field_type": {
"field_kind": "choice",
"values": {
"ordering_type": "ordinal",
"values": [{"id": "string", "value": "string"}]
}
}
To control, how contacts will look in Nimble, special parameter
presentation
included in fields metadata. Usually it is a dictionary
with few fields. You can change presentation after field creation. Must
match to corresponding field_type. Date and number fields must have an
appropriate presentation. There is no presentation for other types
Date presentation:
- date_format --- strftime-like format template as described in https://docs.python.org/2.7/library/datetime.html#strftime-and-strptime-behavior or null if client should use date format from user settings
- ignore_specific_time --- show if time should be presented in the field. Applicable only if date_format is None. Must be null if date_format specified
Examples:
"presentation": { "date_format": null, "ignore_specific_time": false }
"presentation": { "date_format": "%Y-%m-%dT%H:%M:%S", "ignore_specific_time": null }
Number presentation:
- number_type --- possible values: "integer", "decimal", "percentage", "financial"
- fraction_digits --- integer >= 1 that shows count of digits after comma. Applicable for decimal and percentage only.
Examples:
"presentation": { "number_type": "integer", }
"presentation": { "number_type": "decimal", "fraction_digits": 2 }
"presentation": { "number_type": "percentage", "fraction_digits": 1 }
"presentation": { "number_type": "financial" }
Fields, showing as drop-down lists in Nimble. In metadata they have
field_type
equal choice
. Also, their metadata contains field
values
, representing drop-down content. This field contains list of
dictionaries, having two keys:
id
: Value, to be stored in field
value
: String, corresponding to this value
Example:
{
"read_only": false,
"field_type": {
"values": {
"ordering_type": "ordinal",
"values": [
{
"id": "1",
"value": "Analyst"
},
{
"id": "2",
"value": "Competitor"
},
{
"id": "3",
"value": "Customer"
},
{
"id": "4",
"value": "Investor"
},
{
"id": "5",
"value": "Lead"
},
{
"id": "6",
"value": "Partner"
},
{
"id": "7",
"value": "Press"
},
{
"id": "8",
"value": "Prospect"
},
{
"id": "9",
"value": "Reseller"
},
{
"id": "10",
"value": "Other"
},
{
"id": "12",
"value": "7"
}
]
},
"field_kind": "choice"
},
"name": "lead type",
"available_actions": "edit_choices_only",
"field_id": "6023b729ec8d835bb32ee4c9",
"modifier": "",
"type": "field",
"multiples": false
}
All values represented as dictionary with following keys: street
,
city
, state
, zip
, country
. This dictionary should be dumped to
JSON string, and this string should be used as field's value.
Example:
{
"type": "person",
"fields": {
"address": [{
"value": "{\"street\":\"Test\", \"city\":\"Testing\", \"country\":\"Togo\"}",
"modifier": "other"
}]
}
}
All values represented as dictionary with following keys:
company_name
, title
, start_date
, end_date
. Where start_date
and end_date
are dates (in the format mm/yyyy) to indicate in what
period of time this employment took place. These fields are optional;
however, at least one of company_name
or title
must have a non-null
value.
This dictionary should be dumped to JSON string, and this string should be used as field's value.
Example:
{
"type": "person",
"fields": {
"contact employment": [{
"value": "{\"company_name\": \"4tree GmbH (a wholly owned subsidiary of McKinsey & Company)\", \"end_date\": \"01/2022\", \"is_present\": false, \"start_date\": \"07/2019\", \"title\": \"HR\"}",
}]
}
}
Field, containing id of the Nimble user. Example of value:
[
{
"is_primary": false,
"modifier": "",
"value": "602aaa34f92ea11bb5cebae1",
}
]
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.
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.
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
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.
Note
To get relevant results you may use
sorting <contact_list_sorting>
by
relevance.
Note
In the table below (old)
means only another(previously used) behaviour
of search operator, API parameters is still same.
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 contact_list_sorting set to by relevance in descending 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 | Field 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/months | {"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 criteria | {"rating": {"gte": "3"}} |
lte | Field value with specified name have greater or equal value than provided in the search criteria | {"rating": {"lte": "3"}} |
Full list of available search operators
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
Full list of available field types for searching on them
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:
{
"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"}}}
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"
}
},
"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
{
"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": {
"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
{
"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"]
}
}
}
}
}
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
::: title
Note
:::
::::
Parameter `record_type` will be ignored, if `query` parameter was
specified. To filter persons/companies, please use corresponding sub
query in query.
:::: note
::: title
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" } } ] }
On success, results are returned in format, similar to contacts
listing response <contact-resources-response>
Return all available metadata for company's fields
{- "tabs": [
- {
- "tab_id": "string",
- "tab_name": "string",
- "contact_types": "person",
- "is_standard": true,
- "members": [
- {
- "type": "group",
- "name": "string",
- "group_id": "string",
- "logo_id": "string",
- "fields": [
- {
- "type": "field",
- "name": "string",
- "field_id": "string",
- "modifier": "string",
- "multiples": true,
- "read_only": true,
- "field_type": {
- "field_kind": "string",
- "validation_rule": {
- "type": "email"
}
}, - "presentation": {
- "number_type": "integer"
}, - "available_actions": "edit_all"
}
]
}
], - "available_actions": "edit_all"
}
]
}
Create new field
required | Fields.StringFieldValuesType (object) or Fields.LongStringFieldValuesType (object) or Fields.ChoiceFieldValuesType (object) or Fields.NumberFieldValuesType (object) or Fields.DateTimeFieldValuesType (object) or Fields.BooleanFieldValuesType (object) or Fields.AddressFieldValuesType (object) or Fields.UserFieldValuesType (object) (Fields.FieldTypeOnFieldCreation) |
group_id required | string or null |
insert_after required | string or null If not null, inserts a new field after another field or group with specified id. If null, then inserted field to be the first one |
name required | string [ 1 .. 50 ] characters |
required | Fields.IntegerNumberPresentation (object) or Fields.DecimalNumberPresentation (object) or Fields.PercentageNumberPresentation (object) or Fields.FinancialNumberPresentation (object) or Fields.DateTimePresentation (object) (Fields.FieldPresentation) how values of the field should look. Must match to corresponding field_type. Date and number fields must have an appropriate presentation. There is no presentation for other types |
tab_id required | string |
multiples | boolean whether this field can hold multiple values (by default, false) |
{- "field_type": {
- "field_kind": "string",
- "validation_rule": {
- "type": "email"
}
}, - "group_id": "string",
- "insert_after": "string",
- "name": "string",
- "presentation": {
- "number_type": "integer"
}, - "tab_id": "string",
- "multiples": true
}
{- "tab_id": "string",
- "tab_name": "string",
- "contact_types": "person",
- "is_standard": true,
- "members": [
- {
- "type": "group",
- "name": "string",
- "group_id": "string",
- "logo_id": "string",
- "fields": [
- {
- "type": "field",
- "name": "string",
- "field_id": "string",
- "modifier": "string",
- "multiples": true,
- "read_only": true,
- "field_type": {
- "field_kind": "string",
- "validation_rule": {
- "type": "email"
}
}, - "presentation": {
- "number_type": "integer"
}, - "available_actions": "edit_all"
}
]
}
], - "available_actions": "edit_all"
}
Updates existing field
field_id required | string |
group_id | string or null If not null, move field to specified group. Null if remove field from grooup |
insert_after | string or null If not null, move field after another field or group with specified id. If null, then moved field to be the first one |
name | string [ 1 .. 50 ] characters |
Fields.IntegerNumberPresentation (object) or Fields.DecimalNumberPresentation (object) or Fields.PercentageNumberPresentation (object) or Fields.FinancialNumberPresentation (object) or Fields.DateTimePresentation (object) (Fields.FieldPresentation) how values of the field should look. Must match to corresponding field_type. Date and number fields must have an appropriate presentation. There is no presentation for other types | |
tab_id | string |
{- "group_id": "string",
- "insert_after": "string",
- "name": "string",
- "presentation": {
- "number_type": "integer"
}, - "tab_id": "string"
}
{- "tab_id": "string",
- "tab_name": "string",
- "contact_types": "person",
- "is_standard": true,
- "members": [
- {
- "type": "group",
- "name": "string",
- "group_id": "string",
- "logo_id": "string",
- "fields": [
- {
- "type": "field",
- "name": "string",
- "field_id": "string",
- "modifier": "string",
- "multiples": true,
- "read_only": true,
- "field_type": {
- "field_kind": "string",
- "validation_rule": {
- "type": "email"
}
}, - "presentation": {
- "number_type": "integer"
}, - "available_actions": "edit_all"
}
]
}
], - "available_actions": "edit_all"
}
Create new fields group
insert_after required | string or null If not null, inserts a new group after another group or field with specified id. If null, then tab is inserted as the first one |
logo_id required | string |
name required | string [ 1 .. 50 ] characters |
tab_id required | string |
{- "insert_after": "string",
- "logo_id": "string",
- "name": "string",
- "tab_id": "string"
}
{- "tab_id": "string",
- "tab_name": "string",
- "contact_types": "person",
- "is_standard": true,
- "members": [
- {
- "type": "group",
- "name": "string",
- "group_id": "string",
- "logo_id": "string",
- "fields": [
- {
- "type": "field",
- "name": "string",
- "field_id": "string",
- "modifier": "string",
- "multiples": true,
- "read_only": true,
- "field_type": {
- "field_kind": "string",
- "validation_rule": {
- "type": "email"
}
}, - "presentation": {
- "number_type": "integer"
}, - "available_actions": "edit_all"
}
]
}
], - "available_actions": "edit_all"
}
Updates existing fields group
group_id required | string |
insert_after | string or null If not null, move group after another field or group with specified id. If null, then move group to the first position |
logo_id | string |
name | string [ 1 .. 50 ] characters |
tab_id | string |
{- "insert_after": "string",
- "logo_id": "string",
- "name": "string",
- "tab_id": "string"
}
{- "tab_id": "string",
- "tab_name": "string",
- "contact_types": "person",
- "is_standard": true,
- "members": [
- {
- "type": "group",
- "name": "string",
- "group_id": "string",
- "logo_id": "string",
- "fields": [
- {
- "type": "field",
- "name": "string",
- "field_id": "string",
- "modifier": "string",
- "multiples": true,
- "read_only": true,
- "field_type": {
- "field_kind": "string",
- "validation_rule": {
- "type": "email"
}
}, - "presentation": {
- "number_type": "integer"
}, - "available_actions": "edit_all"
}
]
}
], - "available_actions": "edit_all"
}
Create new fields tabs
contact_types required | Array of strings (Contacts.ContactType) Items Enum: "person" "company" |
insert_after required | string or null If not null, inserts a new tab after another tab with specified id. If null, then tab is inserted as the first one |
tab_name required | string [ 1 .. 50 ] characters |
{- "contact_types": [
- "person"
], - "insert_after": "string",
- "tab_name": "string"
}
{- "tab_id": "string",
- "tab_name": "string",
- "contact_types": "person",
- "is_standard": true,
- "members": [
- {
- "type": "group",
- "name": "string",
- "group_id": "string",
- "logo_id": "string",
- "fields": [
- {
- "type": "field",
- "name": "string",
- "field_id": "string",
- "modifier": "string",
- "multiples": true,
- "read_only": true,
- "field_type": {
- "field_kind": "string",
- "validation_rule": {
- "type": "email"
}
}, - "presentation": {
- "number_type": "integer"
}, - "available_actions": "edit_all"
}
]
}
], - "available_actions": "edit_all"
}
Updates existing fields tab
tab_id required | string |
contact_types | string (Contacts.ContactType) Enum: "person" "company" |
insert_after | string or null Moves tab after another tab with specified id. If null, then move tab to the first position |
tab_name | string [ 1 .. 50 ] characters |
{- "contact_types": "person",
- "insert_after": "string",
- "tab_name": "string"
}
{- "tab_id": "string",
- "tab_name": "string",
- "contact_types": "person",
- "is_standard": true,
- "members": [
- {
- "type": "group",
- "name": "string",
- "group_id": "string",
- "logo_id": "string",
- "fields": [
- {
- "type": "field",
- "name": "string",
- "field_id": "string",
- "modifier": "string",
- "multiples": true,
- "read_only": true,
- "field_type": {
- "field_kind": "string",
- "validation_rule": {
- "type": "email"
}
}, - "presentation": {
- "number_type": "integer"
}, - "available_actions": "edit_all"
}
]
}
], - "available_actions": "edit_all"
}
Create choice for field
field_id required | string |
id required | string |
insert_after required | string or null If not null, inserts a new choice after another choice with specified id. If null, then inserted choice to be the first one in field |
value required | string |
{- "id": "string",
- "insert_after": "string",
- "value": "string"
}
{- "tab_id": "string",
- "tab_name": "string",
- "contact_types": "person",
- "is_standard": true,
- "members": [
- {
- "type": "group",
- "name": "string",
- "group_id": "string",
- "logo_id": "string",
- "fields": [
- {
- "type": "field",
- "name": "string",
- "field_id": "string",
- "modifier": "string",
- "multiples": true,
- "read_only": true,
- "field_type": {
- "field_kind": "string",
- "validation_rule": {
- "type": "email"
}
}, - "presentation": {
- "number_type": "integer"
}, - "available_actions": "edit_all"
}
]
}
], - "available_actions": "edit_all"
}
Deletes choice by id
field_id required | string |
id required | string |
preflight_checks required | boolean |
{- "tabs": [
- {
- "tab_id": "string",
- "tab_name": "string",
- "contact_types": "person",
- "is_standard": true,
- "members": [
- {
- "type": "group",
- "name": "string",
- "group_id": "string",
- "logo_id": "string",
- "fields": [
- {
- "type": "field",
- "name": "string",
- "field_id": "string",
- "modifier": "string",
- "multiples": true,
- "read_only": true,
- "field_type": {
- "field_kind": "string",
- "validation_rule": {
- "type": "email"
}
}, - "presentation": {
- "number_type": "integer"
}, - "available_actions": "edit_all"
}
]
}
], - "available_actions": "edit_all"
}
]
}
Updates choise
field_id required | string |
id required | string |
id required | string |
insert_after | string or null If not null, move choice after another choice with specified id. If null, then moved choice to be the first one |
value | string |
{- "id": "string",
- "insert_after": "string",
- "value": "string"
}
{- "tabs": [
- {
- "tab_id": "string",
- "tab_name": "string",
- "contact_types": "person",
- "is_standard": true,
- "members": [
- {
- "type": "group",
- "name": "string",
- "group_id": "string",
- "logo_id": "string",
- "fields": [
- {
- "type": "field",
- "name": "string",
- "field_id": "string",
- "modifier": "string",
- "multiples": true,
- "read_only": true,
- "field_type": {
- "field_kind": "string",
- "validation_rule": {
- "type": "email"
}
}, - "presentation": {
- "number_type": "integer"
}, - "available_actions": "edit_all"
}
]
}
], - "available_actions": "edit_all"
}
]
}
delete is_primary mark from field
contact_id required | string |
field_id required | string |
position required | integer >= 0 |
{- "field_id": "string",
- "position": 0
}
{- "object_id": "4f2acc3142a053dda595f00b",
- "object_type": "deal"
}
mark field with is_primary flag
contact_id required | string |
field_id required | string |
position required | integer >= 0 |
{- "field_id": "string",
- "position": 0
}
{- "object_id": "4f2acc3142a053dda595f00b",
- "object_type": "deal"
}
Retrieves list of all user deals
sort required | string <field:order> |
limit | integer |
{- "meta": {
- "per_page": 0,
- "total": 0,
- "page": 0,
- "pages": 0
}, - "resources": [
- {
- "updated": "string",
- "deal_id": "string",
- "creator": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "related_external_contacts": [
- {
- "contact_info": "string",
- "note": "string"
}
], - "privacy": {
- "read": true,
- "edit": true
}, - "updated_by": "string",
- "created": "string",
- "is_editable": true,
- "currency": "string",
- "related_contacts": [
- {
- "contact": {
- "avatar_url": "string",
- "contact_type": "person",
- "email": [
- "string"
], - "id": "string",
- "is_viewable": true,
- "name": "string",
- "employment": {
- "company_name": "string",
- "title": "string"
}, - "phones": {
- "label": "string",
- "value": "string"
}
}, - "note": "string",
- "employments": [
- {
- "employer": {
- "avatar_url": "string",
- "contact_type": "person",
- "email": [
- "string"
], - "id": "string",
- "is_viewable": true,
- "name": "string",
- "employment": {
- "company_name": "string",
- "title": "string"
}, - "phones": {
- "label": "string",
- "value": "string"
}
}, - "start_date": "string",
- "end_date": "string",
- "title": "string"
}
]
}
], - "owner": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "fields_values": {
- "field_id": "65958d7ef2e8748e6361ddb1",
- "values": [
- {
- "value": "value_1",
- "is_primary": true
}
]
}, - "fields_values_with_names": {
- "field_name": "amount",
- "values": [
- {
- "value": "value_1",
- "is_primary": true
}
]
}, - "stage_transitions": {
- "pipeline_id": "string",
- "pipeline_color": "string",
- "pipeline_name": "string",
- "transitions": [
- {
- "from_stage": {
- "default_probability": 0,
- "stage_id": "string",
- "description": "string",
- "creator": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "created": "string",
- "updated": "string",
- "pipline_id": "string",
- "role": {
- "name": "string",
- "is_final": true
}, - "archived_at": "string",
- "expected_days": 0,
- "name": "string"
}, - "to_stage": {
- "default_probability": 0,
- "stage_id": "string",
- "description": "string",
- "creator": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "created": "string",
- "updated": "string",
- "pipline_id": "string",
- "role": {
- "name": "string",
- "is_final": true
}, - "archived_at": "string",
- "expected_days": 0,
- "name": "string"
}, - "who": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "when": "2019-08-24",
- "notes": "string"
}
], - "before_final_stage": {
- "default_probability": 0,
- "stage_id": "string",
- "description": "string",
- "creator": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "created": "string",
- "updated": "string",
- "pipline_id": "string",
- "role": {
- "name": "string",
- "is_final": true
}, - "archived_at": "string",
- "expected_days": 0,
- "name": "string"
}
}, - "files": {
- "uploader": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "uploaded_at": "string",
- "file_size": 0,
- "file_name": "string",
- "file_id": "string",
- "metadata": {
- "data_id": "string",
- "source": "uploaded_azure"
}
}, - "tags": [
- "string"
], - "final_probability": 0,
- "age_in_days": 0
}
]
}
Create a new deal_v2
owner_id | string
|
object deal's read and edit privacy | |
required | Deals.FieldsValues (object) or Deals.NamedFieldsValues (object) Fields of the deals which was filled up by the owner/creator. At leas field
To remove any field send {field_id:[]}
|
pipeline_id required | string
|
stage_id required | string
|
currency | string <ISO-4217> Currency of the deal in |
Array of objects List of Nimble contacts that take part in the deal. | |
Array of objects (Deals.RelatedExternalContact) A list with related external contacts. Similar to related_contacts, but instead of | |
tags | Array of strings |
{- "owner_id": "string",
- "privacy": {
- "read": true,
- "edit": true
}, - "fields_values": {
- "field_id": "65958d7ef2e8748e6361ddb1",
- "values": [
- {
- "value": "value_1",
- "is_primary": true
}
]
}, - "pipeline_id": "string",
- "stage_id": "string",
- "currency": "string",
- "related_contacts": [
- {
- "contact_id": "string",
- "note": "string"
}
], - "related_external_contacts": [
- {
- "contact_info": "string",
- "note": "string"
}
], - "tags": [
- "string"
]
}
{- "updated": "string",
- "deal_id": "string",
- "creator": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "related_external_contacts": [
- {
- "contact_info": "string",
- "note": "string"
}
], - "privacy": {
- "read": true,
- "edit": true
}, - "updated_by": "string",
- "created": "string",
- "is_editable": true,
- "currency": "string",
- "related_contacts": [
- {
- "contact": {
- "avatar_url": "string",
- "contact_type": "person",
- "email": [
- "string"
], - "id": "string",
- "is_viewable": true,
- "name": "string",
- "employment": {
- "company_name": "string",
- "title": "string"
}, - "phones": {
- "label": "string",
- "value": "string"
}
}, - "note": "string",
- "employments": [
- {
- "employer": {
- "avatar_url": "string",
- "contact_type": "person",
- "email": [
- "string"
], - "id": "string",
- "is_viewable": true,
- "name": "string",
- "employment": {
- "company_name": "string",
- "title": "string"
}, - "phones": {
- "label": "string",
- "value": "string"
}
}, - "start_date": "string",
- "end_date": "string",
- "title": "string"
}
]
}
], - "owner": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "fields_values": {
- "field_id": "65958d7ef2e8748e6361ddb1",
- "values": [
- {
- "value": "value_1",
- "is_primary": true
}
]
}, - "fields_values_with_names": {
- "field_name": "amount",
- "values": [
- {
- "value": "value_1",
- "is_primary": true
}
]
}, - "stage_transitions": {
- "pipeline_id": "string",
- "pipeline_color": "string",
- "pipeline_name": "string",
- "transitions": [
- {
- "from_stage": {
- "default_probability": 0,
- "stage_id": "string",
- "description": "string",
- "creator": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "created": "string",
- "updated": "string",
- "pipline_id": "string",
- "role": {
- "name": "string",
- "is_final": true
}, - "archived_at": "string",
- "expected_days": 0,
- "name": "string"
}, - "to_stage": {
- "default_probability": 0,
- "stage_id": "string",
- "description": "string",
- "creator": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "created": "string",
- "updated": "string",
- "pipline_id": "string",
- "role": {
- "name": "string",
- "is_final": true
}, - "archived_at": "string",
- "expected_days": 0,
- "name": "string"
}, - "who": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "when": "2019-08-24",
- "notes": "string"
}
], - "before_final_stage": {
- "default_probability": 0,
- "stage_id": "string",
- "description": "string",
- "creator": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "created": "string",
- "updated": "string",
- "pipline_id": "string",
- "role": {
- "name": "string",
- "is_final": true
}, - "archived_at": "string",
- "expected_days": 0,
- "name": "string"
}
}, - "files": {
- "uploader": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "uploaded_at": "string",
- "file_size": 0,
- "file_name": "string",
- "file_id": "string",
- "metadata": {
- "data_id": "string",
- "source": "uploaded_azure"
}
}, - "tags": [
- "string"
], - "final_probability": 0,
- "age_in_days": 0
}
update deals tag by name
tag_name required | string name of tag |
new_tag required | string |
{- "new_tag": "string"
}
{- "message": "You can not reopen already active deal",
- "type": "lost_contact_access"
}
delete deals tag by name
tag_name required | string name of tag |
preflight_checks | boolean Default: false check query's deals are editable |
{- "preflight_checks": false
}
{- "errors": [
- {
- "message": "Some contacts cannot be updated because of their privacy settings",
- "nse_query": {
- "and": [
- {
- "is_editable": {
- "is": false
}
}, - {
- "_id": {
- "in": [
- "5dfb9c3e84a6b90f0c01c23a",
- "5dfb9c3e84a6b90f0c01c23b"
]
}
}
]
}, - "total": 10,
- "type": "non_editable_contacts"
}
]
}
Get deal by id
deal_id required | string id of a deal to operate on |
{- "updated": "string",
- "deal_id": "string",
- "creator": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "related_external_contacts": [
- {
- "contact_info": "string",
- "note": "string"
}
], - "privacy": {
- "read": true,
- "edit": true
}, - "updated_by": "string",
- "created": "string",
- "is_editable": true,
- "currency": "string",
- "related_contacts": [
- {
- "contact": {
- "avatar_url": "string",
- "contact_type": "person",
- "email": [
- "string"
], - "id": "string",
- "is_viewable": true,
- "name": "string",
- "employment": {
- "company_name": "string",
- "title": "string"
}, - "phones": {
- "label": "string",
- "value": "string"
}
}, - "note": "string",
- "employments": [
- {
- "employer": {
- "avatar_url": "string",
- "contact_type": "person",
- "email": [
- "string"
], - "id": "string",
- "is_viewable": true,
- "name": "string",
- "employment": {
- "company_name": "string",
- "title": "string"
}, - "phones": {
- "label": "string",
- "value": "string"
}
}, - "start_date": "string",
- "end_date": "string",
- "title": "string"
}
]
}
], - "owner": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "fields_values": {
- "field_id": "65958d7ef2e8748e6361ddb1",
- "values": [
- {
- "value": "value_1",
- "is_primary": true
}
]
}, - "fields_values_with_names": {
- "field_name": "amount",
- "values": [
- {
- "value": "value_1",
- "is_primary": true
}
]
}, - "stage_transitions": {
- "pipeline_id": "string",
- "pipeline_color": "string",
- "pipeline_name": "string",
- "transitions": [
- {
- "from_stage": {
- "default_probability": 0,
- "stage_id": "string",
- "description": "string",
- "creator": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "created": "string",
- "updated": "string",
- "pipline_id": "string",
- "role": {
- "name": "string",
- "is_final": true
}, - "archived_at": "string",
- "expected_days": 0,
- "name": "string"
}, - "to_stage": {
- "default_probability": 0,
- "stage_id": "string",
- "description": "string",
- "creator": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "created": "string",
- "updated": "string",
- "pipline_id": "string",
- "role": {
- "name": "string",
- "is_final": true
}, - "archived_at": "string",
- "expected_days": 0,
- "name": "string"
}, - "who": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "when": "2019-08-24",
- "notes": "string"
}
], - "before_final_stage": {
- "default_probability": 0,
- "stage_id": "string",
- "description": "string",
- "creator": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "created": "string",
- "updated": "string",
- "pipline_id": "string",
- "role": {
- "name": "string",
- "is_final": true
}, - "archived_at": "string",
- "expected_days": 0,
- "name": "string"
}
}, - "files": {
- "uploader": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "uploaded_at": "string",
- "file_size": 0,
- "file_name": "string",
- "file_id": "string",
- "metadata": {
- "data_id": "string",
- "source": "uploaded_azure"
}
}, - "tags": [
- "string"
], - "final_probability": 0,
- "age_in_days": 0
}
Edit deal by id
deal_id required | string id of a deal to operate on |
owner_id | string
|
object deal's read and edit privacy | |
Deals.FieldsValues (object) or Deals.NamedFieldsValues (object) Fields of the deals which was filled up by the owner/creator. At leas field
To remove any field send {field_id:[]}
| |
pipeline_id | string
|
stage_id | string
|
currency | string <ISO-4217> Currency of the deal in |
Array of objects List of Nimble contacts that take part in the deal. If you want to clear contacts list, send | |
Array of objects (Deals.RelatedExternalContact) A list with related external contacts. Similar to | |
tags | Array of strings new list of deal's tags |
{- "owner_id": "5049f696a694620a0700001c",
- "privacy": {
- "read": true,
- "edit": true
}, - "fields_values": {
- "field_id": "65958d7ef2e8748e6361ddb1",
- "values": [
- {
- "value": "value_1",
- "is_primary": true
}
]
}, - "pipeline_id": "630f34cfa34058dea76c0c0e",
- "stage_id": "62fd6587048065ca3510c6d5",
- "currency": "USD",
- "related_contacts": [
- {
- "contact_id": "630c6f7bf5943b012188c778",
- "note": "Some Note Text"
}
], - "related_external_contacts": [
- {
- "contact_info": "string",
- "note": "string"
}
], - "tags": [
- "string"
]
}
{- "updated": "string",
- "deal_id": "string",
- "creator": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "related_external_contacts": [
- {
- "contact_info": "string",
- "note": "string"
}
], - "privacy": {
- "read": true,
- "edit": true
}, - "updated_by": "string",
- "created": "string",
- "is_editable": true,
- "currency": "string",
- "related_contacts": [
- {
- "contact": {
- "avatar_url": "string",
- "contact_type": "person",
- "email": [
- "string"
], - "id": "string",
- "is_viewable": true,
- "name": "string",
- "employment": {
- "company_name": "string",
- "title": "string"
}, - "phones": {
- "label": "string",
- "value": "string"
}
}, - "note": "string",
- "employments": [
- {
- "employer": {
- "avatar_url": "string",
- "contact_type": "person",
- "email": [
- "string"
], - "id": "string",
- "is_viewable": true,
- "name": "string",
- "employment": {
- "company_name": "string",
- "title": "string"
}, - "phones": {
- "label": "string",
- "value": "string"
}
}, - "start_date": "string",
- "end_date": "string",
- "title": "string"
}
]
}
], - "owner": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "fields_values": {
- "field_id": "65958d7ef2e8748e6361ddb1",
- "values": [
- {
- "value": "value_1",
- "is_primary": true
}
]
}, - "fields_values_with_names": {
- "field_name": "amount",
- "values": [
- {
- "value": "value_1",
- "is_primary": true
}
]
}, - "stage_transitions": {
- "pipeline_id": "string",
- "pipeline_color": "string",
- "pipeline_name": "string",
- "transitions": [
- {
- "from_stage": {
- "default_probability": 0,
- "stage_id": "string",
- "description": "string",
- "creator": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "created": "string",
- "updated": "string",
- "pipline_id": "string",
- "role": {
- "name": "string",
- "is_final": true
}, - "archived_at": "string",
- "expected_days": 0,
- "name": "string"
}, - "to_stage": {
- "default_probability": 0,
- "stage_id": "string",
- "description": "string",
- "creator": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "created": "string",
- "updated": "string",
- "pipline_id": "string",
- "role": {
- "name": "string",
- "is_final": true
}, - "archived_at": "string",
- "expected_days": 0,
- "name": "string"
}, - "who": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "when": "2019-08-24",
- "notes": "string"
}
], - "before_final_stage": {
- "default_probability": 0,
- "stage_id": "string",
- "description": "string",
- "creator": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "created": "string",
- "updated": "string",
- "pipline_id": "string",
- "role": {
- "name": "string",
- "is_final": true
}, - "archived_at": "string",
- "expected_days": 0,
- "name": "string"
}
}, - "files": {
- "uploader": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "uploaded_at": "string",
- "file_size": 0,
- "file_name": "string",
- "file_id": "string",
- "metadata": {
- "data_id": "string",
- "source": "uploaded_azure"
}
}, - "tags": [
- "string"
], - "final_probability": 0,
- "age_in_days": 0
}
Store a new deal file. We can store two categories of files:
Files from external sources (gdrive, dropbox, onedrive). In this scenario files are being select in the respective file picker, and the client should pass file details to this API call so the file gets stored for the deal
Files uploaded from a computer using Azure SDK.
a) To perform the upload itself, the client must first use /api/files/azure/upload (this API is the same as one
for uploading Contact Files – we just moved it to a separate endpoint since it's independent
from contact/deals/etc)
b) after the upload was completed, the client has so-called data_id
(the ID of this file in Azure Blob Storage)
c) pass the data_id
to this API so the file gets stored to the deal
deal_id required | string id of deal to which the file should be stored |
object (Deals.AzureFileMetadata) metadata for files uploaded from device using Azure JS SDK |
{- "metadata": {
- "data_id": "string",
- "source": "uploaded_azure"
}
}
Updates a file with new name. Note: only files uploaded using Azure SDK can be renamed
deal_id required | string |
file_id required | string id of a file to operate with |
new_file_name | string |
{- "new_file_name": "string"
}
Create note to the deal
deal_id required | string id of deal to which note should be attached |
title required | string [ 1 .. 256 ] characters Title of the note. |
body | string Text of the note. |
{- "title": "string",
- "body": "string"
}
{- "note_id": "string",
- "title": "string",
- "body": "string",
- "created": "2019-08-24T14:15:22Z",
- "updated": "2019-08-24T14:15:22Z",
- "creator": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}
}
Update note
deal_id required | string id of deal to which note should be attached |
note_id required | string id of note to operate with |
title | string [ 1 .. 256 ] characters Title of the note. |
body | string or null Text of the note. |
{- "title": "string",
- "body": "string"
}
{- "note_id": "string",
- "title": "string",
- "body": "string",
- "created": "2019-08-24T14:15:22Z",
- "updated": "2019-08-24T14:15:22Z",
- "creator": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}
}
Returns a feed of overdue activities for a given deals. Sorting order is time since overdue, descending
deal_id required | string |
limit | integer Indicates how many activities show per page. |
types | Array of strings List of overdue activity types to return. If not present, we'll return activities by all types. |
{- "activities": [
- {
- "activity_id": "string",
- "activity_type": {
- "archived": true,
- "can_update_definition": true,
- "can_update_lc": true,
- "logo_id": "string",
- "type_id": "string",
- "type_name": "string"
}, - "assigned_to": {
- "account_type": "string",
- "avatar_url": "string",
- "company_id": "string",
- "company_name": "string",
- "created": "2019-08-24T14:15:22Z",
- "disabled": true,
- "email": "string",
- "first_name": { },
- "is_company_owner": true,
- "is_pending": true,
- "last_active": "2019-08-24T14:15:22Z",
- "last_name": { },
- "name": "string",
- "permissions": {
- "api use": 1,
- "manage deals pipelines": 1,
- "mass delete": 1,
- "mass export": 1,
- "private deals edit": 1,
- "private deals view": 1
}, - "receive_newsletter": true,
- "has_password": true,
- "timezone": "string",
- "under_gdpr": true,
- "user_id": "string",
- "metadata": {
- "city": "string",
- "company_name": "string",
- "country": "string",
- "employees_count": 0,
- "help_tour_data": {
- "app/activities/list": 0,
- "app/b/homepage": 0,
- "app/contacts/list": 0,
- "app/contacts/view": 0,
- "app/deals/list": 0,
- "app/deals/view": 0,
- "app/groupmessages/create": 0,
- "app/messages/list": 0,
- "app/messages/view": 0,
- "app/settings/": 0,
- "app/social/list": 0,
- "contact_list_group_message": 0,
- "disabled": 0,
- "nimble_widget": 0
}, - "industry": "string",
- "phone": "string",
- "state": "string",
- "street": "string",
- "title": "string",
- "zip": "string"
}, - "email_verification_due": true
}, - "comments": [
- {
- "author": {
- "account_type": "string",
- "avatar_url": "string",
- "company_id": "string",
- "company_name": "string",
- "created": "2019-08-24T14:15:22Z",
- "disabled": true,
- "email": "string",
- "first_name": { },
- "is_company_owner": true,
- "is_pending": true,
- "last_active": "2019-08-24T14:15:22Z",
- "last_name": { },
- "name": "string",
- "permissions": {
- "api use": 1,
- "manage deals pipelines": 1,
- "mass delete": 1,
- "mass export": 1,
- "private deals edit": 1,
- "private deals view": 1
}, - "receive_newsletter": true,
- "has_password": true,
- "timezone": "string",
- "under_gdpr": true,
- "user_id": "string",
- "metadata": {
- "city": "string",
- "company_name": "string",
- "country": "string",
- "employees_count": 0,
- "help_tour_data": {
- "app/activities/list": 0,
- "app/b/homepage": 0,
- "app/contacts/list": 0,
- "app/contacts/view": 0,
- "app/deals/list": 0,
- "app/deals/view": 0,
- "app/groupmessages/create": 0,
- "app/messages/list": 0,
- "app/messages/view": 0,
- "app/settings/": 0,
- "app/social/list": 0,
- "contact_list_group_message": 0,
- "disabled": 0,
- "nimble_widget": 0
}, - "industry": "string",
- "phone": "string",
- "state": "string",
- "street": "string",
- "title": "string",
- "zip": "string"
}, - "email_verification_due": true
}, - "comment_id": "string",
- "created": "string",
- "text": "string",
- "updated": "string"
}
], - "completed_tstamp": { },
- "created": "string",
- "description": "string",
- "details": { },
- "feed_tstamp": { },
- "is_important": true,
- "name": "string",
- "owner": {
- "account_type": "string",
- "avatar_url": "string",
- "company_id": "string",
- "company_name": "string",
- "created": "2019-08-24T14:15:22Z",
- "disabled": true,
- "email": "string",
- "first_name": { },
- "is_company_owner": true,
- "is_pending": true,
- "last_active": "2019-08-24T14:15:22Z",
- "last_name": { },
- "name": "string",
- "permissions": {
- "api use": 1,
- "manage deals pipelines": 1,
- "mass delete": 1,
- "mass export": 1,
- "private deals edit": 1,
- "private deals view": 1
}, - "receive_newsletter": true,
- "has_password": true,
- "timezone": "string",
- "under_gdpr": true,
- "user_id": "string",
- "metadata": {
- "city": "string",
- "company_name": "string",
- "country": "string",
- "employees_count": 0,
- "help_tour_data": {
- "app/activities/list": 0,
- "app/b/homepage": 0,
- "app/contacts/list": 0,
- "app/contacts/view": 0,
- "app/deals/list": 0,
- "app/deals/view": 0,
- "app/groupmessages/create": 0,
- "app/messages/list": 0,
- "app/messages/view": 0,
- "app/settings/": 0,
- "app/social/list": 0,
- "contact_list_group_message": 0,
- "disabled": 0,
- "nimble_widget": 0
}, - "industry": "string",
- "phone": "string",
- "state": "string",
- "street": "string",
- "title": "string",
- "zip": "string"
}, - "email_verification_due": true
}, - "priority": "high",
- "related_contacts": [
- {
- "avatar_url": "string",
- "contact_type": "person",
- "email": [
- "string"
], - "id": "string",
- "is_viewable": true,
- "name": "string",
- "employment": {
- "company_name": "string",
- "title": "string"
}, - "phones": {
- "label": "string",
- "value": "string"
}
}
], - "related_deals": [
- {
- "amount": 0,
- "deal_id": "string",
- "subject": "string"
}
], - "new_related_deals": [
- {
- "deal_id": "string",
- "is_editable": true,
- "is_viewable": true,
- "name": "string",
- "amount": 0
}
], - "scheduled_tstamp": { },
- "tags": [
- "string"
]
}
]
}
Returns a list of columns and column groups for the user who making the request
{- "items": {
- "columns": [
- {
- "id": "string",
- "human_readable_name": "string",
- "json_path": "string",
- "value_json_path": "string",
- "presentation": {
- "type": "single-line-text-box",
- "possible_values": {
- "ordering_type": "ordinal",
- "values": [
- {
- "id": "string",
- "value": "string"
}
]
}
}, - "read_only": true,
- "is_standard": true,
- "sortable": true
}
], - "group_id": "string",
- "human_readable_name": "string"
}, - "type": [ ]
}
Retrieves list of deal fields for this user (standard) and fields for each pipeline
{- "pipelines_tabs": [
- {
- "tab_id": "string",
- "tab_name": "string",
- "pipeline_id": "string",
- "members": {
- "type": "string",
- "field": {
- "field_id": "string",
- "modifier": "string",
- "multiples": true,
- "available_actions": "string",
- "field_type": "string",
- "field_name": "string"
}, - "pipeline_id": "string"
}
}
], - "standard_fields": [
- {
- "field_id": "string",
- "modifier": "string",
- "multiples": true,
- "available_actions": "string",
- "field_type": "string",
- "field_name": "string"
}
]
}
{- "pipelines": [
- {
- "pipeline_id": "string",
- "creator": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "name": "string",
- "description": "string",
- "created": "string",
- "updated": "string",
- "archived_at": "string",
- "stages": [
- {
- "default_probability": 0,
- "stage_id": "string",
- "description": "string",
- "creator": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "created": "string",
- "updated": "string",
- "pipline_id": "string",
- "role": {
- "name": "string",
- "is_final": true
}, - "archived_at": "string",
- "expected_days": 0,
- "name": "string"
}
], - "color": "string",
- "lost_reasons": [
- {
- "id": "string",
- "text": "string"
}
], - "is_default": true,
- "default_currency": "string",
- "tabs": [
- {
- "tab_id": "string",
- "tab_name": "string",
- "pipeline_id": "string",
- "members": {
- "type": "string",
- "field": {
- "field_id": "string",
- "modifier": "string",
- "multiples": true,
- "available_actions": "string",
- "field_type": "string",
- "field_name": "string"
}, - "pipeline_id": "string"
}
}
]
}
]
}
Create new pipeline
name required | string [ 1 .. 200 ] characters Name of new pipeline |
description required | string <= 256 characters |
color required | string |
lost_reasons required | Array of strings[ items <= 256 characters ] Default: [] |
required | Array of objects (Pipeline.CreateDealStageRequest) Default: [] |
required | Array of Pipeline.CreateDealsPipelineGroupRequest (object) or Pipeline.CreateDealsPipelineFieldRequest (object) |
default_currency required | string <ISO-4217> |
{- "name": "string",
- "description": "string",
- "color": "string",
- "lost_reasons": [ ],
- "stages": [ ],
- "fields_tab_members": [
- {
- "group_name": "string",
- "logo_id": "string",
- "insert_after": "string",
- "fields": [
- {
- "name": "string",
- "field_type": {
- "field_kind": "string",
- "validation_rule": "email"
}, - "presentation": {
- "number_type": "integer"
}, - "pipeline_id": "string",
- "insert_after": "string",
- "group_id": "string"
}
]
}
], - "default_currency": "string"
}
{- "pipeline_id": "string",
- "creator": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "name": "string",
- "description": "string",
- "created": "string",
- "updated": "string",
- "archived_at": "string",
- "stages": [
- {
- "default_probability": 0,
- "stage_id": "string",
- "description": "string",
- "creator": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "created": "string",
- "updated": "string",
- "pipline_id": "string",
- "role": {
- "name": "string",
- "is_final": true
}, - "archived_at": "string",
- "expected_days": 0,
- "name": "string"
}
], - "color": "string",
- "lost_reasons": [
- {
- "id": "string",
- "text": "string"
}
], - "is_default": true,
- "default_currency": "string",
- "tabs": [
- {
- "tab_id": "string",
- "tab_name": "string",
- "pipeline_id": "string",
- "members": {
- "type": "string",
- "field": {
- "field_id": "string",
- "modifier": "string",
- "multiples": true,
- "available_actions": "string",
- "field_type": "string",
- "field_name": "string"
}, - "pipeline_id": "string"
}
}
]
}
Get pipeline by id
pipeline_id required | string <ObjectId> Id of pipeline to operate with |
{- "pipeline_id": "string",
- "creator": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "name": "string",
- "description": "string",
- "created": "string",
- "updated": "string",
- "archived_at": "string",
- "stages": [
- {
- "default_probability": 0,
- "stage_id": "string",
- "description": "string",
- "creator": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "created": "string",
- "updated": "string",
- "pipline_id": "string",
- "role": {
- "name": "string",
- "is_final": true
}, - "archived_at": "string",
- "expected_days": 0,
- "name": "string"
}
], - "color": "string",
- "lost_reasons": [
- {
- "id": "string",
- "text": "string"
}
], - "is_default": true,
- "default_currency": "string",
- "tabs": [
- {
- "tab_id": "string",
- "tab_name": "string",
- "pipeline_id": "string",
- "members": {
- "type": "string",
- "field": {
- "field_id": "string",
- "modifier": "string",
- "multiples": true,
- "available_actions": "string",
- "field_type": "string",
- "field_name": "string"
}, - "pipeline_id": "string"
}
}
]
}
Update pipeline by id
pipeline_id required | string <ObjectId> Id of pipeline to operate with |
name | string [ 1 .. 200 ] characters New pipeline name |
description | string New pipeline description |
color | string New pipeline color |
{- "name": "string",
- "description": "string",
- "color": "string"
}
{- "pipeline_id": "string",
- "creator": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "name": "string",
- "description": "string",
- "created": "string",
- "updated": "string",
- "archived_at": "string",
- "stages": [
- {
- "default_probability": 0,
- "stage_id": "string",
- "description": "string",
- "creator": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "created": "string",
- "updated": "string",
- "pipline_id": "string",
- "role": {
- "name": "string",
- "is_final": true
}, - "archived_at": "string",
- "expected_days": 0,
- "name": "string"
}
], - "color": "string",
- "lost_reasons": [
- {
- "id": "string",
- "text": "string"
}
], - "is_default": true,
- "default_currency": "string",
- "tabs": [
- {
- "tab_id": "string",
- "tab_name": "string",
- "pipeline_id": "string",
- "members": {
- "type": "string",
- "field": {
- "field_id": "string",
- "modifier": "string",
- "multiples": true,
- "available_actions": "string",
- "field_type": "string",
- "field_name": "string"
}, - "pipeline_id": "string"
}
}
]
}
Delete the pipeline by its id. All deals in this pipelines will also be deleted!
pipeline_id required | string <ObjectId> Id of pipeline to operate with |
{- "message": "You don't have access to this deal"
}
Get deals in pipeline listing separated by stages
pipeline_id required | string <ObjectId> id of pipeline to get listing for |
sort required | string <field:order> Example: sort=name:asc parameter to sort by |
limit | integer Default: 10 Example: limit=30 limit of deals per page |
query | string unparsed NSE search query |
stage_id | string <ObjectId> id of stage to get info about |
{- "stages": [
- {
- "deals": [
- {
- "updated": "string",
- "deal_id": "string",
- "creator": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "related_external_contacts": [
- {
- "contact_info": "string",
- "note": "string"
}
], - "privacy": {
- "read": true,
- "edit": true
}, - "updated_by": "string",
- "created": "string",
- "is_editable": true,
- "currency": "string",
- "related_contacts": [
- {
- "contact": {
- "avatar_url": "string",
- "contact_type": "person",
- "email": [
- "string"
], - "id": "string",
- "is_viewable": true,
- "name": "string",
- "employment": {
- "company_name": "string",
- "title": "string"
}, - "phones": {
- "label": "string",
- "value": "string"
}
}, - "note": "string",
- "employments": [
- {
- "employer": {
- "avatar_url": null,
- "contact_type": null,
- "email": [ ],
- "id": null,
- "is_viewable": null,
- "name": null,
- "employment": { },
- "phones": { }
}, - "start_date": "string",
- "end_date": "string",
- "title": "string"
}
]
}
], - "owner": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "fields_values": {
- "field_id": "65958d7ef2e8748e6361ddb1",
- "values": [
- {
- "value": "value_1",
- "is_primary": true
}
]
}, - "fields_values_with_names": {
- "field_name": "amount",
- "values": [
- {
- "value": "value_1",
- "is_primary": true
}
]
}, - "stage_transitions": {
- "pipeline_id": "string",
- "pipeline_color": "string",
- "pipeline_name": "string",
- "transitions": [
- {
- "from_stage": {
- "default_probability": 0,
- "stage_id": "string",
- "description": "string",
- "creator": {
- "avatar_url": null,
- "email": null,
- "is_active": null,
- "name": null,
- "user_id": null
}, - "created": "string",
- "updated": "string",
- "pipline_id": "string",
- "role": {
- "name": null,
- "is_final": null
}, - "archived_at": "string",
- "expected_days": 0,
- "name": "string"
}, - "to_stage": {
- "default_probability": 0,
- "stage_id": "string",
- "description": "string",
- "creator": {
- "avatar_url": null,
- "email": null,
- "is_active": null,
- "name": null,
- "user_id": null
}, - "created": "string",
- "updated": "string",
- "pipline_id": "string",
- "role": {
- "name": null,
- "is_final": null
}, - "archived_at": "string",
- "expected_days": 0,
- "name": "string"
}, - "who": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "when": "2019-08-24",
- "notes": "string"
}
], - "before_final_stage": {
- "default_probability": 0,
- "stage_id": "string",
- "description": "string",
- "creator": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "created": "string",
- "updated": "string",
- "pipline_id": "string",
- "role": {
- "name": "string",
- "is_final": true
}, - "archived_at": "string",
- "expected_days": 0,
- "name": "string"
}
}, - "files": {
- "uploader": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "uploaded_at": "string",
- "file_size": 0,
- "file_name": "string",
- "file_id": "string",
- "metadata": {
- "data_id": "string",
- "source": "uploaded_azure"
}
}, - "tags": [
- "string"
], - "final_probability": 0,
- "age_in_days": 0
}
], - "stage": {
- "default_probability": 0,
- "stage_id": "string",
- "description": "string",
- "creator": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "created": "string",
- "updated": "string",
- "pipline_id": "string",
- "role": {
- "name": "string",
- "is_final": true
}, - "archived_at": "string",
- "expected_days": 0,
- "name": "string"
}, - "meta": {
- "total_new_count": 0,
- "next_page_url": "string",
- "total_amount": [
- {
- "currency": "string",
- "count": 0
}
]
}
}
]
}
Get deals in pipeline listing separated by owners
pipeline_id required | string <ObjectId> id of pipeline to get listing for |
sort required | string <field:order> Example: sort=name:asc parameter to sort by |
limit | integer Default: 10 Example: limit=30 limit of deals per page |
query | string unparsed NSE search query |
{- "groups": [
- {
- "deals": [
- {
- "updated": "string",
- "deal_id": "string",
- "creator": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "related_external_contacts": [
- {
- "contact_info": "string",
- "note": "string"
}
], - "privacy": {
- "read": true,
- "edit": true
}, - "updated_by": "string",
- "created": "string",
- "is_editable": true,
- "currency": "string",
- "related_contacts": [
- {
- "contact": {
- "avatar_url": "string",
- "contact_type": "person",
- "email": [
- "string"
], - "id": "string",
- "is_viewable": true,
- "name": "string",
- "employment": {
- "company_name": "string",
- "title": "string"
}, - "phones": {
- "label": "string",
- "value": "string"
}
}, - "note": "string",
- "employments": [
- {
- "employer": {
- "avatar_url": null,
- "contact_type": null,
- "email": [ ],
- "id": null,
- "is_viewable": null,
- "name": null,
- "employment": { },
- "phones": { }
}, - "start_date": "string",
- "end_date": "string",
- "title": "string"
}
]
}
], - "owner": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "fields_values": {
- "field_id": "65958d7ef2e8748e6361ddb1",
- "values": [
- {
- "value": "value_1",
- "is_primary": true
}
]
}, - "fields_values_with_names": {
- "field_name": "amount",
- "values": [
- {
- "value": "value_1",
- "is_primary": true
}
]
}, - "stage_transitions": {
- "pipeline_id": "string",
- "pipeline_color": "string",
- "pipeline_name": "string",
- "transitions": [
- {
- "from_stage": {
- "default_probability": 0,
- "stage_id": "string",
- "description": "string",
- "creator": {
- "avatar_url": null,
- "email": null,
- "is_active": null,
- "name": null,
- "user_id": null
}, - "created": "string",
- "updated": "string",
- "pipline_id": "string",
- "role": {
- "name": null,
- "is_final": null
}, - "archived_at": "string",
- "expected_days": 0,
- "name": "string"
}, - "to_stage": {
- "default_probability": 0,
- "stage_id": "string",
- "description": "string",
- "creator": {
- "avatar_url": null,
- "email": null,
- "is_active": null,
- "name": null,
- "user_id": null
}, - "created": "string",
- "updated": "string",
- "pipline_id": "string",
- "role": {
- "name": null,
- "is_final": null
}, - "archived_at": "string",
- "expected_days": 0,
- "name": "string"
}, - "who": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "when": "2019-08-24",
- "notes": "string"
}
], - "before_final_stage": {
- "default_probability": 0,
- "stage_id": "string",
- "description": "string",
- "creator": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "created": "string",
- "updated": "string",
- "pipline_id": "string",
- "role": {
- "name": "string",
- "is_final": true
}, - "archived_at": "string",
- "expected_days": 0,
- "name": "string"
}
}, - "files": {
- "uploader": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "uploaded_at": "string",
- "file_size": 0,
- "file_name": "string",
- "file_id": "string",
- "metadata": {
- "data_id": "string",
- "source": "uploaded_azure"
}
}, - "tags": [
- "string"
], - "final_probability": 0,
- "age_in_days": 0
}
], - "owner": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "meta": {
- "next_page_url": "string",
- "total_amount": [
- {
- "currency": "string",
- "count": 0
}
]
}
}
]
}
Add lost reason to pipeline
pipeline_id required | string <ObjectId> id of pipeline where reason is |
reason required | string Reason description |
{- "reason": "string"
}
{- "pipeline_id": "string",
- "creator": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "name": "string",
- "description": "string",
- "created": "string",
- "updated": "string",
- "archived_at": "string",
- "stages": [
- {
- "default_probability": 0,
- "stage_id": "string",
- "description": "string",
- "creator": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "created": "string",
- "updated": "string",
- "pipline_id": "string",
- "role": {
- "name": "string",
- "is_final": true
}, - "archived_at": "string",
- "expected_days": 0,
- "name": "string"
}
], - "color": "string",
- "lost_reasons": [
- {
- "id": "string",
- "text": "string"
}
], - "is_default": true,
- "default_currency": "string",
- "tabs": [
- {
- "tab_id": "string",
- "tab_name": "string",
- "pipeline_id": "string",
- "members": {
- "type": "string",
- "field": {
- "field_id": "string",
- "modifier": "string",
- "multiples": true,
- "available_actions": "string",
- "field_type": "string",
- "field_name": "string"
}, - "pipeline_id": "string"
}
}
]
}
Create deal stage
pipeline_id required | string <ObjectId> id of pipeline to manipulate with |
name | string Name of the stage |
description | string Stage description |
pipeline_id | string <ObjectId> Id of the pipeline where stage should be |
insert_after | string <ObjectId> Id of the stage that should be positioned before this new stage |
expected_days | number >= 0 Expected day before stage complete |
default_probability | number [ 0 .. 100 ] Default probability for all deals in this stage (will be deal probability if one doesn't have its own) |
{- "name": "string",
- "description": "string",
- "pipeline_id": "string",
- "insert_after": "string",
- "expected_days": 0,
- "default_probability": 100
}
{- "pipeline_id": "string",
- "creator": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "name": "string",
- "description": "string",
- "created": "string",
- "updated": "string",
- "archived_at": "string",
- "stages": [
- {
- "default_probability": 0,
- "stage_id": "string",
- "description": "string",
- "creator": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "created": "string",
- "updated": "string",
- "pipline_id": "string",
- "role": {
- "name": "string",
- "is_final": true
}, - "archived_at": "string",
- "expected_days": 0,
- "name": "string"
}
], - "color": "string",
- "lost_reasons": [
- {
- "id": "string",
- "text": "string"
}
], - "is_default": true,
- "default_currency": "string",
- "tabs": [
- {
- "tab_id": "string",
- "tab_name": "string",
- "pipeline_id": "string",
- "members": {
- "type": "string",
- "field": {
- "field_id": "string",
- "modifier": "string",
- "multiples": true,
- "available_actions": "string",
- "field_type": "string",
- "field_name": "string"
}, - "pipeline_id": "string"
}
}
]
}
Update stage
pipeline_id required | string <ObjectId> id of pipeline to manipulate with |
stage_id required | string <ObjectId> id of stage to manipulate with |
name | string [ 1 .. 4096 ] characters Stage name |
description | string or null [ 1 .. 4096 ] characters Stage description |
expected_days | integer The number of days a deal is expected to spend at this stage |
default_probability | integer [ 0 .. 100 ] Stage default probability. Will be assigned to all deals in stage if they don't have their own |
{- "name": "string",
- "description": "string",
- "expected_days": 0,
- "default_probability": 100
}
{- "pipeline_id": "string",
- "creator": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "name": "string",
- "description": "string",
- "created": "string",
- "updated": "string",
- "archived_at": "string",
- "stages": [
- {
- "default_probability": 0,
- "stage_id": "string",
- "description": "string",
- "creator": {
- "avatar_url": "string",
- "email": "string",
- "is_active": true,
- "name": "string",
- "user_id": "string"
}, - "created": "string",
- "updated": "string",
- "pipline_id": "string",
- "role": {
- "name": "string",
- "is_final": true
}, - "archived_at": "string",
- "expected_days": 0,
- "name": "string"
}
], - "color": "string",
- "lost_reasons": [
- {
- "id": "string",
- "text": "string"
}
], - "is_default": true,
- "default_currency": "string",
- "tabs": [
- {
- "tab_id": "string",
- "tab_name": "string",
- "pipeline_id": "string",
- "members": {
- "type": "string",
- "field": {
- "field_id": "string",
- "modifier": "string",
- "multiples": true,
- "available_actions": "string",
- "field_type": "string",
- "field_name": "string"
}, - "pipeline_id": "string"
}
}
]
}
Creates custom field in pipeline
pipeline_id required | string
|
name required | string Name of the new field |
required | Pipeline.StringFieldValuesType (object) or Pipeline.LongStringFieldValuesType (object) or Pipeline.ChoiceFieldValuesType (object) or Pipeline.NumberFieldValuesType (object) or Pipeline.DateTimeFieldValuesType (object) or Pipeline.BooleanFieldValuesType (object) or Pipeline.AddressFieldValuesType (object) or Pipeline.UserFieldValuesType (object) (Pipeline.FieldTypeOnFieldCreation) |
required | Fields.IntegerNumberPresentation (object) or Fields.DecimalNumberPresentation (object) or Fields.PercentageNumberPresentation (object) or Fields.FinancialNumberPresentation (object) or Fields.DateTimePresentation (object) (Fields.FieldPresentation) how values of the field should look. Must match to corresponding field_type. Date and number fields must have an appropriate presentation. There is no presentation for other types |
pipeline_id | string or null
|
insert_after | string or null Inserts a new field after field or group with specified |
group_id | string
|
{- "name": "string",
- "field_type": {
- "field_kind": "string",
- "validation_rule": "email"
}, - "presentation": {
- "number_type": "integer"
}, - "pipeline_id": "string",
- "insert_after": "string",
- "group_id": "string"
}
{- "pipelines_tabs": [
- {
- "tab_id": "string",
- "tab_name": "string",
- "pipeline_id": "string",
- "members": {
- "type": "string",
- "field": {
- "field_id": "string",
- "modifier": "string",
- "multiples": true,
- "available_actions": "string",
- "field_type": "string",
- "field_name": "string"
}, - "pipeline_id": "string"
}
}
], - "standard_fields": [
- {
- "field_id": "string",
- "modifier": "string",
- "multiples": true,
- "available_actions": "string",
- "field_type": "string",
- "field_name": "string"
}
]
}
Updates custom field in pipeline
pipeline_id required | string
|
field_id required | string
|
name | string Name of the new field |
Fields.IntegerNumberPresentation (object) or Fields.DecimalNumberPresentation (object) or Fields.PercentageNumberPresentation (object) or Fields.FinancialNumberPresentation (object) or Fields.DateTimePresentation (object) (Fields.FieldPresentation) how values of the field should look. Must match to corresponding field_type. Date and number fields must have an appropriate presentation. There is no presentation for other types | |
insert_after | string or null Inserts a new field after field or group with specified |
group_id | string or null <ObjectId> id of group where field will be located or |
{- "name": "string",
- "presentation": {
- "number_type": "integer"
}, - "insert_after": "string",
- "group_id": "string"
}
{- "pipelines_tabs": [
- {
- "tab_id": "string",
- "tab_name": "string",
- "pipeline_id": "string",
- "members": {
- "type": "string",
- "field": {
- "field_id": "string",
- "modifier": "string",
- "multiples": true,
- "available_actions": "string",
- "field_type": "string",
- "field_name": "string"
}, - "pipeline_id": "string"
}
}
], - "standard_fields": [
- {
- "field_id": "string",
- "modifier": "string",
- "multiples": true,
- "available_actions": "string",
- "field_type": "string",
- "field_name": "string"
}
]
}
Deletes custom field from pipeline
pipeline_id required | string
|
field_id required | string
|
preflight_checks | boolean if true and there are deals using this field - will return an error; if false - will delete the field and its possible values in deals |
{- "preflight_checks": true
}
{- "message": "You don't have access to this deal"
}
Creates choice in specified pipeline field
pipeline_id required | string
|
field_id required | string
|
required | object New choice |
insert_after | string or null Move choice after choice with specified id. If |
{- "choice": {
- "id": "string",
- "value": "string"
}, - "insert_after": "string"
}
{- "pipelines_tabs": [
- {
- "tab_id": "string",
- "tab_name": "string",
- "pipeline_id": "string",
- "members": {
- "type": "string",
- "field": {
- "field_id": "string",
- "modifier": "string",
- "multiples": true,
- "available_actions": "string",
- "field_type": "string",
- "field_name": "string"
}, - "pipeline_id": "string"
}
}
], - "standard_fields": [
- {
- "field_id": "string",
- "modifier": "string",
- "multiples": true,
- "available_actions": "string",
- "field_type": "string",
- "field_name": "string"
}
]
}
Updates choice in custom field in pipeline
pipeline_id required | string
|
field_id required | string
|
choice_id required | string
|
value | string or null New choice value |
insert_after | string or null Move choice after choice with specified id. If |
{- "value": "string",
- "insert_after": "string"
}
{- "pipelines_tabs": [
- {
- "tab_id": "string",
- "tab_name": "string",
- "pipeline_id": "string",
- "members": {
- "type": "string",
- "field": {
- "field_id": "string",
- "modifier": "string",
- "multiples": true,
- "available_actions": "string",
- "field_type": "string",
- "field_name": "string"
}, - "pipeline_id": "string"
}
}
], - "standard_fields": [
- {
- "field_id": "string",
- "modifier": "string",
- "multiples": true,
- "available_actions": "string",
- "field_type": "string",
- "field_name": "string"
}
]
}
Deletes choice from custom field
pipeline_id required | string
|
field_id required | string
|
choice_id required | string
|
preflight_checks | boolean if true and there are deals using this particular choice - will return an error; if false - will delete the choice and the value of this choice in all deals |
{- "preflight_checks": true
}
{- "message": "You don't have access to this deal"
}
Create pipeline deal group
pipeline_id required | string <ObjectId> id of pipeline to manipulate with |
group_name | string |
logo_id | string |
insert_after | string or null If not null, inserts a new group after another group or field with specified id. If null, then group is inserted as the first one |
Array of objects (Pipeline.CreateDealsPipelineFieldRequest) |
{- "group_name": "string",
- "logo_id": "string",
- "insert_after": "string",
- "fields": [
- {
- "name": "string",
- "field_type": {
- "field_kind": "string",
- "validation_rule": "email"
}, - "presentation": {
- "number_type": "integer"
}, - "pipeline_id": "string",
- "insert_after": "string",
- "group_id": "string"
}
]
}
{- "pipelines_tabs": [
- {
- "tab_id": "string",
- "tab_name": "string",
- "pipeline_id": "string",
- "members": {
- "type": "string",
- "field": {
- "field_id": "string",
- "modifier": "string",
- "multiples": true,
- "available_actions": "string",
- "field_type": "string",
- "field_name": "string"
}, - "pipeline_id": "string"
}
}
], - "standard_fields": [
- {
- "field_id": "string",
- "modifier": "string",
- "multiples": true,
- "available_actions": "string",
- "field_type": "string",
- "field_name": "string"
}
]
}
Update pipeline deal group
pipeline_id required | string id of group to manipulate with |
group_id required | string id of group to update |
group_name | string |
logo_id | string |
insert_after | string move group after another group or field with specified id |
{- "group_name": "string",
- "logo_id": "string",
- "insert_after": "string"
}
{- "pipelines_tabs": [
- {
- "tab_id": "string",
- "tab_name": "string",
- "pipeline_id": "string",
- "members": {
- "type": "string",
- "field": {
- "field_id": "string",
- "modifier": "string",
- "multiples": true,
- "available_actions": "string",
- "field_type": "string",
- "field_name": "string"
}, - "pipeline_id": "string"
}
}
], - "standard_fields": [
- {
- "field_id": "string",
- "modifier": "string",
- "multiples": true,
- "available_actions": "string",
- "field_type": "string",
- "field_name": "string"
}
]
}
Delete pipeline deal group
pipeline_id required | string id of pipeline to delete group from |
group_id required | string id of group to delete |
{- "message": "You don't have access to this deal"
}