openapi: 3.0.0
servers:
- url: https://app.nimble.com
info:
title: Nimble API
version: v1
description: "# Overview\n\nNimble 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. \n\nThe 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 [api-support@nimble.com](mailto:api-support@nimble.com).\n\nCurrently available APIs:\n\
\n- **Contacts & Contact fields** - managing contacts & custom fields.\n- **Deals & Deals Pipelines**\
\ - managing deals, pipelines, and deal pipeline fields. \n- **Messages** - reading and creating\
\ draft messages.\n\nWe are building the API with a few main use cases in mind:\nwidgets/extensions\
\ to Nimble, web clients (including our own), mobile\nclients, and 2-way data integrations with other\
\ services. We\naim to make an API that is simple to use, easy to read, and flexible.\n\n[Your feedback](mailto:api-support@nimble.com)\
\ is greatly\nappreciated while we continue to shape our API offering.\n"
x-logo:
url: https://www.nimble.com/wp-content/themes/new_nimble/images/nimble-logo-white.svg
backgroundColor: '#2685c4'
components:
securitySchemes:
ApiKey:
type: apiKey
in: header
name: X-Nimble-Token
schemas:
Contacts.ContactViewContextKinds:
enum:
- last_contacted_data
- employers_data
- leads_data
- sequences_data
- contact_files
Commons.PaginationMeta:
properties:
page:
type: integer
pages:
type: integer
per_page:
type: integer
total:
type: integer
required:
- page
- pages
- per_page
- total
type: object
Contacts.LastContacted:
properties:
deletion_tstamp:
type: object
object_id:
type: object
tstamp:
type: object
type:
type: object
user_id:
type: object
direction:
enum:
- inbound
- outbound
required:
- tstamp
- type
- object_id
- user_id
- deletion_tstamp
type: object
Contacts.LastContactedDirectedContainer:
properties:
in:
$ref: '#/components/schemas/Contacts.LastContacted'
out:
$ref: '#/components/schemas/Contacts.LastContacted'
last:
$ref: '#/components/schemas/Contacts.LastContacted'
Accounts.ShortUserInfo:
properties:
avatar_url:
type: string
email:
type: string
is_active:
type: boolean
name:
type: string
user_id:
type: string
required:
- user_id
- name
- email
- avatar_url
- is_active
type: object
Contacts.UserLastContactedView:
properties:
company_lc:
$ref: '#/components/schemas/Contacts.LastContactedDirectedContainer'
user_lc:
$ref: '#/components/schemas/Contacts.LastContactedDirectedContainer'
last_user:
$ref: '#/components/schemas/Accounts.ShortUserInfo'
Contacts.Principals:
description: |
Explicitly defines users and groups that have an action permission. If any set - no one can.
properties:
group_ids:
description: ids of permitted groups. if empty - no group has permission
items:
type: string
type: array
user_ids:
description: ids of permitted users. If empty - no user has permission
items:
type: string
type: array
required:
- user_ids
- group_ids
type: object
Contacts.ContactPrivacy:
description: "Defines scopes of object visibility and editability.
\nEdit permission means that\
\ group or user also is able to read an object.
\n***No duplication***, if `id` in edit Principal\
\ it must not be in view Principal.
\nIf property is `None` - everyone have an action right\
\ (Permitted to everyone).
\nIf Principal is set, but has empty properies - only owner is allowed\
\ to act.
\nIf not specified - default privacy from company settings will be applied "
properties:
edit:
description: None means permitted to everyone. Prinipals object define permission explicitly
nullable: true
type: object
oneOf:
- $ref: '#/components/schemas/Contacts.Principals'
read:
description: None means permitted to everyone. Prinipals object define permission explicitly
nullable: true
type: object
oneOf:
- $ref: '#/components/schemas/Contacts.Principals'
required:
- read
- edit
type: object
Contacts.ContactType:
enum:
- person
- company
type: string
Contacts.Reminder:
properties:
active:
type: boolean
contact_id:
type: string
days_till_triggered:
type: integer
period:
type: integer
triggered:
type: boolean
required:
- contact_id
- period
- days_till_triggered
- active
- triggered
type: object
Contacts.LeadInStageInfo:
description: info about stage where lead is
properties:
pipeline_id:
type: string
format: ObjectId
pipeline_name:
type: string
stage_name:
type: string
entered_data:
type: string
format: datetime
is_final:
type: boolean
days_limit:
type: integer
nullable: true
Contacts.ContactNotice:
properties:
created:
description: Date and time when the notice was created encoded in ISO 8601
type: string
updated:
description: Date and time when the notice was updated encoded in ISO 8601
type: string
creator:
$ref: '#/components/schemas/Accounts.ShortUserInfo'
updated_by:
$ref: '#/components/schemas/Accounts.ShortUserInfo'
text:
type: string
color:
type: string
required:
- created
- updated
- creator
- updated_by
- text
- color
type: object
Contacts.LastContactedDataContext:
type: object
properties:
context_key:
type: object
context:
$ref: '#/components/schemas/Contacts.UserLastContactedView'
Contacts.EmployerInfo:
description: employer's info
type: object
properties:
contact_id:
type: string
company_name:
type: string
avatar_url:
type: string
Contacts.EmployersDataContext:
type: object
properties:
context_key:
type: object
context:
type: array
items:
$ref: '#/components/schemas/Contacts.EmployerInfo'
Contacts.LeadsDataContext:
type: object
properties:
context_key:
type: object
context:
type: array
items:
$ref: '#/components/schemas/Contacts.LeadInStageInfo'
Contacts.UploadedContactFile:
type: object
properties:
file_id:
type: string
contact_id:
type: string
file_name:
type: string
file_size:
type: number
mime_type:
type: string
uploader:
$ref: '#/components/schemas/Accounts.ShortUserInfo'
uploaded_at:
type: string
pipeline_ids:
type: array
items:
type: string
Attachments.AttachmentData:
discriminator:
propertyName: type
properties:
attachment_bytes:
type: integer
attachment_type:
type: string
icon:
type: string
link:
description: URL that can be used to download an attachment
type: string
mime_type:
type: string
name:
type: string
type:
type: string
updated:
type: string
updated_by:
type: string
required:
- attachment_type
- name
- link
- attachment_bytes
- icon
- type
- mime_type
- updated
- updated_by
type: object
Attachments.DropboxAttachmentData:
allOf:
- $ref: '#/components/schemas/Attachments.AttachmentData'
- description: Dropbox
Attachments.GoogleDriveAttachmentData:
allOf:
- $ref: '#/components/schemas/Attachments.AttachmentData'
- description: GoogleDrive
Attachments.OneDriveAttachmentData:
allOf:
- $ref: '#/components/schemas/Attachments.AttachmentData'
- description: OneDrive
Contacts.ContactFile:
type: object
properties:
source:
type: string
enum:
- device
- google_drive
- one_drive
- dropbox
metadata:
oneOf:
- $ref: '#/components/schemas/Contacts.UploadedContactFile'
- $ref: '#/components/schemas/Attachments.DropboxAttachmentData'
- $ref: '#/components/schemas/Attachments.GoogleDriveAttachmentData'
- $ref: '#/components/schemas/Attachments.OneDriveAttachmentData'
Contacts.ContactFilesContext:
type: object
properties:
context_key:
type: object
context:
type: array
items:
$ref: '#/components/schemas/Contacts.ContactFile'
Sequences.CompletedSequenceStepRecord:
type: object
properties:
step_id:
type: string
description: ID (name) of the completed sequence step
step_type:
description: the type of the completed sequence step
enum:
- delay
- send_message
- condition
when:
type: string
description: iso8601 timestamp of when the step was completed
step_name:
type: string
description: the name of a step this contact completed
Sequences.SequenceProgressionOutcomes:
enum:
- successful
- unsuccessful
- error
- removed
Sequences.InSequenceContactExitDetails:
type: object
properties:
when:
type: string
exit_method:
type: string
description: |
"how" the contact exited the sequence (e.g. by an exit rule or certain message condition)
outcome:
$ref: '#/components/schemas/Sequences.SequenceProgressionOutcomes'
Sequences.InSequenceContactInfo:
type: object
properties:
sequence_id:
description: id of a sequence this contact is in
type: string
seq_contact_id:
description: a unique identifier of a the contact in the sequence
type: string
sequence_name:
description: the name of a sequence this contact belongs to
type: string
sequence_color:
description: the color of a sequence this contact belongs to
type: string
completed_steps:
type: array
items:
$ref: '#/components/schemas/Sequences.CompletedSequenceStepRecord'
current_step:
type: string
description: current sequence's step name
current_step_id:
type: string
description: current sequence's step id
last_completed_action:
type: string
description: last completed sequence action name
last_completed_action_dao:
type: string
description: last completed sequence action date
has_waited_in_current_step:
type: number
description: for how many seconds the contact has waited in it's current step
email:
description: an email address the contact was entered the sequence with
type: string
exit_details:
description: exit details if contact completed the sequence
nullable: true
type: object
oneOf:
- $ref: '#/components/schemas/Sequences.InSequenceContactExitDetails'
owner:
description: user who entered this contact to a sequence
oneOf:
- $ref: '#/components/schemas/Accounts.ShortUserInfo'
next_step_scheduled_at:
description: |
the timestamp of the next scheduled sequence step (can be use to approximate the next send_message step)
type: string
Contacts.InSequenceContactInfoContext:
type: object
properties:
context_key:
type: object
context:
type: array
items:
$ref: '#/components/schemas/Sequences.InSequenceContactInfo'
Messages.Attachment:
properties:
content_type:
description: MIME type of attachment
type: string
data_id:
description: Field data_id must be first retrieved using any sort of Uploads API.
type: string
file_size:
description: Field file_size is given in bytes.
type: integer
name:
type: string
url:
description: URL that can be used by a user to download attachment's content
type: string
required:
- data_id
- file_size
- content_type
- name
- url
type: object
Messages.MessagingAccountIdentifier:
properties:
account_type:
enum:
- email
- mass_mail
type: string
identifier:
description: 'Account identifier specific to account_type. For account_type: email it should
be email address. '
type: string
required:
- account_type
- identifier
type: object
Messages.MessagingAccount:
allOf:
- $ref: '#/components/schemas/Messages.MessagingAccountIdentifier'
properties:
avatar_url:
nullable: true
type: string
comment:
description: |
Field comment holds some short freeform text that shows a role of this messaging account to user.
Examples are 'home', 'work', 'assistant', etc.
type: string
company:
description: Name of account's company, might be null.
type: object
company_id:
description: ID of account's company in Nimble db, might be null.
nullable: true
type: object
contact_id:
description: Nimble contact id associated with this account
nullable: true
type: string
format: ObjectId
user_id:
description: Nimble user id (user themself or team member) associated with this account
nullable: true
type: string
format: ObjectId
name:
description: Field name is for readable name of a user. Sometimes identifier value is not suitable
to be shown to user, for example when it's numerical user id (as for Facebook). Can be null
if full name is unknown.
oneOf:
- type: number
- type: string
type: object
Messages.MessageTemplateContentMode:
type: string
enum:
- standard
- builder
- custom_html
Messages.MessageTemplateContentSpecification:
properties:
attachments:
items:
$ref: '#/components/schemas/Messages.Attachment'
type: array
bcc:
items:
$ref: '#/components/schemas/Messages.MessagingAccount'
type: array
body:
description: |
Can include template variable references in for of *|VARIABLE|*. Recognized template variables are 'FName',
'LName', 'Title', 'CompanyName' and 'Unsubscribe'.
Template variables are surrounded with *| |* symbols. Unknown template variable references are not allowed
and will result in error.
type: string
cc:
items:
$ref: '#/components/schemas/Messages.MessagingAccount'
type: array
subject:
type: string
builder_data:
type: object
description: client Email builder data
nullable: true
content_mode:
$ref: '#/components/schemas/Messages.MessageTemplateContentMode'
unsubscribe_category_ids:
type: array
items:
type: string
description: ids of unsubscribe categories to which this message belongs. If null -- will unsubscribe
from all categories
nullable: true
required:
- subject
- body
type: object
Settings.MessagingAccountIdentifier:
properties:
account_type:
type: string
identifier:
type: string
required:
- account_type
- identifier
type: object
Messages.EmailListConfirmationMessageRequest:
properties:
message:
$ref: '#/components/schemas/Messages.MessageTemplateContentSpecification'
sender_account:
$ref: '#/components/schemas/Settings.MessagingAccountIdentifier'
sender_credential_id:
type: string
format: objectid
description: Unique identifier of sender's credential to send emails on behalf of
required:
- sender_account
- message
- sender_credential_id
type: object
Messages.EmailList:
type: object
properties:
list_id:
type: string
format: objectid
description: Unique identifier for the email list
name:
type: string
description: The name of the email list
description:
type: string
nullable: true
description: Description of the email list
opt_in_settings:
type: object
properties:
enabled:
type: boolean
description: whether to enable mandatory opt-in (i.e. confirmation of recipient via email)
confirmation_message_request:
$ref: '#/components/schemas/Messages.EmailListConfirmationMessageRequest'
owner_id:
type: string
format: objectid
description: User id of owner
is_private:
type: boolean
description: whether this mailing list is shared across company or not
archived_at:
type: string
format: date-time
description: Timestamp when the list was archived
is_archived:
type: boolean
description: whether this mailing list is archived already
total_entries:
type: integer
description: Total number of recipients in this mailing list
Contacts.EmailListsContext:
type: object
properties:
context_key:
type: object
context:
type: array
items:
$ref: '#/components/schemas/Messages.EmailList'
Contacts.ContactViewContext:
oneOf:
- $ref: '#/components/schemas/Contacts.ContactFilesContext'
- $ref: '#/components/schemas/Contacts.EmployersDataContext'
- $ref: '#/components/schemas/Contacts.LastContactedDataContext'
- $ref: '#/components/schemas/Contacts.LeadsDataContext'
- $ref: '#/components/schemas/Contacts.InSequenceContactInfoContext'
- $ref: '#/components/schemas/Contacts.EmailListsContext'
discriminator:
propertyName: context_key
mapping:
last_contacted_data: '#/components/schemas/Contacts.LastContactedDataContext'
employers_data: '#/components/schemas/Contacts.EmployersDataContext'
leads_data: '#/components/schemas/Contacts.LeadsDataContext'
contact_files: '#/components/schemas/Contacts.ContactFilesContext'
sequences_data: '#/components/schemas/Contacts.InSequenceContactInfoContext'
email_lists: '#/components/schemas/Contacts.EmailListsContext'
Contacts.ContactView:
description: user perspective on a specific contact
properties:
avatar_url:
type: string
children:
items:
type: string
type: array
employers_info:
description: DEPRECATED, use values in `contexts`
items:
properties:
company_name:
type: string
contact_id:
type: string
required:
- company_name
- contact_id
type: object
type: array
company_last_contacted:
description: DEPRECATED, use values in `contexts`
properties:
in:
$ref: '#/components/schemas/Contacts.LastContacted'
out:
$ref: '#/components/schemas/Contacts.LastContacted'
required:
- in
- out
type: object
lc:
description: DEPRECATED, use values in `contexts`
$ref: '#/components/schemas/Contacts.UserLastContactedView'
created:
type: string
creator:
type: string
fields:
additionalProperties:
items:
properties:
field_id:
type: string
modifier:
type: string
value:
type: string
required:
- field_id
- value
- modifier
type: object
type: array
type: object
id:
type: string
is_important:
type: object
last_contacted:
description: DEPRECATED, use values in `contexts`
nullable: true
$ref: '#/components/schemas/Contacts.LastContacted'
object_type:
enum:
- contact
type: string
last_contacted_user:
description: email of user that contacted for the last time (DEPRECATED, use values in `contexts`)
type: string
owner_id:
type: string
privacy:
$ref: '#/components/schemas/Contacts.ContactPrivacy'
record_type:
$ref: '#/components/schemas/Contacts.ContactType'
reminder:
nullable: true
$ref: '#/components/schemas/Contacts.Reminder'
tags:
items:
type: string
type: array
updated:
type: string
updater:
type: string
stages_info:
description: DEPRECATED. use `contexts`
type: array
items:
$ref: '#/components/schemas/Contacts.LeadInStageInfo'
notice:
$ref: '#/components/schemas/Contacts.ContactNotice'
contexts:
description: additional requested contexts (usually passed in the `contexts` request parameter)
type: array
items:
$ref: '#/components/schemas/Contacts.ContactViewContext'
required:
- id
- record_type
- object_type
- fields
- owner_id
- privacy
- children
- updated
- created
- updater
- creator
- avatar_url
- tags
- last_contacted
- company_last_contacted
- is_important
- reminder
- notice
type: object
Contacts.ContactsListing:
properties:
meta:
$ref: '#/components/schemas/Commons.PaginationMeta'
resources:
items:
$ref: '#/components/schemas/Contacts.ContactView'
type: array
required:
- meta
- resources
type: object
Errors.ValidationError:
description: request was malformed
example:
errors:
/:
message: 'missing required properties: ["calendar_id", "summary"]'
/base_occurrence/start_dtime:
message: Can't parse value 20000-01-01T01:01:00 as DATE-TIME
message: 'Invalid value {} (dict): missing required properties: []"calendar_id", "summary"]'
code: 245
human_readable_error: 'Invalid value {} (dict): missing required properties: []"calendar_id",
"summary"]"'
extra:
- {}
properties:
errors:
description: |
mapping where keys are paths to problematic request attributes
and values are objects with single message attribute
type: object
message:
type: string
code:
type: integer
description: legacy that you SHOULD NOT USE
human_readable_error:
type: string
description: Error message with some changes making it easier to read.
extra:
type: array
items:
type: object
description: extra data that would be useful to provide
required:
- message
- errors
- human_readable_error
type: object
Commons.PushData:
description: an object containing the push data from the server to the client
properties:
action:
description: the action this notification is for
example: single_message_sent
type: string
created:
description: datetime formatted in iso8601
format: date-time
type: string
id:
type: string
is_new:
type: boolean
object:
description: some structure which varies, depending on object_type and action
type: object
object_type:
description: the type of object this push data is for
example: notification
type: string
required:
- action
- object_type
- created
- is_new
- id
- object
type: object
Contacts.ContactsRemovedResponse:
properties:
data:
properties:
ids:
items:
type: string
type: array
push_data:
$ref: '#/components/schemas/Commons.PushData'
required:
- ids
- push_data
type: object
status:
type: string
required:
- data
- status
type: object
Errors.NotFoundError:
example:
object_id: 4f2acc3142a053dda595f00b
object_type: deal
properties:
object_id:
type: string
object_type:
type: string
required:
- object_type
- object_id
type: object
Errors.PreflightCheckError:
example:
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
properties:
message:
type: string
nse_query:
description: problem contacts selection query
type: object
total:
type: integer
type:
description: unique and stable identifier of error type
type: string
required:
- type
- message
- total
- nse_query
type: object
Errors.PreflightCheckFailures:
description: action cannot be applied to all specified contacts
properties:
errors:
items:
$ref: '#/components/schemas/Errors.PreflightCheckError'
type: array
required:
- errors
type: object
Contacts.ContactsIdsListing:
properties:
meta:
$ref: '#/components/schemas/Commons.PaginationMeta'
resources:
description: List of contacts’ IDs in BSON format
items:
type: string
type: array
required:
- meta
- resources
type: object
Contacts.FieldPresentationType:
enum:
- single-line-text-box
- phone
- email
- url
- multi-line-text-box
- select-box
- address
- separator
- numeric-general
- numeric-scientific
- date
- date-wo-year
- boolean
- objectid
- attachment
type: string
Contacts.FieldPresentationWidth:
enum:
- '1'
- '2'
type: string
Contacts.SimpleFieldPresentation:
properties:
type:
$ref: '#/components/schemas/Contacts.FieldPresentationType'
width:
$ref: '#/components/schemas/Contacts.FieldPresentationWidth'
required:
- type
- width
type: object
Contacts.SelectBoxFieldPresentation:
properties:
next_id:
type: string
type:
enum:
- select-box
type: string
values:
items:
properties:
id:
type: string
value:
type: string
required:
- id
- value
type: object
type: array
width:
$ref: '#/components/schemas/Contacts.FieldPresentationWidth'
required:
- type
- width
- next_id
- values
type: object
Contacts.ContactField:
example:
group: Company Info
id: 58e212d729e8e95e88606bf6
label: domain
modifier: ''
multiples: false
name: domain
presentation:
type: single-line-text-box
width: '1'
read_only: false
properties:
group:
type: string
id:
type: string
label:
type: string
modifier:
type: string
multiples:
type: boolean
name:
type: string
presentation:
oneOf:
- $ref: '#/components/schemas/Contacts.SimpleFieldPresentation'
- $ref: '#/components/schemas/Contacts.SelectBoxFieldPresentation'
read_only:
type: boolean
required:
- id
- name
- label
- modifier
- group
- presentation
- multiples
- read_only
type: object
Contacts.FieldGroupType:
enum:
- person
- company
- both
type: string
Contacts.ContactFieldsGroup:
properties:
id:
type: string
is_standard:
type: boolean
label:
type: string
name:
type: string
order:
items:
type: string
type: array
type:
$ref: '#/components/schemas/Contacts.FieldGroupType'
required:
- id
- name
- label
- order
- is_standard
- type
type: object
Contacts.FieldsMetadata:
example:
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
properties:
fields:
additionalProperties:
description: The name of field
items:
$ref: '#/components/schemas/Contacts.ContactField'
type: array
type: object
groups:
additionalProperties:
oneOf:
- $ref: '#/components/schemas/Contacts.ContactFieldsGroup'
description: The name of group
type: object
required:
- groups
- fields
type: object
Contacts.OwnerId:
description: |-
Describes id of user who is owning this contact. Keep in mind that the creator and owner may be different.
If null - owner will be unassigned.
If not specified - default owner from company settings will be applied.
nullable: true
type: string
Contacts.CreateContactRequest:
properties:
avatar_url:
type: string
fields:
description: |
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).
type: object
owner_id:
$ref: '#/components/schemas/Contacts.OwnerId'
privacy:
$ref: '#/components/schemas/Contacts.ContactPrivacy'
record_type:
$ref: '#/components/schemas/Contacts.ContactType'
tags:
description: |
Comma separated list of tags to assign to contacts. If you need to create tags,
containing comma sign — escape it with backslash.
E.g. `our customers,best\,premium` will create tags `our customers` and `best,premium`.
Note Maximum 5 tags are allowed in this list during contact creation.
type: string
type:
$ref: '#/components/schemas/Contacts.ContactType'
file_ids:
description: List of already uploaded file ids to attach to the contact
items:
type: string
required:
- fields
type: object
Errors.PaymentError:
example:
extra_usage:
features: []
resources:
- amount: 1
resource:
description: Total number of contacts in a company
per_user: false
persistent: true
resource_id: number_of_contacts
payment_type: Resources/features usage exceeded
required_spec:
plan:
available_upgrades:
- amount: 10737418240
name: Messages total storage add on
price: $10.00
resource: total_message_size
upgrade_id: storage_upgrade
- amount: 10000
name: Contacts add on
price: $10.00
resource: number_of_contacts
upgrade_id: contacts_upgrade
limits:
features: []
resources_limits:
- limit:
per_user: 2147483648
type: team_size_proportional_plan_limit
resource:
description: How many size used for message storage for a user
per_user: false
persistent: true
resource_id: total_message_size
- limit:
type: no_limit
resource:
description: Total number of users in a company
per_user: false
persistent: true
resource_id: number_of_users
- limit:
amount: 25000
type: fixed_plan_limit
resource:
description: Total number of contacts in a company
per_user: false
persistent: true
resource_id: number_of_contacts
- limit:
type: no_limit
resource:
description: How many group message templates are allowed for a user
per_user: true
persistent: true
resource_id: number_of_message_templates
- limit:
type: no_limit
resource:
description: Total number of allowed custom fields for contacts
per_user: false
persistent: true
resource_id: custom_fields
- limit:
amount: 100
type: fixed_plan_limit
resource:
description: How many group messages can be sent per day
per_user: true
persistent: false
resource_id: bulk_messages_per_day
name: Nimble Business
period: monthly
plan_id: plan_1
price:
per_user_price: $25.00
type: team_size_proportional_plan_price
upgrades: []
properties:
extra_usage:
description: Exceeded nimble usage. here you can findout what resource or feature wasn't enough
type: object
payment_type:
type: string
required_spec:
description: Subscription spec that will allow user to continue use nimble with all extra resources/features
type: object
required:
- payment_type
- required_spec
- extra_usage
type: object
Contacts.ContactUpdateRequest:
properties:
avatar_url:
type: string
fields:
description: |
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).
type: object
is_important:
type: boolean
type: object
Errors.ForbiddenError:
example:
message: You don't have access to this deal
properties:
message:
type: string
description: |
indicates that we can't authenticate the request. Message can be an arbitrary string, however there are
few special cases:
"Can't authenticate request" – something is wrong with the auth token
"email_verification_required" - if the user needs to verify their email address to continue having
access to Nimble
required:
- message
type: object
Errors.NotAcceptableError:
example:
message: You can not reopen already active deal
type: lost_contact_access
properties:
message:
type: string
type:
type: string
required:
- message
- type
type: object
Fields.TextValidationRule:
type: object
properties:
type:
enum:
- email
- url
Fields.StringFieldValuesType:
type: object
properties:
field_kind:
enum:
- string
validation_rule:
$ref: '#/components/schemas/Fields.TextValidationRule'
Fields.LongStringFieldValuesType:
type: object
properties:
field_kind:
enum:
- long_string
Commons.PossibleValues:
type: object
properties:
ordering_type:
type: string
enum:
- ordinal
- alphabetic
values:
type: array
items:
type: object
properties:
id:
type: string
value:
type: string
Fields.ChoiceFieldValuesType:
type: object
properties:
field_kind:
enum:
- choice
values:
$ref: '#/components/schemas/Commons.PossibleValues'
Fields.NumberFieldValuesType:
type: object
properties:
field_kind:
enum:
- number
Fields.DateTimeFieldValuesType:
type: object
properties:
field_kind:
enum:
- datetime
Fields.BooleanFieldValuesType:
type: object
properties:
field_kind:
enum:
- boolean
Fields.AddressFieldValuesType:
type: object
properties:
field_kind:
enum:
- address
Fields.AttachmentFieldValuesType:
type: object
properties:
field_kind:
enum:
- attachment
Fields.UserFieldValuesType:
type: object
properties:
field_kind:
enum:
- user
Fields.EmploymentFieldValuesType:
type: object
properties:
field_kind:
enum:
- employment
Fields.FieldType:
oneOf:
- $ref: '#/components/schemas/Fields.StringFieldValuesType'
- $ref: '#/components/schemas/Fields.LongStringFieldValuesType'
- $ref: '#/components/schemas/Fields.ChoiceFieldValuesType'
- $ref: '#/components/schemas/Fields.NumberFieldValuesType'
- $ref: '#/components/schemas/Fields.DateTimeFieldValuesType'
- $ref: '#/components/schemas/Fields.BooleanFieldValuesType'
- $ref: '#/components/schemas/Fields.AddressFieldValuesType'
- $ref: '#/components/schemas/Fields.AttachmentFieldValuesType'
- $ref: '#/components/schemas/Fields.UserFieldValuesType'
- $ref: '#/components/schemas/Fields.EmploymentFieldValuesType'
Fields.IntegerNumberPresentation:
type: object
properties:
number_type:
enum:
- integer
required:
- type
Fields.DecimalNumberPresentation:
type: object
properties:
number_type:
enum:
- decimal
fraction_digits:
type: integer
minimum: 1
required:
- type
- fraction_digits
Fields.PercentageNumberPresentation:
type: object
properties:
number_type:
enum:
- percentage
fraction_digits:
type: integer
minimum: 1
required:
- type
- fraction_digits
Fields.FinancialNumberPresentation:
type: object
properties:
number_type:
enum:
- financial
currency:
type: string
nullable: true
required:
- type
- currency
Fields.DateTimePresentation:
type: object
properties:
date_format:
type: string
nullable: true
description: |
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:
type: boolean
nullable: true
description: |
show if time should be presented in the field. Applicable only if date_format is None.
Must be null if date_format specified
required:
- date_format
- ignore_specific_time
Fields.FieldPresentation:
description: |
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
oneOf:
- $ref: '#/components/schemas/Fields.IntegerNumberPresentation'
- $ref: '#/components/schemas/Fields.DecimalNumberPresentation'
- $ref: '#/components/schemas/Fields.PercentageNumberPresentation'
- $ref: '#/components/schemas/Fields.FinancialNumberPresentation'
- $ref: '#/components/schemas/Fields.DateTimePresentation'
Fields.ContactField:
type: object
properties:
type:
enum:
- field
type: string
name:
type: string
field_id:
type: string
modifier:
type: string
multiples:
type: boolean
read_only:
description: if contacts values of this field is editable. It is different from available_actions.read_only
type: boolean
field_type:
$ref: '#/components/schemas/Fields.FieldType'
presentation:
$ref: '#/components/schemas/Fields.FieldPresentation'
available_actions:
description: |
edit_all - all operations with field available
edit_choices_only - just choices of field available for changing
view_only - field can't be changed
enum:
- edit_all
- edit_choices_only
- view_only
Fields.ContactFieldsGroup:
type: object
properties:
type:
enum:
- group
type: string
name:
type: string
group_id:
type: string
logo_id:
type: string
fields:
type: array
items:
$ref: '#/components/schemas/Fields.ContactField'
Fields.ContactFieldsTab:
properties:
tab_id:
type: string
tab_name:
type: string
contact_types:
$ref: '#/components/schemas/Contacts.ContactType'
is_standard:
type: boolean
members:
description: a member could be a group of fields or separate field
type: array
items:
oneOf:
- $ref: '#/components/schemas/Fields.ContactFieldsGroup'
- $ref: '#/components/schemas/Fields.ContactField'
available_actions:
description: |
edit_all - available all operations with tab
rearrange_only - available just moving tab between other tabs
view_only - tab can't be changed
enum:
- edit_all
- rearrange_only
- view_only
Fields.ContactsFieldsMetadata:
type: object
properties:
tabs:
items:
$ref: '#/components/schemas/Fields.ContactFieldsTab'
type: array
required:
- tabs
description: Contain the structure of contacts tabs, groups, and fields.
Fields.FieldTypeOnFieldCreation:
oneOf:
- $ref: '#/components/schemas/Fields.StringFieldValuesType'
- $ref: '#/components/schemas/Fields.LongStringFieldValuesType'
- $ref: '#/components/schemas/Fields.ChoiceFieldValuesType'
- $ref: '#/components/schemas/Fields.NumberFieldValuesType'
- $ref: '#/components/schemas/Fields.DateTimeFieldValuesType'
- $ref: '#/components/schemas/Fields.BooleanFieldValuesType'
- $ref: '#/components/schemas/Fields.AddressFieldValuesType'
- $ref: '#/components/schemas/Fields.UserFieldValuesType'
Fields.CreateFieldRequest:
type: object
properties:
field_type:
$ref: '#/components/schemas/Fields.FieldTypeOnFieldCreation'
group_id:
nullable: true
type: string
insert_after:
description: 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
nullable: true
type: string
name:
maxLength: 50
minLength: 1
type: string
presentation:
$ref: '#/components/schemas/Fields.FieldPresentation'
tab_id:
type: string
multiples:
type: boolean
description: whether this field can hold multiple values (by default, false)
required:
- name
- tab_id
- group_id
- field_type
- presentation
- insert_after
Fields.UpdateIsPrimaryRequest:
properties:
field_id:
type: string
position:
minimum: 0
type: integer
required:
- field_id
- position
- is_primary
type: object
Contacts.ContactNoteSpec:
properties:
contact_ids:
description: List of contacts’ IDs in BSON format to which the note will be attached. Contacts
count should be between 1 and 10.
items:
type: string
type: array
note:
type: string
note_preview:
description: Short version of note, that will be used for preview purposes
type: string
required:
- contact_ids
- note
- note_preview
type: object
Contacts.ShortContact:
properties:
avatar_url:
type: string
contact_type:
$ref: '#/components/schemas/Contacts.ContactType'
email:
items:
type: string
type: array
id:
type: string
is_viewable:
description: if this contact can be viewed in details by a calling user
type: boolean
name:
type: string
employment:
nullable: true
description: the most relevant contact employment (e.g., primary or present)
type: object
properties:
company_name:
type: string
nullable: true
title:
type: string
nullable: true
phones:
properties:
label:
description: phone label like "home", "work", etc
type: string
value:
type: string
required:
- label
- value
type: object
required:
- avatar_url
- contact_type
- id
- name
- email
- is_viewable
- phones
type: object
Contacts.ContactNote:
properties:
author_name:
description: Readable name of company user who created this note
type: string
contacts:
items:
$ref: '#/components/schemas/Contacts.ShortContact'
type: array
created:
description: Date and time when the note was created encoded in ISO 8601
type: string
id:
type: string
note:
type: string
note_preview:
type: string
owner_id:
type: string
owner:
$ref: '#/components/schemas/Accounts.ShortUserInfo'
updated:
description: Date and time when the note was updated encoded in ISO 8601
type: string
required:
- id
- owner_id
- author_name
- created
- updated
- contacts
- note_preview
- note
- owner
type: object
Contacts.SingleContactNoteSpec:
properties:
note:
type: string
note_preview:
description: Optional short version used for previews. Defaults to the full note.
type: string
required:
- note
type: object
Calls.CallResolutionSpec:
enum:
- successful
- unsuccessful
- abandoned
- left_voicemail
type: string
Activities.ActivityTypeDef:
properties:
archived:
description: True if the type was archived. We shouldn't create new activities of archived types
type: boolean
can_update_definition:
description: True if user can change definition of that type, False otherwise
type: boolean
can_update_lc:
description: True if completion of the activity should update the last contacted date
type: boolean
logo_id:
description: id of a picture to display for these activities
type: string
type_id:
description: unique and stable id for an activity type
type: string
type_name:
description: human-readable name for an activity type
type: string
required:
- type_id
- type_name
- logo_id
- can_update_lc
- can_update_definition
- archived
type: object
Settings.UserPermissions:
additionalProperties:
type: number
description: users permission
example:
api use: 1
manage deals pipelines: 1
mass delete: 1
mass export: 1
private deals edit: 1
private deals view: 1
type: object
Legacy.UserMetadata:
properties:
city:
nullable: true
type: string
description: (deprecated)
company_name:
type: string
description: (deprecated)
country:
nullable: true
description: (deprecated)
type: string
employees_count:
nullable: true
description: (deprecated)
type: integer
help_tour_data:
description: (deprecated)
properties:
app/activities/list:
type: integer
app/b/homepage:
type: integer
app/contacts/list:
type: integer
app/contacts/view:
type: integer
app/deals/list:
type: integer
app/deals/view:
type: integer
app/groupmessages/create:
type: integer
app/messages/list:
type: integer
app/messages/view:
type: integer
app/settings/:
type: integer
app/social/list:
type: integer
contact_list_group_message:
type: integer
disabled:
type: integer
nimble_widget:
type: integer
type: object
industry:
description: (deprecated)
nullable: true
type: string
phone:
nullable: true
type: string
state:
description: (deprecated)
nullable: true
type: string
street:
description: (deprecated)
nullable: true
type: string
title:
nullable: true
type: string
zip:
description: (deprecated)
nullable: true
type: string
required:
- title
- company_name
- industry
- phone
- street
- city
- state
- zip
- country
- employees_count
- help_tour_data
type: object
Accounts.User:
properties:
account_type:
type: string
avatar_url:
nullable: true
type: string
company_id:
type: string
company_name:
type: string
created:
format: date-time
type: string
disabled:
type: boolean
email:
type: string
first_name:
type: object
is_company_owner:
type: boolean
is_pending:
description: true if that user has a pending invite
type: boolean
last_active:
description: timestamp when a user made his last API request to the platform
format: date-time
type: string
last_name:
type: object
name:
type: string
permissions:
$ref: '#/components/schemas/Settings.UserPermissions'
receive_newsletter:
type: boolean
has_password:
type: boolean
description: |
if this user has a password set (for some account types, like google accounts, the password is optional)
timezone:
type: string
under_gdpr:
type: boolean
user_id:
type: string
metadata:
$ref: '#/components/schemas/Legacy.UserMetadata'
email_verification_due:
type: boolean
description: |
A flag indicating whether the email verification is due. Almost all API call will result in 403 response
for users with unverified email.
required:
- under_gdpr
- user_id
- company_id
- company_name
- email
- name
- first_name
- last_name
- timezone
- disabled
- avatar_url
- created
- account_type
- is_company_owner
- receive_newsletter
- permissions
- last_active
- is_pending
- metadata
- has_password
type: object
Commons.Comment:
properties:
author:
$ref: '#/components/schemas/Accounts.User'
comment_id:
type: string
created:
type: string
text:
type: string
updated:
type: string
required:
- comment_id
- author
- text
- created
- updated
type: object
Deals.ShortSavedDeal:
properties:
deal_id:
description: unique id of a deal
type: string
is_editable:
description: Is this deal is editable to a user who retrieved it
type: boolean
is_viewable:
description: Is this deal is viewable to a user who retrieved it (True for private deals
type: boolean
name:
type: string
amount:
type: integer
nullable: true
Sequences.SequenceBriefInfo:
type: object
properties:
id:
type: string
description: unique id of the sequence
name:
type: string
description: name of the sequence
required:
- id
- name
Activities.Activity:
properties:
activity_id:
type: string
activity_type:
$ref: '#/components/schemas/Activities.ActivityTypeDef'
assigned_to:
$ref: '#/components/schemas/Accounts.User'
comments:
items:
$ref: '#/components/schemas/Commons.Comment'
type: array
completed_tstamp:
type: object
created:
type: string
description:
type: string
details:
description: Activity specific data that only relevant for certain implementation
type: object
feed_tstamp:
type: object
is_important:
type: boolean
name:
type: string
owner:
$ref: '#/components/schemas/Accounts.User'
priority:
enum:
- high
- medium
- low
type: string
related_contacts:
items:
$ref: '#/components/schemas/Contacts.ShortContact'
type: array
new_related_deals:
items:
$ref: '#/components/schemas/Deals.ShortSavedDeal'
type: array
related_sequence:
$ref: '#/components/schemas/Sequences.SequenceBriefInfo'
nullable: true
description: sequence that created this activity, if applicable
scheduled_tstamp:
type: object
tags:
items:
type: string
type: array
required:
- details
- activity_type
- activity_id
- name
- description
- assigned_to
- related_contacts
- scheduled_tstamp
- completed_tstamp
- feed_tstamp
- tags
- priority
- comments
- is_important
- owner
- created
- related_sequence
type: object
Tasks.TaskRelatedObjectsSpec:
description: Objects to associate with a task. Use `related.contacts` rather than the legacy `related_to`
field.
properties:
contacts:
description: Contact IDs to associate with the task.
items:
type: string
type: array
deals:
description: Deal IDs to associate with the task.
items:
type: string
type: array
type: object
Tasks.NewTaskSpecification:
properties:
assigned_to:
type: string
completed_time:
type: string
due_date:
type: string
is_important:
type: boolean
notes:
type: string
related:
$ref: '#/components/schemas/Tasks.TaskRelatedObjectsSpec'
subject:
type: string
tags:
items:
type: string
type: array
required:
- subject
type: object
Tasks.TaskRelatedObjects:
properties:
contacts:
description: Contacts associated with the task.
items:
$ref: '#/components/schemas/Contacts.ShortContact'
type: array
deals:
description: legacy deal ids (always empty, kept for backwards compatibility)
items:
type: string
type: array
new_deals:
description: Deals associated with the task.
items:
$ref: '#/components/schemas/Deals.ShortSavedDeal'
type: array
sequence:
$ref: '#/components/schemas/Sequences.SequenceBriefInfo'
nullable: true
description: sequence that created this task, if applicable
required:
- contacts
- deals
- new_deals
- sequence
type: object
Tasks.Task:
properties:
assigned_to:
$ref: '#/components/schemas/Accounts.ShortUserInfo'
nullable: true
comments:
items:
$ref: '#/components/schemas/Commons.Comment'
type: array
company_id:
type: string
completed:
type: boolean
completed_time:
nullable: true
type: string
created:
type: string
due_date:
nullable: true
type: string
due_date_text:
nullable: true
type: string
id:
type: string
is_important:
type: boolean
notes:
nullable: true
type: string
owner:
$ref: '#/components/schemas/Accounts.ShortUserInfo'
owner_id:
type: string
related:
$ref: '#/components/schemas/Tasks.TaskRelatedObjects'
related_to:
description: Legacy response field. To associate contacts when creating a task, use `related.contacts`.
items:
type: string
type: array
starred:
type: boolean
subject:
type: string
tags:
items:
type: string
type: array
updated:
type: string
version:
default: 2
type: integer
required:
- version
- assigned_to
- comments
- company_id
- completed
- completed_time
- created
- due_date
- due_date_text
- id
- is_important
- starred
- notes
- owner_id
- related_to
- related
- subject
- tags
- updated
- owner
type: object
Proceedings.ProceedingTypeDef:
properties:
type_id:
description: Unique and stable id for an proceeding type
type: string
enum:
- contact_note
- contact_attachment
- message
- webform_response
- task
- call
- event
- deal
- new_deal
type_name:
description: human-readable name for an proceeding type
type: string
Proceedings.ProceedingProvider:
properties:
name:
type: string
provider_id:
type: string
types:
items:
$ref: '#/components/schemas/Proceedings.ProceedingTypeDef'
type: array
required:
- provider_id
- name
- types
type: object
Proceedings.Proceeding:
properties:
description:
type: string
details:
description: Proceeding-specific data that only relevant for certain implementation
type: object
feed_tstamp:
type: string
name:
type: string
proceeding_id:
type: string
proceeding_type:
$ref: '#/components/schemas/Proceedings.ProceedingTypeDef'
required:
- details
- proceeding_type
- proceeding_id
- name
- description
- feed_tstamp
type: object
Contacts.StageRole:
properties:
is_final:
type: boolean
name:
type: string
required:
- name
- is_final
type: object
Contacts.LeadStage:
properties:
archived_at:
nullable: true
type: string
created:
type: string
creator:
$ref: '#/components/schemas/Accounts.ShortUserInfo'
days_limit:
nullable: true
type: number
description:
nullable: true
type: string
name:
type: string
pipeline_id:
type: string
position:
type: number
role:
$ref: '#/components/schemas/Contacts.StageRole'
stage_id:
type: string
updated:
type: string
required:
- stage_id
- pipeline_id
- creator
- name
- description
- created
- updated
- archived_at
- position
- days_limit
- role
type: object
Contacts.LeadLostReason:
type: object
properties:
id:
type: string
text:
type: string
Contacts.LeadsPipeline:
properties:
archived_at:
nullable: true
type: string
color:
type: string
created:
type: string
fields:
type: array
items:
type: object
properties:
column_id:
type: string
enabled:
type: boolean
required:
- column_id
- enabled
creator:
$ref: '#/components/schemas/Accounts.ShortUserInfo'
description:
nullable: true
type: string
name:
type: string
pipeline_id:
type: string
stages:
items:
$ref: '#/components/schemas/Contacts.LeadStage'
type: array
updated:
type: string
lost_reasons:
description: a list with possible lost reasons that can be specified for a lost lead
type: array
items:
$ref: '#/components/schemas/Contacts.LeadLostReason'
required:
- pipeline_id
- creator
- name
- description
- created
- updated
- archived_at
- stages
- color
- lost_reasons
type: object
Contacts.ExitLeadSuccessfullyRequest:
properties:
actual_exit_date:
description: |
if specified, this value will be set as the actual exit data, otherwise the time of the request will be used
type: string
nullable: true
notes:
description: optional notes (comments) to add to this transition to a won stage
type: string
nullable: true
type: object
Contacts.ExitLeadUnsuccessfullyRequest:
properties:
actual_exit_date:
description: |
if specified, this value will be set as the actual exit data, otherwise the time of the request will be used
type: string
nullable: true
notes:
description: optional notes (comments) to add to this transition to a lost stage
type: string
nullable: true
lost_reason:
description: optional lost reason to add to this "exit"
type: string
nullable: true
type: object
Deals.RelatedExternalContact:
description: external contact related to this deal
type: object
properties:
contact_info:
type: string
note:
type: string
Deals.Principals:
type: object
properties:
user_ids:
type: array
items:
type: string
format: BSONObjectId
description: Set of user IDs with permissions
minItems: 0
group_ids:
type: array
items:
type: string
format: BSONObjectId
description: Set of group IDs with permissions
minItems: 0
required:
- user_ids
- group_ids
example:
user_ids:
- 507f1f77bcf86cd799439011
group_ids:
- 507f1f77bcf86cd799439012
Deals.DealPrivacy:
type: object
properties:
read:
$ref: '#/components/schemas/Deals.Principals'
description: Principals permitted to read deal. Null if permitted for everyone
edit:
$ref: '#/components/schemas/Deals.Principals'
description: Principals permitted to read and edit deal. Null if permitted for everyone
required:
- read
- edit
example:
read:
user_ids:
- 507f1f77bcf86cd799439011
group_ids:
- 507f1f77bcf86cd799439012
edit:
user_ids:
- 507f1f77bcf86cd799439013
group_ids:
- 507f1f77bcf86cd799439014
Deals.EmploymentInfo:
description: Information about date employment
type: object
properties:
employer:
$ref: '#/components/schemas/Contacts.ShortContact'
start_date:
description: First working day
type: string
end_date:
description: Last working day
type: string
title:
description: Job-title of contact
type: string
Deals.RelatedContact:
description: Contacts related to deal
type: object
properties:
contact:
description: short info about related contact
$ref: '#/components/schemas/Contacts.ShortContact'
note:
description: contact's note
type: string
employments:
description: employments of this contact if applicable
type: array
items:
$ref: '#/components/schemas/Deals.EmploymentInfo'
Deals.FieldsValues:
type: object
description: Fields of the deals which was filled up by the owner/creator
properties:
field_id:
type: string
example: 65958d7ef2e8748e6361ddb1
values:
type: array
items:
type: object
properties:
value:
type: string
example: value_1
is_primary:
type: boolean
example: true
Deals.NamedFieldsValues:
type: object
description: Fields of the deals which was filled up by the owner/creator
properties:
field_name:
type: string
example: amount
values:
type: array
items:
type: object
properties:
value:
type: string
example: value_1
is_primary:
type: boolean
example: true
Pipeline.DealStage:
description: Stage in the deals pipeline
type: object
properties:
default_probability:
description: Probability, that will be set to a deal at this stage, if not specific deal probability
provided.
type: integer
stage_id:
type: string
description:
type: string
creator:
$ref: '#/components/schemas/Accounts.ShortUserInfo'
created:
type: string
updated:
type: string
pipline_id:
description: Id of pipeline deals belongs to
type: string
role:
type: object
properties:
name:
type: string
is_final:
type: boolean
example: true
archived_at:
description: When and if this stage has been archived
type: string
nullable: true
expected_days:
description: The number of days a deal is expected to spend at this stage
type: integer
name:
description: Name of the stage
type: string
Deals.DealStageTransition:
properties:
from_stage:
$ref: '#/components/schemas/Pipeline.DealStage'
description: Can be null if this was the very first transition
to_stage:
$ref: '#/components/schemas/Pipeline.DealStage'
who:
$ref: '#/components/schemas/Accounts.ShortUserInfo'
when:
type: string
format: date
notes:
type: string
nullable: true
required:
- from_stage
- to_stage
- who
- when
type: object
Deals.DealPipelineTransitions:
properties:
pipeline_id:
type: string
pipeline_color:
type: string
pipeline_name:
type: string
transitions:
items:
$ref: '#/components/schemas/Deals.DealStageTransition'
type: array
before_final_stage:
$ref: '#/components/schemas/Pipeline.DealStage'
nullable: true
description: previous to the final stage (if the deal is won or lost, otherwise - null)
required:
- pipeline_id
- pipeline_color
- pipeline_name
- transitions
type: object
Deals.AzureFileMetadata:
type: object
description: metadata for files uploaded from device using Azure JS SDK
properties:
data_id:
description: id of an object in the cloud
type: string
source:
enum:
- uploaded_azure
Deals.ExternalFileMetadata:
type: object
description: metadata for files from external sources (dropbox, google drive, one drive)
properties:
icon_url:
type: string
file_url:
type: string
source:
enum:
- dropbox
- one_drive
- google_drive
Deals.DealFile:
type: object
properties:
uploader:
$ref: '#/components/schemas/Accounts.ShortUserInfo'
uploaded_at:
type: string
file_size:
type: number
description: the file size in bytes
file_name:
type: string
file_id:
type: string
metadata:
oneOf:
- $ref: '#/components/schemas/Deals.AzureFileMetadata'
- $ref: '#/components/schemas/Deals.ExternalFileMetadata'
Deals.DealView:
properties:
updated:
description: Time of the last Deal update
type: string
deal_id:
description: Id of created Deal
type: string
deal_number:
description: Auto-incrementing deal number, unique within company
type: integer
creator:
description: Deal creator
$ref: '#/components/schemas/Accounts.ShortUserInfo'
related_external_contacts:
description: List of external contacts related to this deal
type: array
items:
$ref: '#/components/schemas/Deals.RelatedExternalContact'
privacy:
description: Read/Edit privacy settings
$ref: '#/components/schemas/Deals.DealPrivacy'
updated_by:
description: Last updated by which user
type: string
created:
description: Datetime when deal was created
type: string
is_editable:
description: Is this deal is editable to a user who retrieved it
type: boolean
currency:
description: Currency of Deal
type: string
format: iso-4217
related_contacts:
description: List of Nimble contacts related to this deal
type: array
items:
$ref: '#/components/schemas/Deals.RelatedContact'
owner:
description: User who owns this deal
$ref: '#/components/schemas/Accounts.ShortUserInfo'
fields_values:
description: 'Fields of the deals which was filled up by the owner/creator. At leas field deal_name
is required.
Standard fields description:
- name
- required. Name of the deal.
- probability - required
(if none
Stage.default_probability set). Deal probability. If not provided by
user, deal will try to derive it from stage''s default_probability. If none,
will rise error - description - optional. Description of the deal. Sending just
'' '' (whitespace) removing it
- amount - optional. Amount of tha money in the
deal. Can be only positive number or 0
- expected_close_date - optional. Date
when deal is expected to be closed.
- actual_close_date - optional. Actual date.
View only.
To remove any field send {field_id:[]}'
$ref: '#/components/schemas/Deals.FieldsValues'
fields_values_with_names:
$ref: '#/components/schemas/Deals.NamedFieldsValues'
stage_transitions:
$ref: '#/components/schemas/Deals.DealPipelineTransitions'
files:
$ref: '#/components/schemas/Deals.DealFile'
tags:
items:
type: string
type: array
final_probability:
description: custom deal probability if it specified or deal stage probability
type: integer
age_in_days:
type: number
Deals.DealsList:
type: object
description: List of user deals
properties:
meta:
type: object
properties:
per_page:
type: integer
description: amount of deals per page
total:
type: integer
description: total amount of deals
page:
type: integer
description: number of the current page
pages:
type: integer
description: total amount of pages
resources:
type: array
description: List of deals
items:
$ref: '#/components/schemas/Deals.DealView'
Deals.CreateDealRequest:
properties:
owner_id:
description: id of user who owns deal
type: string
privacy:
description: deal's read and edit privacy
$ref: '#/components/schemas/Deals.DealPrivacy'
fields_values:
description: 'Fields of the deals which was filled up by the owner/creator. At leas field deal_name
is required.
Standard fields description:
- name
- required. Name of the deal.
- probability - required
(if none
Stage.default_probability set). Deal probability. If not provided by
user, deal will try to derive it from stage''s default_probability. If none,
will rise error - description - optional. Description of the deal. Sending just
'' '' (whitespace) removing it
- amount - optional. Amount of tha money in the
deal. Can be only positive number or 0
- expected_close_date - optional. Date
when deal is expected to be closed.
- actual_close_date - optional. Actual date.
View only.
To remove any field send {field_id:[]} List of available
fields can be obtained from /api/v2/deals/fields'
type: object
additionalProperties:
type: array
items:
type: object
properties:
value:
type: string
example:
63760e653af0e748fe48366a:
- value: Deal Name
63760e653af0e748fe48366b:
- value: '10000'
description:
- value: Important deal
pipeline_id:
description: id of the pipeline which belongs to this deal
type: string
stage_id:
type: string
description: id of stage on which deal is currently is
currency:
description: Currency of the deal in ISO-4217 format (3 char
code)
type: string
format: ISO-4217
related_contacts:
description: List of Nimble contacts that take part in the deal.
type: array
items:
type: object
properties:
contact_id:
type: string
note:
type: string
nullable: true
related_external_contacts:
description: A list with related external contacts. Similar to related_contacts, but instead
of contact_id we use contact_info (email, phone etc)
type: array
items:
$ref: '#/components/schemas/Deals.RelatedExternalContact'
tags:
type: array
items:
type: string
required:
- owner
- fields_values
- pipeline_id
- stage_id
type: object
Columns.ColumnPresentationType:
enum:
- single-line-text-box
- phone
- mail
- url
- multi-line-text-box
- select-box
- address
- numeric-general
- date
- boolean
- attachment
- tags
- privacy
- user
- contact employment
nullable: false
type: string
Columns.ColumnPresentation:
type: object
properties:
type:
$ref: '#/components/schemas/Columns.ColumnPresentationType'
possible_values:
$ref: '#/components/schemas/Commons.PossibleValues'
Columns.ListingColumn:
properties:
id:
description: unique column identifier
type: string
human_readable_name:
description: name to display
type: string
json_path:
description: JSONPath to determine the exact value from contact data. It should return a list
of values
type: string
value_json_path:
description: JSONPath to determine the exact value from field's value (when value is json itself).
type: string
nullable: true
presentation:
description: allows client to distinguish different field types. Single line by default
$ref: '#/components/schemas/Columns.ColumnPresentation'
read_only:
description: defines ability to edit this column
type: boolean
is_standard:
description: show if the column is standard or created by the user
type: boolean
sortable:
description: True if contacts can be sorted by this column
type: boolean
type: object
Columns.ColumnGroup:
properties:
columns:
items:
$ref: '#/components/schemas/Columns.ListingColumn'
type: array
group_id:
type: string
human_readable_name:
type: string
required:
- group_id
- human_readable_name
- columns
type: object
Search.SearchField:
type: object
properties:
human_readable_name:
type: string
search_name:
type: string
data_type:
type: object
properties:
type_id:
enum:
- textlike
- datelike
- numberlike
occurrences:
type: array
items:
enum:
- starts_with
frequently_used:
type: boolean
possible_values:
$ref: '#/components/schemas/Commons.PossibleValues'
Deals.DealListingColumn:
allOf:
- $ref: '#/components/schemas/Columns.ListingColumn'
- properties:
search_field:
$ref: '#/components/schemas/Search.SearchField'
type: object
Deals.BaseDealPipelineFieldsTabMember:
properties:
type:
type: string
type: object
Deals.IDealField:
type: object
properties:
field_id:
description: The id of a field in the database
type: string
modifier:
type: string
multiples:
type: boolean
available_actions:
description: Shows available for user actions
type: string
field_type:
type: string
field_name:
description: The name of a field
type: string
Deals.DealPipelineField:
description: Fields of DealsPipeline
allOf:
- $ref: '#/components/schemas/Deals.BaseDealPipelineFieldsTabMember'
- properties:
field:
$ref: '#/components/schemas/Deals.IDealField'
pipeline_id:
type: string
type: object
Deals.DealPipelineFieldsGroup:
allOf:
- $ref: '#/components/schemas/Deals.BaseDealPipelineFieldsTabMember'
- properties:
group_name:
type: string
group_id:
type: string
logo_id:
type: string
fields:
type: array
items:
$ref: '#/components/schemas/Deals.DealPipelineField'
type: object
Deals.DealPipelineFieldsTabMember:
oneOf:
- $ref: '#/components/schemas/Deals.DealPipelineField'
- $ref: '#/components/schemas/Deals.DealPipelineFieldsGroup'
discriminator:
propertyName: type
mapping:
field: '#/components/schemas/Deals.DealPipelineField'
group: '#/components/schemas/Deals.DealPipelineFieldsGroup'
Deals.DealPipelineFieldsTab:
type: object
properties:
tab_id:
description: The id of a tab in the database
type: string
tab_name:
description: The name of a tab
type: string
pipeline_id:
type: string
members:
$ref: '#/components/schemas/Deals.DealPipelineFieldsTabMember'
Deals.DealFieldsMetadata:
type: object
properties:
pipelines_tabs:
type: array
items:
$ref: '#/components/schemas/Deals.DealPipelineFieldsTab'
standard_fields:
type: array
items:
$ref: '#/components/schemas/Deals.IDealField'
Commons.Tag:
properties:
name:
type: string
created:
description: datetime object that equals to time when tag was created
type: string
nullable: true
required:
- name
type: object
Contacts.ContactsAlreadyLeadsError:
properties:
error_type:
type: string
error_description:
type: string
already_leads:
type: array
items:
type: object
properties:
id:
type: string
full_name:
type: string
Contacts.NotEditableContactsError:
properties:
error_type:
type: string
error_description:
type: string
count:
type: integer
Contacts.AssigmentProgress:
properties:
is_completed:
type: boolean
operation_id:
type: string
processed:
type: integer
started_at:
type: string
total:
type: integer
errors:
type: array
items:
oneOf:
- $ref: '#/components/schemas/Contacts.ContactsAlreadyLeadsError'
- $ref: '#/components/schemas/Contacts.NotEditableContactsError'
required:
- operation_id
- processed
- total
- started_at
- is_completed
- errors
type: object
Deals.EditDealRequest:
type: object
properties:
owner_id:
description: id of user who owns the deal
type: string
example: 5049f696a694620a0700001c
privacy:
description: deal's read and edit privacy
$ref: '#/components/schemas/Deals.DealPrivacy'
fields_values:
description: 'Fields of the deals which was filled up by the owner/creator. At leas field deal_name
is required.
Standard fields description:
- name
- required. Name of the deal.
- probability - required
(if none
Stage.default_probability set). Deal probability. If not provided by
user, deal will try to derive it from stage''s default_probability. If none,
will rise error - description - optional. Description of the deal. Sending just
'' '' (whitespace) removing it
- amount - optional. Amount of tha money in the
deal. Can be only positive number or 0
- expected_close_date - optional. Date
when deal is expected to be closed.
- actual_close_date - optional. Actual date.
View only.
To remove any field send {field_id:[]}'
oneOf:
- $ref: '#/components/schemas/Deals.FieldsValues'
- $ref: '#/components/schemas/Deals.NamedFieldsValues'
pipeline_id:
description: id of the pipeline to which this deal belongs
type: string
example: 630f34cfa34058dea76c0c0e
stage_id:
description: id of the stage on which deal is now
type: string
example: 62fd6587048065ca3510c6d5
currency:
description: 'Currency of the deal in ISO-4217 (3 char code).'
type: string
format: ISO-4217
example: USD
related_contacts:
description: 'List of Nimble contacts that take part in the deal. If you want to clear contacts
list, send {''related_external_contacts'': []}'
type: array
items:
type: object
properties:
contact_id:
type: string
note:
type: string
nullable: true
example:
- contact_id: 630c6f7bf5943b012188c778
note: Some Note Text
related_external_contacts:
description: 'A list with related external contacts. Similar to related_contacts,
but instead of contact_id we use contact_info (email, phone etc).
If you want to clear contacts list, send {''related_external_contacts'': []}'
type: array
items:
$ref: '#/components/schemas/Deals.RelatedExternalContact'
tags:
description: new list of deal's tags
items:
type: string
type: array
Deals.StoreAzureFileRequest:
type: object
properties:
metadata:
$ref: '#/components/schemas/Deals.AzureFileMetadata'
Deals.StoreExternalFileRequest:
type: object
properties:
metadata:
$ref: '#/components/schemas/Deals.ExternalFileMetadata'
file_name:
type: string
file_size:
type: number
Deals.StoreFileRequest:
oneOf:
- $ref: '#/components/schemas/Deals.StoreAzureFileRequest'
- $ref: '#/components/schemas/Deals.StoreExternalFileRequest'
Deals.UpdateDealFileRequest:
type: object
properties:
new_file_name:
type: string
Deals.DealNote:
type: object
properties:
note_id:
type: string
title:
type: string
body:
type: string
created:
type: string
format: date-time
updated:
type: string
format: date-time
creator:
$ref: '#/components/schemas/Accounts.ShortUserInfo'
Pipeline.LeadLostReason:
type: object
properties:
id:
description: The id of a reason in the db
type: string
format: ObjectId
text:
description: reason's text
type: string
Pipeline.DealsPipeline:
properties:
pipeline_id:
description: The unique ID of a pipeline
type: string
format: ObjectId
creator:
$ref: '#/components/schemas/Accounts.ShortUserInfo'
name:
description: The description for the pipeline
type: string
description:
type: string
nullable: true
created:
type: string
updated:
type: string
archived_at:
description: The timestamp of when the pipeline was archived (None if it's not archived)
type: string
nullable: true
stages:
type: array
items:
$ref: '#/components/schemas/Pipeline.DealStage'
color:
description: The color of a pipeline
type: string
lost_reasons:
type: array
items:
$ref: '#/components/schemas/Pipeline.LeadLostReason'
is_default:
description: If this pipeline was pre-generated on company creation
type: boolean
default_currency:
description: Default currency for pipeline
type: string
nullable: true
tabs:
type: array
items:
$ref: '#/components/schemas/Deals.DealPipelineFieldsTab'
Pipeline.CreateDealStageRequest:
description: Stage in the pipeline where deals will be placed
type: object
properties:
name:
type: string
description: Name of the stage
description:
type: string
description: Stage description
pipeline_id:
type: string
format: ObjectId
description: Id of the pipeline where stage should be
insert_after:
type: string
format: ObjectId
description: Id of the stage that should be positioned before this new stage
expected_days:
type: number
minimum: 0
description: Expected day before stage complete
default_probability:
type: number
minimum: 0
maximum: 100
description: Default probability for all deals in this stage (will be deal probability if one
doesn't have its own)
Pipeline.StringFieldValuesType:
type: object
properties:
field_kind:
enum:
- string
validation_rule:
enum:
- email
- url
Pipeline.LongStringFieldValuesType:
type: object
properties:
field_kind:
enum:
- long_string
Pipeline.ChoiceFieldValuesType:
type: object
properties:
field_kind:
enum:
- choice
values:
$ref: '#/components/schemas/Commons.PossibleValues'
Pipeline.NumberFieldValuesType:
type: object
properties:
field_kind:
enum:
- number
Pipeline.DateTimeFieldValuesType:
type: object
properties:
field_kind:
enum:
- datetime
Pipeline.BooleanFieldValuesType:
type: object
properties:
field_kind:
enum:
- boolean
Pipeline.AddressFieldValuesType:
type: object
properties:
field_kind:
enum:
- address
Pipeline.UserFieldValuesType:
type: object
properties:
field_kind:
enum:
- user
Pipeline.FieldTypeOnFieldCreation:
oneOf:
- $ref: '#/components/schemas/Pipeline.StringFieldValuesType'
- $ref: '#/components/schemas/Pipeline.LongStringFieldValuesType'
- $ref: '#/components/schemas/Pipeline.ChoiceFieldValuesType'
- $ref: '#/components/schemas/Pipeline.NumberFieldValuesType'
- $ref: '#/components/schemas/Pipeline.DateTimeFieldValuesType'
- $ref: '#/components/schemas/Pipeline.BooleanFieldValuesType'
- $ref: '#/components/schemas/Pipeline.AddressFieldValuesType'
- $ref: '#/components/schemas/Pipeline.UserFieldValuesType'
Pipeline.CreateDealsPipelineFieldRequest:
type: object
properties:
name:
type: string
description: Name of the new field
field_type:
$ref: '#/components/schemas/Pipeline.FieldTypeOnFieldCreation'
presentation:
$ref: '#/components/schemas/Fields.FieldPresentation'
nullable: true
pipeline_id:
type: string
description: id of pipeline this field is being created for (if known)
nullable: true
insert_after:
type: string
description: Inserts a new field after field or group with specified id. If null,
then field is inserted as the first one
nullable: true
group_id:
description: id of group this field is being created for (if field is a member
of group)
type: string
required:
- name
- field_type
- presentation
Pipeline.CreateDealsPipelineGroupRequest:
type: object
properties:
group_name:
type: string
logo_id:
type: string
insert_after:
description: 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
nullable: true
type: string
fields:
type: array
items:
$ref: '#/components/schemas/Pipeline.CreateDealsPipelineFieldRequest'
Pipeline.CreateDealsPipelineRequest:
type: object
properties:
name:
type: string
description: Name of new pipeline
minLength: 1
maxLength: 200
description:
type: string
maxLength: 256
color:
type: string
lost_reasons:
type: array
items:
type: string
maxLength: 256
default: []
stages:
type: array
items:
type: object
$ref: '#/components/schemas/Pipeline.CreateDealStageRequest'
default: []
fields_tab_members:
type: array
items:
anyOf:
- $ref: '#/components/schemas/Pipeline.CreateDealsPipelineGroupRequest'
- $ref: '#/components/schemas/Pipeline.CreateDealsPipelineFieldRequest'
default_currency:
type: string
format: ISO-4217
required:
- name
- description
- color
- lost_reasons
- stages
- fields_tab_members
- default_currency
Pipeline.EditDealsPipelineRequest:
description: Updates pipeline
type: object
properties:
name:
type: string
minLength: 1
maxLength: 200
description: New pipeline name
description:
type: string
description: New pipeline description
color:
type: string
description: New pipeline color
Deals.DealsStageGroup:
type: object
description: Grouped data about stage and deals in it + meta
properties:
deals:
description: Deals in this stage
type: array
items:
$ref: '#/components/schemas/Deals.DealView'
stage:
description: Deal stage from pipeline
$ref: '#/components/schemas/Pipeline.DealStage'
meta:
description: Meta data about this stage
type: object
properties:
total_new_count:
description: Total pipeline deals count which entered stage less than 3 days ago
type: integer
next_page_url:
description: URL to load more deals for this stage. None if no more deals
type: string
total_amount:
description: Sum of deal amount separated by currencies
type: array
items:
type: object
properties:
currency:
type: string
format: ISO-4217
count:
type: integer
Deals.DealsByOwnerGroup:
type: object
description: Grouped data about owners and deals related to it + meta
properties:
deals:
description: Deals owned by user
type: array
items:
$ref: '#/components/schemas/Deals.DealView'
owner:
description: User that owned deals
$ref: '#/components/schemas/Accounts.ShortUserInfo'
meta:
description: Meta data about this group
type: object
properties:
next_page_url:
description: URL to load more deals for this group. None if no more deals
type: string
total_amount:
description: Sum of deal amount separated by currencies
type: array
items:
type: object
properties:
currency:
type: string
format: ISO-4217
count:
type: integer
Errors.ActionCanNotBeCompleted:
description: Action can not be complited becouse of reason described in error message
properties:
message:
description: Human-readable message for an error
type: string
error_type:
description: stable and unique identifier for error type. Clients should be able to rely on
it
type: string
Pipeline.EditDealStageRequest:
type: object
properties:
name:
type: string
description: Stage name
minLength: 1
maxLength: 4096
description:
type: string
description: Stage description
nullable: true
minLength: 1
maxLength: 4096
expected_days:
type: integer
description: The number of days a deal is expected to spend at this stage
default_probability:
description: Stage default probability. Will be assigned to all deals in stage if they don't
have their own
type: integer
minimum: 0
maximum: 100
Pipeline.UpdateDealsPipelineFieldRequest:
type: object
properties:
name:
type: string
description: Name of the new field
presentation:
$ref: '#/components/schemas/Fields.FieldPresentation'
nullable: true
insert_after:
type: string
description: Inserts a new field after field or group with specified id. If null,
then field is inserted as the first one
nullable: true
group_id:
type: string
format: ObjectId
description: id of group where field will be located or null if field will not
be in group
nullable: true
Pipeline.CreateDealsPipelineFieldChoiceRequest:
type: object
properties:
choice:
type: object
description: New choice
properties:
id:
type: string
value:
type: string
insert_after:
description: Move choice after choice with specified id. If null, then choice will
be the first one in field
type: string
nullable: true
required:
- choice
Pipeline.UpdateDealsPipelineFieldChoiceRequest:
type: object
properties:
value:
description: New choice value
type: string
nullable: true
insert_after:
description: Move choice after choice with specified id. If null, then choice will
be the first one in field
type: string
nullable: true
Messages.MessageTrackingConfiguration:
description: |
tracking configuration
type: object
properties:
opens_tracking:
type: boolean
description: whether to track message opens
clicks_tracking:
type: boolean
description: whether to track link clicks in a message
Messages.WatchRepliesRequest:
description: |
pass this object if we want to watch for the replies to this message
type: object
properties:
expiration_interval:
type: number
nullable: true
description: expiration interval in seconds
expiration_tstamp:
type: string
nullable: true
description: some concrete datetime when the thread watcher expires
Messages.IncompleteMessageSpecification:
description: |
"incomplete" message specification. All fields are optional.
type: object
properties:
attachments:
default: []
items:
$ref: '#/components/schemas/Messages.Attachment'
type: array
bcc:
default: []
items:
$ref: '#/components/schemas/Messages.MessagingAccount'
type: array
body:
nullable: true
type: string
cc:
default: []
items:
$ref: '#/components/schemas/Messages.MessagingAccount'
type: array
in_reply_to:
nullable: true
type: object
description: |
if this message spec is a reply to a thread, this object contains the id of message it's a reply to
and the id of a thread
properties:
in_reply_to_id:
type: string
description: "the id of a message assigned to it by a mail provider (the `provider_umid`\
\ property \nin the message's response we're replying to)\n"
thread_id:
type: string
description: the id of a thread this reply is to
recipients:
items:
$ref: '#/components/schemas/Messages.MessagingAccount'
type: array
sender:
type: object
oneOf:
- $ref: '#/components/schemas/Messages.MessagingAccount'
nullable: true
subject:
nullable: true
type: string
tracking_enabled:
nullable: true
type: object
description: DEPRECATED. use `tracking_configuration` instead
tracking_configuration:
$ref: '#/components/schemas/Messages.MessageTrackingConfiguration'
watch_replies:
type: object
nullable: true
oneOf:
- $ref: '#/components/schemas/Messages.WatchRepliesRequest'
builder_data:
type: object
description: client Email builder data
nullable: true
content_mode:
$ref: '#/components/schemas/Messages.MessageTemplateContentMode'
sender_credential_id:
type: string
format: ObjectId
description: credential to send this message (if null, credential will be determined by sender)
nullable: true
Messages.MappedMessagingAccount:
description: scheduled message participant (sender, cc, bcc, recipient) matched to a Nimble contact
if available
type: object
properties:
email:
type: string
contact:
description: matched Nimble contact if available
oneOf:
- $ref: '#/components/schemas/Contacts.ShortContact'
user:
description: matched Nimble user if available
type: object
nullable: true
oneOf:
- $ref: '#/components/schemas/Accounts.ShortUserInfo'
Messages.DraftMessageWithParticipants:
type: object
properties:
draft_id:
type: string
specification:
$ref: '#/components/schemas/Messages.IncompleteMessageSpecification'
updated:
description: last timestamp of when the draft was updated
type: string
creator:
$ref: '#/components/schemas/Accounts.ShortUserInfo'
recipients:
description: matched recipients
items:
$ref: '#/components/schemas/Messages.MappedMessagingAccount'
type: array
cc:
description: matched cc addresses
items:
$ref: '#/components/schemas/Messages.MappedMessagingAccount'
type: array
bcc:
description: matched bcc addresses
items:
$ref: '#/components/schemas/Messages.MappedMessagingAccount'
type: array
sender:
$ref: '#/components/schemas/Messages.MappedMessagingAccount'
security:
- ApiKey: []
tags:
- name: Authentication
description: "## Introduction\n\nThis document will describe authorization flow that return the\nauthorization\
\ token that allow to make requests to Nimble API and access\nresources to which access has been granted\
\ for user. For For\nauthorization Nimble use OAuth 2.0 protocol with bearer tokens. All\ntechnical\
\ details can be read in\n[RFC6749](http://tools.ietf.org/html/rfc6749) and\n[RFC6750](http://tools.ietf.org/html/rfc6750),\
\ but you don\\'t need to\nread them (unless you want to know more details on OAuth 2.0) every\ndetail\
\ that need to obtain access token and use this token for\nrequesting resource on behalf of user will\
\ be described in this\ndocument.\n\n## Terminology\n\n- **User** - Person who has an account inside\
\ Nimble and owner of resources to\n which API provide access\n\n- **Client** - Service that request\
\ a token and want to make requests to the Nimble\n API on behalf of User\n\n- **Authorization\
\ server** - Server that allow User to grant access for Client to use his\n resources\n\n- **Resource\
\ server** - Server that returns User\\'s resources to Client if it was granted\n for access by\
\ User\n\n- **Bearer token** - Token that Client received after User has granted access. Possession\n\
\ of this token allows client to make requests to Resource server in\n order to receive Client\\\
's resources.\n\n## Prerequisites\n\nIn order to create a Client for Nimble API you need to have to\
\ register\nyour application in our DB and get Client Secret and Client Id. Its can\nbe done on the\
\ page with this link:\n.\n\
You probably have done this already.\n\n## Authorization process overview\n\nFor giving you a good\
\ overview of process we will use scheme and give a\nbrief explanation to the each step on scheme.\
\ Steps are shown by the\narrows and has a letters assigned to each step on scheme.\n\n\n\n\n\nLet's go over a scheme step by step.\n\n- **Step A** - You have some product (Client)\
\ that wants to use\n Nimble Data for some purposes. User wants to use Client and you need\n \
\ to retrieve a grant of user to operate the data from Nimble on his\n behalf. So, user has something\
\ that allows to initiate this process\n from Client.\n- **Step B** - Your client open a page\
\ that points to Authorization\n Server providing a params specified on scheme. As a params, you\
\ need\n to send your API key and URI of client to which Authorization Grant\n Code will be\
\ returned. You also need to specify, which Scopes do you\n request from user. You should separate\
\ scopes with comma or plus sign.\n Scopes are: `basic` (User and Company info), `contacts` and\
\ `deals`\n- **Step C** - Auth server using your API Key (Client Key) creates a\n link to which\
\ user will be directed and send a redirect response.\n User will be automatically redirected to\
\ the page where he can put\n his credentials and grant access. Note that now user is on side of\n\
\ Authorization Server.\n- **Step D** - As soon as user finished a process of providing\n \
\ access, Authorization Server takes a redirect URI that you specified\n on step B and sends code\
\ to that URI.\n- **Step E** - Using this code you make a\n `application/x-www-form-urlencoded`\
\ request to the\n Authorization Server where in body you put code retrieved on\n previous step,\
\ your Client Secret, Client Id and Grant Type you want\n to receive. It is always [authorization\
\ code](#tag/Authentication/Requesting-Authorization-Grant-Code). For\n details see [Request access\
\ token](#tag/Authentication/Requesting-Access-Token)\n- **Step F** - If everything is valid then\
\ you will receive response\n from server with Access Token and Refresh Token. Now you are able\
\ to\n do a requests to the Nimble API using Access Token until it valid.\n Using Refresh Token\
\ you will be able to renew this token without\n involving User second time. For details see:\n\
\ [Token refresh](#tag/Authentication/Refresh-token-after-expiration-without-user-input).\n\n##\
\ Requesting Authorization Grant Code\n\nYou should use this request on step B of\n[Authorization\
\ Process](#tag/Authentication/Authorization-process-overview). You need to open a page for user with\
\ this endpoint and\nprovide a Redirect URI on which your handler will be able to catch the\ncode\
\ from Authorization Server that will be returned when User\nsuccessfully grant you a permission to\
\ use Nimble API.\n\n**Endpoint**:\n\n GET https://app.nimble.com/oauth/authorize\n\n**Params**:\n\
\n- ***client_id*** - *required* - Your Client Key from Application Page.\n\n- **redirect_uri**- *required*\
\ - URI where you have a handler who will catch a\n code and finish the Process, see note below.\n\
\n- **response_type** - *required* - must be set to `code`. We don\\'t support Implicit\n Flow,\
\ so `code` is the only available option now.\n\n- **scope** - *required* - there are 3 scopes in\
\ Nimble: Basic (User & Company Info), Contacts and Deals. Send them as basic,contacts,deals of basic+contacts+deals.\n\
\n\n Please note, that main value for redirect URL is specified in\n application settings on\
\ developer portal. `redirect_uri` parameter\n in URL could be used only to overwrite path part\
\ in redirect URL.\n So, `redirect_uri` should have exactly same URI, as specified in\n application\
\ settings.\n\n**Example request**:\n\n GET https://app.nimble.com/oauth/authorize?client_id=5f96b5e9adaxzca93x1213123132&redirect_uri=https%3A%2F%2Fyourportal.com%2Fauth%2Fpassed&response_type=code\n\
\n**Successful response**:\n\n> First, user will be redirected to the page on Authorization Server\n\
> with hostname `https://app.nimble.com/oauth/authorize`\n>\n> As soon as he provided his credentials,\
\ you will receive a request\n> like listed below on your `Redirect URI`:\n>\n> https://yourportal.com/auth/passed?code=LTM4M\
\ \n\n**Error response**:\n\nIf 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.\n>\n> *Example Invalid Authorization Request Redirect*:\n>\n> http://www.myapp.com/oauth?error=invalid_request&error_description=Invalid%20URL\n\
>\nAfter 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.\n\n> *Example Unsuccessful Validation Redirect*:\n>\n> http://www.myapp.com/oauth?error=access_denied&error_descripton=Validation%20errors\n\
>\nIf user click Deny on the grant permission page then another error will be sent.\n> *Example Deny\
\ Consent Redirect*:\n>\n> http://www.myapp.com/oauth?error=access_denied&error_description=User%20denied%20access\n\
\n## Get OAuth Client ID and Secret\nTo get OAuth app credentials, please email api-support@nimble.com\
\ and include the following:\n- App Name\n- App Description\n- Redirect URL for oAuth callback\n\n\
## Requesting Access Token\n\nAs soon as User complete step C your handler will catch step D. You\
\ need\nto listen for redirect on your Redirect URI. **Code returned to you\nisn't access token yet!**\
\ You still need to obtain the authorization\ntoken. Note, that this code is valid for a short period\
\ time and if you\nnot intiate request to access token as soon as you receive a code then\nreceived\
\ code can become invalid and User will need to reinitiate a\nprocess once again. So, on step E you\
\ need to receive access to token\nfor which user granted you.\n\nThe Client should use the authorization\
\ code obtained to request an\naccess token. When requesting an access token, you SHOULD specify\n\
required data as form parameters. Client application secret is needed\nfor client authentication.\
\ When specifying client_id and client_secret\nas form parameters, the `Content-Type` header MUST\
\ be set to\n`application/x-www-form-urlencoded`. Request should be done via HTTPS\nonly.\n\n**Endpoint**:\n\
\n POST https://app.nimble.com/api/oauth/token\n\n**Parameters:**\n\n- **grant_type** - *required*\
\ - must be set to `authorization_code`. You need to receive an Access token.\n- **code** - *required*\
\ - code that you received on step D. This code has a short-valid time, so initiate request for token\
\ as soon as you receive it.\n- **redirect_uri** - *required* - redirect URI for your application.\
\ Should be equal to `redirect_uri`, provided during [Requesting grant code](#tag/Authentication/Requesting-Authorization-Grant-Code)\n\
- **client_id** - *required* - your Client API key.\n- **client_secret** - *required* --- your Client\
\ API secret key.\n\n**Headers**:\n\n- `Content-Type: application/x-www-form-urlencoded; charset=UTF-8`\
\ - *required* - you need to specify this header always\n\n**Example Request**:\n\n POST /api/oauth/token\
\ HTTP/1.1\n Host: app.nimble.com\n Content-Type: application/x-www-form-urlencoded; charset=UTF-8\n\
\n Body : client_id=5f96b5e9a6b7478e15ee574a426aa063&redirect_uri=http%3A%2F%2Flocalhost%3A3000%2Fauth&code=LTM4M&grant_type=authorization_code&client_secret=89bb4ffb4f264bff\n\
\n*Successfull Response JSON*:\n\n``` javascript\n{\n \"access_token\": \"bf086611-9e97-4d11-9cd7-3c86dec0bbd4\"\
,\n \"token_type\": \"bearer\",\n \"expires_in\": 599,\n \"refresh_token\": \"515ac59b-6518-49a2-81d6-54f91ee74c4a\"\
,\n \"scope\": \"basic\"\n}\n```\n\n## API requests using Access Token\n\nNow when we have Access\
\ Token Received you need to store it and use for\nany requests for Nimble Data on behalf of user.\
\ This process described\nin [Making requests tutorial](#tag/Authentication/Tutorial:-Making-authenticated-requests)\n\
\n## Refresh token after expiration without user input\n\nThe application uses the refresh token to\
\ extend the validity of the\naccess token provided with the refresh token. When refreshing an access\n\
token, you should specify required data as a form parameters. Client\napplication secret is needed\
\ for client authentication. `Content-Type`\nheader must be set to `application/x-www-form-urlencoded`.\n\
\nParameters:\n\n- **client_id** - Client identifier used to obtain the authorization code\n- **client_secret**\
\ - Client secret code\n- **grant_type** - Must be set to `refresh_token`\n- **refresh_token** - Refresh\
\ token obtained from the access token request\n- **redirect_uri** - *required* --- redirect URI for\
\ your application. Should be equal to `redirect_uri`, provided during [Request grant code](#tag/Authentication/Requesting-Authorization-Grant-Code)\n\
\nExample Request:\n\n POST /api/oauth/token HTTP/1.1\n Host: https://app.nimble.com/\n Content-Type:\
\ application/x-www-form-urlencoded; charset=UTF-8\n\n client_id=3e8471e7516a0c85ef35ab1d23f1bdf1&client_secret=737d10deba3fd124&grant_type=refresh_token&refresh_token=5f752714eddb07a3e41c2a3311f514e1&redirect_uri=http%3A%2F%2Flocalhost%3A3000%2Fauth\n\
\nExample Response:\n\n``` javascript\n{\n \"access_token\": \"1d7bc7328b402f4826e17607e364bc6a\"\
,\n \"expires_in\": 559,\n \"refresh_token\": \"f35c2165112fda74f79b408cc253485fcdfd888a\"\n\
}\n```\n\n## Examples\n\nFor your convinience we created some examples:\n\n[Python authorization\n\
example](https://github.com/nimblecrm/python-example). Actual code\nimplementation on Python and Tornado\n\
\n[Ruby authorization example](https://github.com/nimblecrm/ruby-example).\nImplementation of authorization\
\ process in Ruby\n\n## Troubleshooting & Feedback\n\nIf you have any problems or want to submit feedback\
\ feel free to go to\nour support forum or email us at \n\n\n## Tutorial:\
\ Making authenticated requests\n\nWhen you've received token, using the process described in\n[Obtaining\
\ API key](https://support.nimble.com/en/articles/822159-generate-an-api-key-to-access-the-nimble-api)\
\ guide, you are\nready to call Nimble API. You can use one of two ways, described below.\nThey both\
\ are equal.\n\n### Authenticating your request with URL parameter\n\nIn order to use this token code\
\ you just add it into URL as request\nparameter with name `access_token`.\n\n**Endpoint**:\n\nAny\
\ of available endpoint of Nimble API\n\n**Params**:\n\nNo matter what request `POST`, `GET` or any\
\ other HTTP method, just add\nan `access_token` as parameter to URL.\n\n- **access_token** - *required*\
\ - put a token for user under this parameter.\n\n**Example Request**:\n\n POST https://api.nimble.com/api/v1/contact?access_token=e0f7b053200672c2ff6ede59c8e2bfc7\n\
\n**Successful Response**:\n\nAll API responses described on their corresponding pages.\n\n### Authenticating\
\ your request with HTTP header\n\nYou can also pass your token in HTTP header `Authorization` in\
\ format:\n`Bearer `.\n\n**Example request**:\n\n PUT /api/v1/contact/4f60a873fcf7b752ed006b7a\
\ HTTP/1.1\n Accept: application/json\n Accept-Encoding: gzip, deflate, compress\n Authorization:\
\ Bearer c0b5f46631455b543c309b8cb18b8dae\n Content-Type: application/json; charset=utf-8\n\n \
\ {\n \"fields\": {\n \"first name\": [\n {\n \
\ \"modifier\": \"\", \n \"value\": \"1name\"\n }\n \
\ ]\n }\n }\n\n\n\n\n\n"
- name: Handling Errors
description: "## API Errors\n\nErrors in Nimble are returned as a JSON dictionary with appropriate HTTP\n\
error codes and following keys:\n\n**message**\n: Message about the error\n\n**code**\n: Extended\
\ error code\n\n### Validation Error\n\nSent on invalid parameters. Returns with HTTP code 409 and\
\ code field\nequal to 245.\n\nThis response looks like common error dictionary:\n\n``` javascript\n\
{\n \"message\": \"You can specify either `keyword` or `query` parameter, not both!\", \n \"\
code\": 245\n}\n```\n\nOn contact creation and update --- additional data is returned.\n\n``` javascript\n\
{\n \"message\": \"Validation errors\",\n \"code\": 245,\n \"errors\": {\n \"first\
\ name\": [{\n \"message\": \"First name or last name field is required for person and\
\ should not be empty\",\n \"field_id\": \"5049f697a694620a07000043\"\n }]\n \
\ }\n}\n```\n\nHere errors are a dictionary, containing information about field that\ncaused the error.\
\ Key is field name and values are extended error\nmessage and unique id of the field that caused\
\ the error.\n\n### Quota Error\n\nSent if user exceeded his quota values. Returns with HTTP code\
\ 402 and\ncode field equal to 108.\n\n``` javascript\n{\n \"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.\", \n \"code\": 108\n}\n```\n\n### Server error\n\
\nSent if unrecoverable Nimble server occurs. Returns with HTTP code 500\nand code field equal to\
\ 107.\n\n``` javascript\n{\n \"message\": \"Internal error handling request\", \n \"code\"\
: 107\n}\n```\n\n### NotFound Error\n\nSent on attempt to get some object by invalid identifier (in\
\ most cases\nidentifier of object is its ID in our database).\n\nThis response will contain dictionary\
\ with **object_type** and **object_id** fields:\n\n``` javascript\n{\n \"object_type\": \"contact\
\ field\",\n \"object_id\": \"111111111111111111111111\"\n}\n```\n"
- name: Contacts
description: "# Contacts details\n\nTypical response to this request is a dictionary with 2 keys (unless\n\
otherwise specified by the specific API): meta and resources.\n\n## Contact resources\n\nThis field\
\ usually contains all data for the contacts you\\'ve requested.\nHere is an example of a Nimble contact\n\
\n``` javascript\n\"resources\": [\n {\n \"updated\": \"2012-09-07T16:49:56+0300\",\n \
\ \"created\": \"2012-09-07T16:49:56+0300\",\n \"fields\": {\n \"description\"\
: [\n {\n \"value\": \"description\",\n \"label\"\
: \"description\",\n \"modifier\": \"other\"\n },\n \
\ {\n \"value\": \"description\",\n \"label\": \"description\"\
,\n \"modifier\": \"linkedin\"\n }\n ],\n \"\
last name\": [\n {\n \"modifier\": \"\",\n \"\
value\": \"Akopyan\",\n \"label\": \"last name\"\n }\n \
\ ],\n \"phone\": [\n {\n \"modifier\": \"mobile\"\
,\n \"value\": \"+7 (917) 202-456-1111\",\n \"label\": \"phone\"\
\n },\n {\n \"modifier\": \"home\",\n \
\ \"value\": \"+7 244 231 84 22\",\n \"label\": \"phone\"\n \
\ }\n ],\n \"URL\": [\n {\n \"modifier\"\
: \"other\",\n \"value\": \"https://nimble.com\",\n \"label\"\
: \"URL\"\n },\n {\n \"modifier\": \"other\",\n \
\ \"value\": \"https://app.nimble.com\",\n \"label\": \"URL\"\
\n }\n ],\n \"source\": [\n {\n \
\ \"modifier\": \"\",\n \"value\": \"csv\",\n \"label\"\
: \"source\"\n }\n ],\n \"address\": [\n {\n \
\ \"modifier\": \"other\",\n \"value\": \"{'city': 'Dushanbe',\
\ 'street': 'First str. 15', 'zip': '54055', 'country': 'Farganistan'}\",\n \"\
label\": \"address\"\n }\n ],\n \"email\": [\n \
\ {\n \"modifier\": \"other\",\n \"value\": \"fake_person@nimble.com\"\
,\n \"label\": \"email\"\n }\n ],\n \"first\
\ name\": [\n {\n \"modifier\": \"\",\n \"value\"\
: \"Amayak\",\n \"label\": \"first name\"\n }\n ]\n \
\ },\n \"object_type\": \"contact\",\n \"id\": \"5049fb849b85f669e40000dc\",\n\
\ \"last_contacted\": {\n \"user_id\": \"5c459c52ceee1868ee3ab41f\",\n \
\ \"deletion_tstamp\": null,\n \"type\": \"LCType\",\n \"object_id\"\
: \"ed5afbee-37f5-db6b-7f71-c7d6b8750bbb\",\n \"tstamp\": \"2019-01-22T21:57:30+0000\"\n\
\ },\n \"avatar_url\": \"https://app.nimble.com/api/contacts/avatars/5049fb849b85f669e40000dc\"\
,\n \"record_type\": \"person\",\n \"creator\": \"Emil Kio\",\n \"children\"\
: [],\n \"tags\": [\n {\n \"tag\": \"csv import\",\n \
\ \"id\": \"5049fa0c9b85f62cb4000639\"\n }\n ],\n \"owner_id\": \"5049f696a694620a0700001c\"\
\n }\n]\n```\n\nHere is a description of the response in detail:\n\n**updated**\n\n: Timestamp\
\ of contact\\'s last update time\n\n**created**\n\n: Timestamp of contact\\'s creation time\n\n\
**fields**\n\n: Dictionary containing contact\\'s fields data. Keys are field names\n and values\
\ are lists of field values. All default contact fields are\n [described here](#tag/Contacts-Fields/Nimble-Default-Fields)\n\
\n**object_type**\n\n: String specifying document type. For contacts it\\'s `contact`.\n\n**id**\n\
\n: Unique contact id in BSON format.\n\n**last_contacted**\n\n: \n\n Information about last\
\ outbound message to this contact (if any). Contains following fields.\n\n : - *user_id* ---\
\ unique id of owner in BSON format\n - *object_id* --- id of object of corresponding type\
\ in BSON\n format\n - *type* --- last contacted provider\\'s type\n -\
\ *tstamp* --- timestamp of last outbound message\n - *deletion_tstamp* --- timestamp of\
\ object deleting\n\n**avatar_url**\n\n: URL of image that can be used as contact\\'s avatar. Value\
\ of null is\n used to indicate that contact has no avatar associated.\n\n**record_type**\n\n:\
\ Type of contact. This can have one of two values: `person` and\n `company`.\n\n**creator**\n\
\n: Name of the person who created the contact\n\n**children**\n\n: For `company` contacts this\
\ field contains list of `person` contacts\n associated with the company.\n\n**tags**\n\n: \n\
\n List of tags associated with the contact. Each tag is represented as a dictionary having following\
\ keys.\n\n : - *tag* --- tag\\'s text\n - *id* --- unique id of tag in BSON format\n\
\n**owner_id**\n\n: Id of the person owning the contact in BSON format\n\n\n## Contact list\n\n\
Contact list request is similar to\n[contact details response](#tag/Contacts/Contacts-details). It\
\ has the\nsame key with resources,\n[described here](#tag/Contacts/Contacts-details/Contact-resources).\
\ Difference is in `meta` key value. For contact listing it\nreturns pagination details.\n"
- name: Contacts Fields
description: "## Legacy contacts metadata\n\nContact\\'s metadata contains information about all basic\
\ and custom\nfields created in Nimble for a user. Below is it\\'s typical structure.\nPlease note\
\ that this listing doesn\\'t contain all metadata as the full\nlist is very big. The typical records\
\ are shown here. All default\ncontact fields are [described here](#tag/Contacts-Fields/Nimble-Default-Fields)\n\
\n``` javascript\n\"contacts_meta\": {\n \"fields\": {\n \"first name\": [\n \
\ {\n \"group\": \"Basic Info\",\n \"name\": \"first name\",\n \
\ \"label\": \"first name\",\n \"modifier\": \"\",\n \"presentation\"\
: {},\n \"id\": \"5049f697a694620a07000043\",\n \"multiples\": false,\n\
\ \"read_only\": false\n }\n ],\n \"email\": [\n \
\ {\n \"group\": \"Contact Info\",\n \"name\": \"email\",\n \
\ \"label\": \"email\",\n \"modifier\": \"other\",\n \"presentation\"\
: {},\n \"id\": \"5049f697a694620a07000065\",\n \"multiples\": true,\n\
\ \"read_only\": false\n },\n {\n \"group\": \"\
Contact Info\",\n \"name\": \"email\",\n \"label\": \"email\",\n \
\ \"modifier\": \"personal\",\n \"presentation\": {},\n \
\ \"id\": \"5049f697a694620a07000064\",\n \"multiples\": true,\n \"\
read_only\": false\n }\n ],\n \"lead status\": [\n {\n \
\ \"group\": \"Lead Details\",\n \"name\": \"lead status\",\n \
\ \"label\": \"lead status\",\n \"modifier\": \"\",\n \"presentation\"\
: {\n \"width\": \"1\",\n \"next_id\": \"5\",\n \
\ \"values\": [\n {\n \"id\": \"1\",\n \
\ \"value\": \"Open\"\n },\n \
\ {\n \"id\": \"2\",\n \"value\": \"Contacted\"\
\n },\n {\n \"id\": \"3\"\
,\n \"value\": \"Qualified\"\n },\n \
\ {\n \"id\": \"4\",\n \"value\"\
: \"Unqualified\"\n }\n ],\n \"type\"\
: \"select-box\"\n },\n \"id\": \"5049f697a694620a0700008d\",\n \
\ \"multiples\": false,\n \"read_only\": false\n }\n ]\n\
\ },\n \"groups\": {\n \"Basic Info\": {\n \"name\": \"Basic Info\",\n \
\ \"order\": [\n \"first name\",\n \"last name\",\n \
\ \"middle name\",\n \"company name\",\n \"title\",\n \
\ \"source\",\n \"last contacted\"\n ],\n \"is_standard\"\
: true,\n \"label\": \"Basic Info\",\n \"type\": \"both\",\n \"id\"\
: \"5049f696a694620a07000031\"\n }\n }\n}\n```\n\nHere is a description of the response\
\ in detail:\n\n**fields**\n\n: Information about the fields in Nimble. Represented by dictionary\n\
\ where keys are fields names, and values are lists containing details\n about all possible\
\ modifications of this field. If field have no\n modifiers (like `first name` on example above),\
\ this list contains\n only one element.\n\n Information stored in dictionaries with following\
\ keys:\n\n : - *group* --- unique name of the group containing this field.\n - *label*\
\ --- unique name representing the field in\n human-readable form.\n - *modifier*\
\ --- name of the field\\'s modifier\n - *id* --- unique id of the field in BSON format\n\
\ - *multiples* - indicates whether field could have multiple\n values (under\
\ different modifiers).\n - *presentation* - dict with the information which should help\n\
\ to display this field on client.\n - *read_only* - if contacts field values\
\ is editable by user\n\n**groups**\n\n: \n\n 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:\n\n : - *id* --- unique id of the group in BSON\
\ format.\n - *order* --- list containing names of the fields as they\n appeared\
\ in group.\n - *name* --- unique name of the group. (Outdated: as we have\n field\
\ name as the key of `groups` dictionary.)\n - *label* --- unique name representing the field\
\ in\n human-readable form.\n - *is_standard* - whether this group belongs to\
\ standard\n Nimble groups.\n - *type* - type (belonging) of group, could be among\
\ `person`,\n `company`, `both`.\n\n\n## Fields metadata\n\nContact\\'s metadata contains\
\ information about all basic and custom\nfields created in Nimble for a user. Below is it\\'s typical\
\ structure.\nAll default contact fields are [described here](#tag/Contacts-Fields/Nimble-Default-Fields)\n\
\n``` javascript\n{\n \"tabs\": [\n {\n \"tab_id\": \"string\",\n \"tab_name\": \"string\"\
,\n \"contact_types\": \"person\",\n \"is_standard\": true,\n \"members\": [\n \
\ {\n \"type\": \"group\",\n \"name\": \"string\",\n \"group_id\": \"\
string\",\n \"logo_id\": \"string\",\n \"fields\": [\n {\n \
\ \"type\": \"field\",\n \"name\": \"string\",\n \"field_id\": \"string\"\
,\n \"modifier\": \"string\",\n \"multiples\": true,\n \"read_only\"\
: true,\n \"field_type\": {\n \"field_kind\": \"string\",\n \
\ \"validation_rule\": {\n \"type\": \"email\"\n }\n \
\ },\n \"presentation\": {\n \"number_type\": \"integer\"\n \
\ },\n \"available_actions\": \"edit_all\"\n }\n ]\n \
\ }\n ],\n \"available_actions\": \"edit_all\"\n }\n ]\n}\n```\n\nHere is a description\
\ of the response in detail:\n\n\n### Tabs\n\n- **tab_id** — unique ID of the tab.\n- **tab_name**\
\ — name representing the tab in human-readable form.\n- **contact_types** — contact types that could\
\ have fields in the tab. Possible values: `person`, `company`.\n- **is_standard** — whether this\
\ tab belongs to standard Nimble tabs.\n- **available_actions** — possible actions: `edit_all`, `rearrange_only`,\
\ `view_only`.\n- **members** — list of tab members. This could include groups and fields without\
\ groups.\n\n### Groups\n\n- **type** — tab member type. It is always \"group\" here.\n- **name**\
\ — name representing the group in human-readable form.\n- **group_id** — unique ID of the group.\n\
- **logo_id** — ID of the logo to display.\n- **is_standard** — whether this group belongs to standard\
\ Nimble groups.\n- **fields** — list of fields contained within the group.\n\n### Fields\n\n- **type**\
\ — tab member type. It is always \"field\" here.\n- **name** — name representing the field in human-readable\
\ form.\n- **field_id** — unique ID of the field.\n- **modifier** — name of the field's modifier.\n\
- **multiples** — indicates whether the field can have multiple values (under different modifiers).\n\
- **read_only** — whether the field is available for editing.\n- **field_type** — dictionary describing\
\ the field type. More details are [described here](#tag/Contacts-Fields/Nimble-Default-Fields/Nimble-Fields-Type).\n\
- **presentation** — dictionary describing how the field should be presented in the Nimble client.\
\ More details are [described here](#tag/Contacts-Fields/Nimble-Default-Fields/Nimble-Fields-Presentation).\n\
- **available_actions** — possible actions: `edit_all`, `edit_choices_only`, `view_only`.\n\n---\n\
\nThe image below shows schema of fields metadata. Blue rectangle - tab,\ngreen rectangle - group,\
\ red rectangle - field. As you can see, fields\ncould be a member of a tab or a group. The same metadata\
\ schema is used for deals metadata.\n\n\n\
\n---\n\n# Nimble Default Fields\n\n\n| Field Name | Type | Multiple Field | Modifiers\
\ | Notes \
\ \
\ \
\ \
\ \
\ |\n|--------------------|---------|------------------|-----------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n\
| first name | string | - | N/A \
\ | \
\ \
\ \
\ \
\ |\n| last name | string\
\ | - | N/A | \
\ \
\ \
\ \
\ \
\ |\n| company name | string | - |\
\ N/A | \
\ \
\ \
\ \
\ \
\ |\n| contact employment | string | + | N/A \
\ | All values are represented as a JSON-encoded strings of dictionaries\
\ with the following keys: `company_name`, `title`, `start_date`, `end_date`. Where `start_date` and\
\ `end_date` are dates indicating the period of employment. These fields are optional; however, at\
\ least one of `company_name` or `title` must have a non-null value. This dictionary should be converted\
\ to a JSON string, and this string should be used as the field's value. |\n| birthday |\
\ string | - | N/A | Format:\
\ MM/DD/YYYY or MM/DD \
\ \
\ \
\ \
\ |\n| domain | string | - \
\ | N/A | The domain field. Example: `nimble.com`.\
\ This field satisfies the following conditions:
- **Unique** within the team. Only one company\
\ record with a particular value is allowed in the whole account.
- **Properly formatted**. No\
\ protocol or path is allowed; it can have up to a 3rd-level domain.
- It can be assigned to **company\
\ records only**. \
\ |\n| phone | string | + | work, home, mobile, main, home fax,\
\ work fax, other | \
\ \
\ \
\ \
\ |\n| email \
\ | string | + | work, personal, other \
\ | \
\ \
\ \
\ \
\ |\n| skype id | string | + \
\ | N/A | \
\ \
\ \
\ \
\ \
\ |\n| twitter | string | + | N/A \
\ | \
\ \
\ \
\ \
\ \
\ |\n| facebook | string | + | N/A \
\ | \
\ \
\ \
\ \
\ |\n| linkedin\
\ | string | + | N/A \
\ | \
\ \
\ \
\ \
\ |\n| google plus | string |\
\ + | N/A | \
\ \
\ \
\ \
\ \
\ |\n| muck rack | string | + | N/A\
\ | \
\ \
\ \
\ \
\ \
\ |\n| threads | string | + | N/A \
\ | \
\ \
\ \
\ \
\ |\n| instagram\
\ | string | + | N/A \
\ | \
\ \
\ \
\ \
\ |\n| tiktok | string | +\
\ | N/A | \
\ \
\ \
\ \
\ \
\ |\n| youtube | string | + | N/A \
\ | \
\ \
\ \
\ \
\ \
\ |\n| foursquare | string | + | N/A \
\ | \
\ \
\ \
\ \
\ |\n| URL\
\ | string | + | work, personal, blog, other \
\ | \
\ \
\ \
\ \
\ |\n| address | address\
\ | + | work, home, other | \
\ \
\ \
\ \
\ \
\ |\n| description | string | + | other,\
\ twitter, facebook, linkedin, google+, foursquare | \
\ \
\ \
\ \
\ \
\ |\n| hubspot | string | - | N/A \
\ | \
\ \
\ \
\ \
\ |\n| annual\
\ revenue | string | - | N/A \
\ | \
\ \
\ \
\ \
\ |\n| # of employees | choice \
\ | - | N/A | \
\ \
\ \
\ \
\ \
\ |\n| rating | choice | - | N/A\
\ | \
\ \
\ \
\ \
\ \
\ |\n| lead status | choice | - | N/A \
\ | \
\ \
\ \
\ \
\ |\n| lead\
\ source | choice | - | N/A \
\ | \
\ \
\ \
\ \
\ |\n| lead type | choice\
\ | - | N/A | \
\ \
\ \
\ \
\ \
\ |\n\n## Deprecated Fields\n\nThe fields `parent company`\
\ and `title` have been deprecated and replaced by the `contact employment` field, which accepts a\
\ **JSON-encoded string** to store employment details.\n\nThe `contact employment` field includes\
\ the following subfields:\n\n- **company_name** (string): Name of the company.\n- **title** (string):\
\ Job title.\n- **start_date** (datetime, optional): Employment start date in MM/YYYY format\n- **end_date**\
\ (datetime, optional): Employment end date in MM/YYYY format (must be null or omitted if the employment\
\ is ongoing).\n- **is_present** (boolean, optional): Indicates if the contact is currently employed\
\ at this company.\n\n### Validation Rules\n\n- **Company Name or Title Required**: At least one of\
\ `company_name` or `title` must be provided.\n\n- **Mutual Exclusivity of `end_date` and `is_present`**:\
\ If `end_date` is provided, `is_present` cannot be `true`.\n\n- **Date Order**: If both `start_date`\
\ and `end_date` are provided, `start_date` must be earlier than `end_date`.\n\n### Examples\n\n\n\
#### Original value (before encoding)\n\n```javascript\n{\n \"company_name\": \"Example Corp\",\n\
\ \"title\": \"Senior Developer\",\n \"start_date\": \"05/2024\"\n}\n```\n\n#### JSON-encoded value\n\
\nBefore sending the value to the API, it must be encoded as a JSON string:\n\n```javascript\n\"{\\\
\"company_name\\\":\\\"Example Corp\\\",\\\"title\\\":\\\"Senior Developer\\\",\\\"start_date\\\"\
:\\\"05/2024\\\"}\"\n```\n\n#### Example request body — full contact employment\n\n```javascript\n\
{\n \"fields\": {\n \"contact employment\": [\n {\n \"value\": \"{\\\"company_name\\\
\":\\\"Example Corp\\\",\\\"title\\\":\\\"Senior Developer\\\",\\\"start_date\\\":\\\"05/2024\\\"\
}\"\n }\n ]\n }\n}\n```\n\n#### Example request body — company name only\n\nIf you only need\
\ to link a person with a company without additional details:\n\n```javascript\n{\n \"fields\": {\n\
\ \"contact employment\": [\n {\n \"value\": \"{\\\"company_name\\\":\\\"Example Corp\\\
\"}\"\n }\n ]\n }\n}\n```\n\n#### Example request body — current and previous companies\n\
\nIf you want to add multiple contact employment values:\n\n```javascript\n{\n \"fields\": {\n \
\ \"contact employment\": [\n {\n \"value\": \"{\\\"company_name\\\":\\\"Old Corp\\\"\
,\\\"title\\\":\\\"Developer\\\",\\\"start_date\\\":\\\"01/2021\\\",\\\"end_date\\\":\\\"04/2024\\\
\"}\"\n },\n {\n \"value\": \"{\\\"company_name\\\":\\\"Example Corp\\\",\\\"title\\\
\":\\\"Senior Developer\\\",\\\"start_date\\\":\\\"05/2024\\\", \\\"is_present\\\": true}\",\n \
\ \"is_primary\": true\n }\n ]\n }\n}\n```\n\n\n\n## Nimble Default Field Tabs\n\n| Tab\
\ Name | Description | Fields \
\ \
\ |\n|------------------------|----------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n\
| Personal Info | Personal contact's details | - first name,
- last\
\ name,
- middle name,
- title,
- parent company,
- birthday
- employment \
\ |\n| Company Info | Extended information\
\ about contact's company | - annual revenue,
- company name,
- domain,
- # of employees\
\ \
\ |\n| Contact Info | How to reach this contact | - phone,
- email,
-\
\ skype id,
- twitter,
- facebook,
- linkedin,
- google+,
- foursquare,
- address,
-\
\ description,
- URL,
- hubspot |\n| Lead Details | Information about contact as lead\
\ | - rating,
- lead stage \
\ |\n| Additional\
\ Lead Fields | Legacy fields | - lead status,
- lead source,
-\
\ lead type \
\ |\n| Extra Info | Contact's extended information \
\ | * Files \
\ |\n\n\n## Nimble\
\ Fields Type\n\nShow data about field type. You can't change it after creation. It is a dictionary\
\ with at least one field - `field_kind`.\n\n- **field_kind** --- represents the type of field in\
\ Nimble. It can have one of the following values:\n\n > - **string** --- simple field with one line\
\ of text\n > - **long_string** --- field containing multiline text\n > - **choice** --- drop-down\
\ list with predefined values, requires additional parameter `values`. Value of the field contains\
\ the id of one of the choice values\n > - **number** --- field with integer or decimal number\n\
\ > - **datetime** --- string formatted in ISO 8601\n > - **boolean** --- field with true/false\
\ value\n > - **address** --- field with address, that allows input of address in Nimble default\
\ format\n > - **user** --- field containing id of the Nimble user\n\nExamples:\n\n``` javascript\n\
\"field_type\": {\n \"field_kind\": \"string\"\n}\n```\n\n``` javascript\n\"field_type\": {\n \
\ \"field_kind\": \"choice\",\n \"values\": {\n \"ordering_type\": \"ordinal\",\n \
\ \"values\": [{\"id\": \"string\", \"value\": \"string\"}]\n }\n}\n```\n\n### Choice Type\n\
\nFields, showing as drop-down lists in Nimble. In metadata they have\n`field_type` equal `choice`.\
\ Also, their metadata contains field\n`values`, representing drop-down content. This field contains\
\ list of\ndictionaries, having two keys:\n\n**id**\n\n: Value, to be stored in field\n\n**value**\n\
\n: String, corresponding to this value\n\nExample:\n\n``` javascript\n{\n\"read_only\": false,\n\
\"field_type\": {\n\"values\": {\n \"ordering_type\": \"ordinal\",\n \"values\": [\n {\n \
\ \"id\": \"1\",\n \"value\": \"Analyst\"\n },\n {\n \"id\": \"2\",\n \"value\"\
: \"Competitor\"\n },\n {\n \"id\": \"3\",\n \"value\": \"Customer\"\n },\n \
\ {\n \"id\": \"4\",\n \"value\": \"Investor\"\n },\n {\n \"id\": \"5\",\n \
\ \"value\": \"Lead\"\n },\n {\n \"id\": \"6\",\n \"value\": \"Partner\"\n },\n\
\ {\n \"id\": \"7\",\n \"value\": \"Press\"\n },\n {\n \"id\": \"8\",\n \
\ \"value\": \"Prospect\"\n },\n {\n \"id\": \"9\",\n \"value\": \"Reseller\"\n\
\ },\n {\n \"id\": \"10\",\n \"value\": \"Other\"\n },\n {\n \"id\": \"\
12\",\n \"value\": \"7\"\n }\n ]\n},\n\"field_kind\": \"choice\"\n},\n\"name\": \"lead type\"\
,\n\"available_actions\": \"edit_choices_only\",\n\"field_id\": \"6023b729ec8d835bb32ee4c9\",\n\"\
modifier\": \"\",\n\"type\": \"field\",\n\"multiples\": false\n}\n```\n\n### Address Type\n\nAll values\
\ represented as dictionary with following keys: `street`,\n`city`, `state`, `zip`, `country`. This\
\ dictionary should be dumped to\nJSON string, and this string should be used as field\\'s value.\n\
\nExample:\n\n``` javascript\n{\n \"type\": \"person\",\n \"fields\": {\n \"address\"\
: [{\n \"value\": \"{\\\"street\\\":\\\"Test\\\", \\\"city\\\":\\\"Testing\\\", \\\"country\\\
\":\\\"Togo\\\"}\",\n \"modifier\": \"other\"\n }]\n }\n}\n```\n\n### User Type\n\
\nField, containing id of the Nimble user. Example of value:\n\n``` javascript\n[\n {\n \"is_primary\"\
: false,\n \"modifier\": \"\",\n \"value\": \"602aaa34f92ea11bb5cebae1\",\n }\n]\n```\n\n##\
\ Nimble Fields Presentation\n\nTo control, how contacts will look in Nimble, special parameter\n\
`presentation` included in fields metadata. Usually it is a dictionary\nwith few fields. You can change\
\ presentation after field creation. Must\nmatch to corresponding field_type. Date and number fields\
\ must have an\nappropriate presentation. There is no presentation for other types\n\n- Date presentation:\n\
\n > - date_format --- strftime-like format template as described in\n > \n\
\ > or null if client should use date format from user settings\n > - ignore_specific_time\
\ --- show if time should be presented in\n > the field. Applicable only if date_format is\
\ None. Must be\n > null if date_format specified\n >\n > Examples:\n >\n > ```\
\ javascript\n > \"presentation\": {\n > \"date_format\": null,\n > \"ignore_specific_time\"\
: false\n > }\n > ```\n >\n > ``` javascript\n > \"presentation\": {\n > \"\
date_format\": \"%Y-%m-%dT%H:%M:%S\",\n > \"ignore_specific_time\": null\n > }\n > ```\n\
\n- Number presentation:\n\n > - number_type --- possible values: \\\"integer\\\", \\\"decimal\\\
\",\n > \\\"percentage\\\", \\\"financial\\\"\n > - fraction_digits --- integer \\>= 1\
\ that shows count of digits\n > after comma. Applicable for decimal and percentage only.\n\
\ >\n > Examples:\n >\n > ``` javascript\n > \"presentation\": {\n > \"number_type\"\
: \"integer\",\n > }\n > ```\n >\n > ``` javascript\n > \"presentation\": {\n >\
\ \"number_type\": \"decimal\",\n > \"fraction_digits\": 2\n > }\n > ```\n >\n \
\ > ``` javascript\n > \"presentation\": {\n > \"number_type\": \"percentage\",\n >\
\ \"fraction_digits\": 1\n > }\n > ```\n >\n > ``` javascript\n > \"presentation\"\
: {\n > \"number_type\": \"financial\"\n > }\n > ```\n"
- name: Contacts Pipelines
- name: Activities
description: Activities management
- name: Tasks
description: Tasks management
- name: Search Contacts
description: "## Basic concepts\n\nNimble Search Engine (NSE) normalizes both indexed values and query\
\ text:\n\n- lowercase conversion\n- accent removal (ASCII folding)\n\nExamples:\n\n- `cAr` -> `car`\n\
- `čar` -> `car`\n- `ČAR` -> `car`\n\n## Advanced search query syntax\n\nAdvanced search query is\
\ a JSON object.\n\nTerminal query example:\n\n``` javascript\n{\"skype id\": {\"is\": \"john.doe\"\
}}\n```\n\nComposite query example:\n\n``` javascript\n{\n \"and\": [\n {\"skype id\": {\"is\"\
: \"john.doe\"}},\n {\"record type\": {\"is\": \"person\"}}\n ]\n}\n```\n\nJoin operators:\n\n\
- `and`\n- `or`\n- `not` (single subquery)\n\nHow to read a query:\n\n- field: what data you search\
\ in (for example `email`, `record type`, `__any`)\n- operator: matching rule (`is`, `contain`, `range`,\
\ etc.)\n- value: value for that operator\n\nGeneric terminal shape:\n\n``` javascript\n{\"\"\
: {\"\": \"\"}}\n```\n\n## Search operators\n\n### Text operators\n\n-\
\ `contain`\n- `not_contain`\n- `starts_with`\n- `is`\n- `is_not`\n- `is_empty`\n- `in`\n\nNotes:\n\
\n- `contain` is full-text matching by normalized tokens.\n- `starts_with` is full-text prefix matching.\n\
- `not_in` exists, but only for specific fields (for example `_id`, some employment fields).\n\n###\
\ Datetime operators\n\n- `in_the_last`\n- `not_in_the_last`\n- `range`\n- `not_in_range`\n- `day_month_range`\n\
- `is_empty`\n\n`in_the_last` / `not_in_the_last` units:\n\n- `second`\n- `day`\n- `week`\n- `month`\n\
- `year`\n\nRange formats:\n\n- date range: `start_date` / `end_date` in `%Y-%m-%d`\n- datetime range:\
\ `start_datetime` / `end_datetime` in RFC3339\n\n### Numeric operators\n\n- `is`\n- `is_not`\n- `is_empty`\n\
- `in`\n- `gt`\n- `gte`\n- `lt`\n- `lte`\n- `range`\n- `not_in_range`\n\n## Synthetic fields\n\nSynthetic\
\ fields are pre-aggregated searchable fields.\nThey are built from multiple source fields and indexed\
\ for fast text search.\n\n### `names` (alias: `name`)\n\nUse `names` when you want to search by a\
\ person/company name only.\n\nSource fields:\n\n- `first_name`\n- `middle_name`\n- `last_name`\n\
- `company_name`\n\n### `__any`\n\nUse `__any` for broad keyword-style lookup across many contact\
\ attributes.\n`names` is effectively a subset of `__any`.\n\nSource fields:\n\n- `first_name`\n-\
\ `middle_name`\n- `last_name`\n- `company_name`\n- `address_work`\n- `address_home`\n- `address_other`\n\
- `email_work`\n- `email_personal`\n- `email_other`\n- `domain`\n- `phone_work`\n- `phone_home`\n\
- `phone_mobile`\n- `phone_main`\n- `phone_other`\n- `phone_fax_home`\n- `phone_fax_work`\n- `skype`\n\
- `description_twitter`\n- `description_facebook`\n- `description_linkedin`\n- `description_gplus`\n\
- `description_fsq`\n- `description_other`\n- `contact_employment`\n\nImportant:\n\n- source fields\
\ above are internal aggregation keys, not query field names;\n- for precise filtering, prefer explicit\
\ fields (for example `email`, `domain`, `address.city`) instead of `__any`.\n\n## Common searchable\
\ fields\n\nThis page is a practical overview. Full default fields metadata is documented here:\n\
[Contacts Fields](#tag/Contacts-Fields/Nimble-Default-Fields)\n\nCommonly used search fields include:\n\
\n- `__any`, `name` / `names`\n- `first name`, `last name`, `company name`, `title`\n- `email`, `phone`,\
\ `domain`, `skype id`\n- `address`, `city`, `state`, `country`, `street`, `zip`\n- `created`, `updated`,\
\ `birthday`, `company last contacted`, `user last contacted`\n- `tag`, `record type`, `_id`, `saved_search`\n\
\n## Record type explained\n\n`record type` controls contact kind:\n\n- `person`: only person contacts\n\
- `company`: only company contacts\n- `all`: both (no type filter)\n\nRecommended usage in advanced\
\ queries:\n\n- choose one full variant:\n - only person contacts: `{\"record type\": {\"is\": \"\
person\"}}`\n - only company contacts: `{\"record type\": {\"is\": \"company\"}}`\n - both persons\
\ and companies: `{\"record type\": {\"is\": \"all\"}}`\n- when you combine filters, place `record\
\ type` as a regular clause in top-level `and`\n\n\n## Field/operator quick matrix\n\nThis table is\
\ intentionally practical (most-used fields). \nFor full searchable catalogue in your account, use\
\ metadata endpoints and fields catalogue.\n\n| Field | Meaning | Supported operators (practical)\
\ |\n|---|---|---|\n| `__any` | broad synthetic full-text field | `contain`, `not_contain`, `starts_with`\
\ |\n| `name` / `names` | synthetic name field | `contain`, `not_contain`, `starts_with`, `is_empty`\
\ |\n| `first name`, `last name`, `email`, `phone`, `domain`, `skype id`, `company name` | common\
\ contact text fields | `is`, `is_not`, `contain`, `not_contain`, `starts_with`, `is_empty`, `in`\
\ |\n| `title`, `company_name` | employment aggregate fields | `is`, `is_not`, `contain`, `not_contain`,\
\ `starts_with`, `is_empty`, `in`, `not_in` |\n| `address` | any address text | `contain`, `not_contain`,\
\ `starts_with`, `is_empty` |\n| `address.city`, `address.state`, `address.country`, `address.street`,\
\ `address.zip` | address components | `is`, `is_not`, `contain`, `not_contain`, `starts_with`, `is_empty`\
\ |\n| `rating` | numeric field | `is`, `is_not`, `is_empty`, `gt`, `gte`, `lt`, `lte`, `range`, `not_in_range`,\
\ `in` |\n| `created`, `updated` | system timestamps | `in_the_last`, `not_in_the_last`, `range`,\
\ `not_in_range` |\n| `birthday` | contact birthday | `in_the_last`, `not_in_the_last`, `range`, `not_in_range`,\
\ `day_month_range`, `is_empty` |\n| `company last contacted`, `user last contacted` | contact activity\
\ timestamps | `is_empty`, `gt`, `gte`, `lt`, `lte`, `range`, `not_in_range`, `in_the_last`, `not_in_the_last`\
\ |\n| `record type` | contact type (`person`, `company`, `all`) | `is` |\n| `_id` | contact id |\
\ `is`, `in`, `not_in` |\n| `tag` | tags | `is`, `is_not`, `is_empty`, `in` |\n| `saved_search` |\
\ saved segment reference | `is` |\n| `reminder` | reminder presence | `is_empty` |\n\nNotes:\n\n\
- `name` is an alias for `names`.\n- `title` and `company_name` are employment-based fields.\n- `company\
\ name` (with space) is a contact field and is different from `company_name` (employment aggregate).\n\
- legacy clients may still send `is` / `is_not` for `names`.\n\n## Query examples\n\n### 1) Filter\
\ by record type (all persons)\n\n``` javascript\n{\"record type\": {\"is\": \"person\"}}\n```\n\n\
### 2) Search by synthetic `names`\n\n``` javascript\n{\"names\": {\"contain\": \"Jon Ferrara\"}}\n\
```\n\n### 3) Broad search by `__any`\n\n``` javascript\n{\"__any\": {\"contain\": \"domain.com\"\
}}\n```\n\n### 4) Exact email + type\n\n``` javascript\n{\n \"and\": [\n {\"email\": {\"is\":\
\ \"jon@nimble.com\"}},\n {\"record type\": {\"is\": \"person\"}}\n ]\n}\n```\n\n### 5) `in` for\
\ multi-value match\n\n``` javascript\n{\n \"email\": {\n \"in\": [\n \"jon@nimble.com\"\
,\n \"jon.ferrara@nimble.com\"\n ]\n }\n}\n```\n\n### 6) Address component search\n\n```\
\ javascript\n{\"address.city\": {\"is\": \"Los Angeles\"}}\n```\n\n### 7) Numeric range\n\n``` javascript\n\
{\"rating\": {\"range\": {\"start\": 2, \"end\": 4}}}\n```\n\n### 8) Date in the last period\n\n```\
\ javascript\n{\n \"created\": {\n \"in_the_last\": {\n \"unit\": \"month\",\n \"quantity\"\
: 3\n }\n }\n}\n```\n\n### 9) Birthday by day/month range (ignore year)\n\n``` javascript\n{\n\
\ \"birthday\": {\n \"day_month_range\": {\n \"start_date\": \"01/03\",\n \"end_date\"\
: \"31/03\"\n }\n }\n}\n```\n\n### 10) Last-contacted range\n\n``` javascript\n{\n \"company\
\ last contacted\": {\n \"range\": {\n \"start_date\": \"2025-01-01\",\n \"end_date\"\
: \"2025-12-31\"\n }\n }\n}\n```\n\n### 11) Tag filter\n\n``` javascript\n{\"tag\": {\"is\": \"\
vip\"}}\n```\n\n### 12) Filter by explicit contact ids\n\n``` javascript\n{\n \"_id\": {\n \"\
in\": [\n \"4f69fb852ab3740c5e000004\",\n \"5e69fb852ab3f40d5e050017\"\n ]\n }\n}\n\
```\n\n### 13) Use saved search inside another query\n\n``` javascript\n{\n \"and\": [\n {\"saved_search\"\
: {\"is\": \"4fc886dc682c4a64dd060062\"}},\n {\"record type\": {\"is\": \"person\"}}\n ]\n}\n\
```\n\n### 14) Complex logic with `and` + `or` + `not`\n\n``` javascript\n{\n \"and\": [\n {\"\
record type\": {\"is\": \"person\"}},\n {\n \"or\": [\n {\"title\": {\"contain\": \"\
Founder\"}},\n {\"company_name\": {\"contain\": \"Nimble\"}}\n ]\n },\n {\n \
\ \"not\": [\n {\"tag\": {\"is\": \"archived\"}}\n ]\n }\n ]\n}\n```\n\n### 15) Companies\
\ only\n\n``` javascript\n{\"record type\": {\"is\": \"company\"}}\n```\n\n### 16) Use `record type`\
\ inside advanced query\n\n``` javascript\n{\n \"and\": [\n {\"record type\": {\"is\": \"person\"\
}},\n {\"tag\": {\"is\": \"vip\"}}\n ]\n}\n```\n\n### 17) Explicitly include both persons and\
\ companies\n\n``` javascript\n{\"record type\": {\"is\": \"all\"}}\n```\n\n## Validation and limits\n\
\n- query nesting depth is limited (max depth: 20)\n- empty string values for occurrences are invalid\n\
- unsupported field/operator combinations return validation errors\n\n## API endpoints\n\nUse contacts\
\ listing endpoints for search:\n\n- `GET /api/v1/contacts`\n- `GET /api/v1/contacts/ids`\n\nSearch\
\ parameters:\n\n- `keyword`: simple search (internally transformed to `{\"__any\": {\"contain\":\
\ \"...\"}}`)\n- `query`: advanced NSE query (JSON, URL-encoded in query string)\n\nBehavior details:\n\
\n- `keyword` and `query` are mutually exclusive\n- if `query` is provided, `record_type` is ignored\n\
\nTip:\n\n- `query` must be URL-encoded JSON in query string.\n\nRequest example:\n\n```text\nGET\
\ /api/v1/contacts?query=%7B%22and%22%3A%5B%7B%22first%20name%22%3A%7B%22contain%22%3A%22Jon%22%7D%7D%2C%7B%22record%20type%22%3A%7B%22is%22%3A%22person%22%7D%7D%5D%7D\n\
```\n\nDecoded query:\n\n``` javascript\n{\n \"and\": [\n {\"first name\": {\"contain\": \"Jon\"\
}},\n {\"record type\": {\"is\": \"person\"}}\n ]\n}\n```\n\n## Response: OK\n\nOn success, listing\
\ endpoints return standard contact-list format with:\n\n- `resources`\n- `meta` (`page`, `pages`,\
\ `per_page`, `total`)\n\nSee contact resource format here:\n[Contacts details](#tag/Contacts/Contacts-details)\n\
\n## Response: Errors\n\nPossible error:\n\n- `validation-error`\n"
- name: Users
description: User management
- name: Company
description: Company management
- name: Deals Fields
description: Deals fields groups and tabs management
- name: Deals
description: Deals management
- name: Deals Pipelines Fields
description: Pipelines fields management
- name: Deals Pipelines
description: Pipelines management
x-tagGroups:
- name: Guides
tags:
- Authentication
- Handling Errors
- name: API Reference
tags:
- Users
- Contacts
- Contacts Fields
- Contacts Pipelines
- Search Contacts
- Activities
- Tasks
- Deals
- Deals Fields
- Deals Pipelines
- Deals Pipelines Fields
- Messages
paths:
/api/v1/myself:
get:
description: Returns information about authenticated user. User_id from this response can be used
to assign different Nimble entities to this user. Such as tasks, contacts, etc.
operationId: get-myself
summary: Current user info
tags:
- Users
responses:
'200':
content:
application/json:
schema:
properties:
company_id:
type: string
example: 4c2118ad54397f271b000000
company_size:
type: integer
example: 3
email:
type: string
example: some@user.com
name:
type: string
example: John Doe
user_id:
type: string
example: 4f2acc3142a053dda595f00b
required:
- user_id
- company_id
- email
- name
- company_size
type: object
description: ''
/api/v1/contacts:
delete:
description: Deletes a list of contacts by specified advanced search query. Requires bulk delete
permission for authenticated user.
operationId: delete-contacts-list-2
summary: Delete list of contacts
tags:
- Contacts
parameters:
- description: Delete all contacts where fields are containing value from this parameter
in: query
name: keyword
schema:
items:
type: string
type: array
- description: 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.
in: query
name: query
schema:
type: string
- description: Delete all contacts with provided record_type. This parameter could be combined with
keyword parameter in order to delete contacts of specific record_type
in: query
name: record_type
schema:
default: all
enum:
- person
- company
- all
type: string
- description: check query's contacts are editable
in: query
name: preflight_checks
schema:
default: false
type: boolean
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Contacts.ContactsRemovedResponse'
description: ''
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.NotFoundError'
description: ''
'406':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.PreflightCheckFailures'
description: ''
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
description: ''
get:
description: 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.
operationId: list-contacts
summary: Contact List
tags:
- Contacts
parameters:
- description: 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
in: query
name: keyword
schema:
type: string
- description: Specifies a comma separated list of fields to return. If this parameter is excluded,
all fields will be returned
in: query
name: fields
schema:
type: string
- description: Specifies whether tags should be included in the results.
in: query
name: tags
schema:
default: true
type: boolean
- description: True if return last contacted information, False otherwise
in: query
name: last_contacted (DEPRECATED; use contexts)
schema:
default: true
type: boolean
- description: 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.
in: query
name: sort
schema:
items:
type: string
type: array
- description: Specifies query for contacts advanced search. Please note, that this parameter not
compatible with parameters record_type and keyword
in: query
name: query
schema:
items:
type: string
type: array
- in: query
name: record_type
schema:
default: all
enum:
- person
- company
- all
type: string
- description: Specifies which page to display
in: query
name: page
schema:
default: 1
type: integer
- description: Specifies the number of items to return per page of results.
in: query
name: per_page
schema:
default: 30
type: integer
- name: files_data (DEPRECATED; use contexts)
description: if response should include the contacts files in this listing
deprecated: true
in: query
schema:
default: false
type: boolean
- name: contexts
description: |
comma-separated additional contexts that should be returned with in this contact
in: query
schema:
$ref: '#/components/schemas/Contacts.ContactViewContextKinds'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Contacts.ContactsListing'
description: ''
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
description: ''
/api/v1/contacts/ids:
get:
description: Has same parameters as a regular contacts list, but returns only contact ids. Works
faster than regular contact list.
operationId: list-contacts-ids
summary: Contact ids list
tags:
- Contacts
parameters:
- description: 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
in: query
name: keyword
schema:
type: string
- description: Specifies a comma separated list of fields to return. If this parameter is excluded,
all fields will be returned
in: query
name: fields
schema:
type: string
- description: Specifies whether tags should be included in the results.
in: query
name: tags
schema:
default: true
type: boolean
- description: True if return last contacted information, False otherwise
in: query
name: last_contacted
schema:
default: true
type: boolean
- description: 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.
in: query
name: sort
schema:
items:
type: string
type: array
- description: Specifies query for contacts advanced search. Please note, that this parameter not
compatible with parameters record_type and keyword
in: query
name: query
schema:
items:
type: string
type: array
- in: query
name: record_type
schema:
default: all
enum:
- person
- company
- all
type: string
- description: Specifies which page to display
in: query
name: page
schema:
default: 1
type: integer
- description: Specifies the number of items to return per page of results.
in: query
name: per_page
schema:
default: 30
type: integer
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Contacts.ContactsIdsListing'
description: ''
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
description: ''
/api/v1/contact:
get:
description: Returns a list of contacts for the specified identifiers
operationId: list-contacts-for-identifiers
summary: Returns standard contact listings
tags:
- Contacts
parameters:
- description: A list of contact ids (max 30), separated by a comma
in: query
name: id
required: true
schema:
type: string
- description: Field names to retrieve, otherwise all fields will be retrieved
in: query
name: fields
schema:
type: string
- description: True if include fields matadata into response, False otherwise
in: query
name: meta
schema:
type: boolean
- description: True if return tags information, False otherwise
in: query
name: tags
schema:
type: boolean
- description: True if return last contacted information, False otherwise
in: query
name: last_contacted (DEPRECATED, use contexts)
schema:
type: boolean
- name: contexts
description: |
comma-separated additional contexts that should be returned with in this contact
in: query
schema:
$ref: '#/components/schemas/Contacts.ContactViewContextKinds'
responses:
'200':
content:
application/json:
schema:
properties:
contacts_meta:
$ref: '#/components/schemas/Contacts.FieldsMetadata'
resources:
items:
$ref: '#/components/schemas/Contacts.ContactView'
type: array
required:
- resources
type: object
description: ''
post:
description: 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.
operationId: post-contact
summary: Create new contact
tags:
- Contacts
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Contacts.CreateContactRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Contacts.ContactView'
description: Contact successfully created
'402':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.PaymentError'
description: ''
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
description: ''
/api/v1/contact/{contact_id}:
delete:
description: Deletes contact
operationId: delete-contact
summary: Delete contact by id
tags:
- Contacts
parameters:
- description: deletion method to use. 'regular' will return error if there are relations that avoid
deletion, 'force' will delete contacts with relations (like exit sequence)
in: query
name: deletion_method
schema:
type: string
enum:
- regular
- force
default: regular
- description: when true, remove all email list entries whose email address matches any email of
the deleted contact
in: query
name: cleanup_email_lists
schema:
type: boolean
default: false
responses:
'200':
description: Contact successfully deleted
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ForbiddenError'
description: Cannot update the contact because of privacy settings violation
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.NotFoundError'
description: ''
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
description: ''
get:
description: Returns contact
operationId: get-contact
summary: Returns contact data by its id.
tags:
- Contacts
parameters:
- description: Field names to retrieve, otherwise all fields will be retrieved
in: query
name: fields
schema:
type: string
- description: True if include fields matadata into response, False otherwise
in: query
name: meta
schema:
type: boolean
- description: True if return tags information, False otherwise
in: query
name: tags
schema:
type: boolean
- description: True if return last contacted information, False otherwise
in: query
name: last_contacted (DEPRECATED, use contexts)
schema:
type: boolean
- description: True if return leads pipeline info, False otherwise
in: query
name: leads_data (DEPRECATED, use contexts)
schema:
default: true
type: boolean
- name: contexts
description: |
comma-separated additional contexts that should be returned with in this contact
in: query
schema:
$ref: '#/components/schemas/Contacts.ContactViewContextKinds'
responses:
'200':
content:
application/json:
schema:
properties:
contacts_meta:
$ref: '#/components/schemas/Contacts.FieldsMetadata'
resources:
items:
$ref: '#/components/schemas/Contacts.ContactView'
type: array
required:
- resources
type: object
description: ''
parameters:
- description: id of a contact to operate on
in: path
name: contact_id
required: true
schema:
type: string
put:
description: Updates contact
operationId: put-contact
summary: Updates contact by its id.
tags:
- Contacts
parameters:
- description: '`1` if replace fields instead of extending it, otherwise extend'
in: query
name: type
schema:
enum:
- '0'
- '1'
type: string
- description: True if return leads pipeline info, False otherwise
in: query
name: leads_data
schema:
default: true
type: boolean
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Contacts.ContactUpdateRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Contacts.ContactView'
description: ''
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ForbiddenError'
description: the calling user does not have permissions to perform that action
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.NotFoundError'
description: ''
'406':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.NotAcceptableError'
description: we can't update contact because it will invisible or not editable after
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
description: ''
/api/v1/contacts/metadata:
get:
description: (DEPRECATED) This method return all available metadata for company's fields/groups.
operationId: list-contacts-fields-metadata
summary: (D) List contacts fields metadata
deprecated: true
tags:
- Contacts
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Contacts.FieldsMetadata'
description: Successful execution
/api/v1/contacts/fields:
get:
description: Return all available metadata for company's fields
operationId: list-company-contacts-fields
summary: List all available metadata for company fields
tags:
- Contacts Fields
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Fields.ContactsFieldsMetadata'
description: fields metadata
post:
description: Create new field
operationId: post-contact-field
summary: Create new field
tags:
- Contacts Fields
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Fields.CreateFieldRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Fields.ContactFieldsTab'
description: ''
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
description: invalid request
/api/v1/contacts/fields/{field_id}:
delete:
description: Deletes field by id
operationId: delete-contact-field
summary: Delete contact field by id
tags:
- Contacts Fields
parameters:
- in: query
name: preflight_checks
required: true
schema:
type: boolean
responses:
'200':
description: Successful deleted
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.NotFoundError'
description: field not found
'406':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.PreflightCheckFailures'
description: if preflight_checks is true and field is used in contacts
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
description: invalid request
parameters:
- in: path
name: field_id
required: true
schema:
type: string
put:
description: Updates existing field
operationId: put-contact-field
summary: Update existing field by id
tags:
- Contacts Fields
requestBody:
content:
application/json:
schema:
properties:
group_id:
description: If not null, move field to specified group. Null if remove field from grooup
nullable: true
type: string
insert_after:
description: If not null, move field after another field or group with specified id.
If null, then moved field to be the first one
nullable: true
type: string
name:
maxLength: 50
minLength: 1
type: string
presentation:
$ref: '#/components/schemas/Fields.FieldPresentation'
tab_id:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Fields.ContactFieldsTab'
description: field updated
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.NotFoundError'
description: field not found
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
description: invalid request
/api/v1/contacts/fields/groups:
post:
description: Create new fields group
operationId: create-contacts-fields-group
summary: Create new contacts fields group
tags:
- Contacts Fields
requestBody:
content:
application/json:
schema:
properties:
insert_after:
description: 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
nullable: true
type: string
logo_id:
type: string
name:
maxLength: 50
minLength: 1
type: string
tab_id:
type: string
required:
- name
- tab_id
- logo_id
- insert_after
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Fields.ContactFieldsTab'
description: ''
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
description: invalid request
/api/v1/contacts/fields/groups/{group_id}:
delete:
description: Deletes group by id
operationId: delete-contacts-fields-group
summary: Delete contacts fields group by id
tags:
- Contacts Fields
parameters:
- in: query
name: preflight_checks
required: true
schema:
type: boolean
responses:
'200':
description: Successful deleted
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.NotFoundError'
description: ''
'406':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.PreflightCheckFailures'
description: if preflight_checks is true and any field in group is used
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
description: invalid request
parameters:
- in: path
name: group_id
required: true
schema:
type: string
put:
description: Updates existing fields group
operationId: put-contacts-fields-group
summary: Update contacts fields group by id
tags:
- Contacts Fields
requestBody:
content:
application/json:
schema:
properties:
insert_after:
description: If not null, move group after another field or group with specified id.
If null, then move group to the first position
nullable: true
type: string
logo_id:
type: string
name:
maxLength: 50
minLength: 1
type: string
tab_id:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Fields.ContactFieldsTab'
description: group updated
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.NotFoundError'
description: group not found
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
description: invalid request
/api/v1/contacts/fields/tabs:
post:
description: Create new fields tabs
operationId: post-contacts-fields-tab
summary: Create new contacts fields tab
tags:
- Contacts Fields
requestBody:
content:
application/json:
schema:
properties:
contact_types:
items:
$ref: '#/components/schemas/Contacts.ContactType'
type: array
insert_after:
description: If not null, inserts a new tab after another tab with specified id. If
null, then tab is inserted as the first one
nullable: true
type: string
tab_name:
maxLength: 50
minLength: 1
type: string
required:
- tab_name
- contact_types
- insert_after
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Fields.ContactFieldsTab'
description: ''
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
description: invalid request
/api/v1/contacts/fields/tabs/{tab_id}:
delete:
description: Deletes tab by id
operationId: delete-contacts-tab-by-id
summary: Delete contacts tab by id
tags:
- Contacts Fields
parameters:
- in: query
name: preflight_checks
required: true
schema:
type: boolean
responses:
'200':
description: Successful deleted
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.NotFoundError'
description: tab not found
'406':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.PreflightCheckFailures'
description: if preflight_checks is true and at least one field in tab used in contacts
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
description: invalid request
parameters:
- in: path
name: tab_id
required: true
schema:
type: string
put:
description: Updates existing fields tab
operationId: put-contacts-tab-by-id
summary: Update contacts fields tab by id
tags:
- Contacts Fields
requestBody:
content:
application/json:
schema:
properties:
contact_types:
$ref: '#/components/schemas/Contacts.ContactType'
insert_after:
description: Moves tab after another tab with specified id. If null, then move tab to
the first position
nullable: true
type: string
tab_name:
maxLength: 50
minLength: 1
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Fields.ContactFieldsTab'
description: tab updated
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.NotFoundError'
description: tab not found
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
description: invalid request
/api/v1/contacts/fields/{field_id}/choices:
post:
description: Create choice for field
operationId: post-contact-choice-field
summary: Create choice for field
parameters:
- in: path
name: field_id
schema:
type: string
required: true
tags:
- Contacts Fields
requestBody:
content:
application/json:
schema:
properties:
id:
type: string
insert_after:
description: 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
nullable: true
type: string
value:
type: string
required:
- id
- value
- insert_after
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Fields.ContactFieldsTab'
description: choice created
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.NotFoundError'
description: field not found
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
description: invalid request
/api/v1/contacts/fields/{field_id}/choices/{id}:
delete:
description: Deletes choice by id
operationId: delete-contact-choice-field
summary: Delete contact choice by id
tags:
- Contacts Fields
parameters:
- in: query
name: preflight_checks
required: true
schema:
type: boolean
- in: path
name: field_id
schema:
type: string
required: true
- in: path
name: id
schema:
type: string
required: true
responses:
'200':
content:
application/json:
schema:
properties:
tabs:
items:
$ref: '#/components/schemas/Fields.ContactFieldsTab'
type: array
description: Successful deleted
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.NotFoundError'
description: choice not found
'406':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.PreflightCheckFailures'
description: if preflight_checks is true and choise is used in any contacts
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
description: invalid request
parameters:
- in: path
name: id
required: true
schema:
type: string
put:
parameters:
- in: path
name: field_id
schema:
type: string
required: true
- in: path
name: id
schema:
type: string
required: true
description: Updates choise
operationId: put-contacts-field-choice
summary: Update field choice
tags:
- Contacts Fields
requestBody:
content:
application/json:
schema:
properties:
id:
type: string
insert_after:
description: If not null, move choice after another choice with specified id. If null,
then moved choice to be the first one
nullable: true
type: string
value:
type: string
required:
- id
responses:
'200':
content:
application/json:
schema:
properties:
tabs:
items:
$ref: '#/components/schemas/Fields.ContactFieldsTab'
type: array
description: choice updated
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.NotFoundError'
description: choice or field not found
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
description: invalid request
/api/v1/contact/{contact_id}/field:
delete:
parameters:
- in: path
name: contact_id
schema:
type: string
required: true
description: delete is_primary mark from field
operationId: delete-primary-mark-from-contact-field
summary: Delete is_primary mark from field
tags:
- Contacts Fields
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Fields.UpdateIsPrimaryRequest'
required: true
responses:
'200':
description: success
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.NotFoundError'
description: field not found
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
description: ''
put:
description: mark field with is_primary flag
operationId: put-primary-mark-to-contact-field
summary: Mark field with is_primary flag
parameters:
- in: path
name: contact_id
schema:
type: string
required: true
tags:
- Contacts Fields
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Fields.UpdateIsPrimaryRequest'
required: true
responses:
'200':
description: success
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.NotFoundError'
description: field not found
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
description: ''
/api/v1/contacts/notes:
post:
description: Creates a note on one or more contacts. At least one contact id is required as Nimble
currently doesn't support notes without contacts.
operationId: post-contact-note
summary: Create contacts note
tags:
- Contacts
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Contacts.ContactNoteSpec'
required: true
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/Contacts.ContactNote'
description: Note created successfully.
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
description: ''
/api/v1/contacts/notes/{note_id}:
delete:
description: delete contact note
operationId: delete-contact-note
summary: Delte contact note by id
tags:
- Contacts
responses:
'200':
content:
application/json:
schema:
properties:
id:
type: string
required:
- id
type: object
description: ''
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.NotFoundError'
description: ''
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
description: ''
get:
description: return single note
operationId: get-contact-note
summary: Returns note by id.
tags:
- Contacts
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Contacts.ContactNote'
description: ''
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.NotFoundError'
description: ''
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
description: ''
parameters:
- in: path
name: note_id
required: true
schema:
type: string
post:
description: create contact note
operationId: post-contact-note-with-id
summary: Create contact note with id
tags:
- Contacts
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Contacts.ContactNoteSpec'
required: true
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/Contacts.ContactNote'
description: ''
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.NotFoundError'
description: ''
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
description: ''
put:
description: update contact note
operationId: put-contact-note
summary: Update contact note by id
tags:
- Contacts
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Contacts.ContactNoteSpec'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Contacts.ContactNote'
description: ''
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.NotFoundError'
description: ''
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
description: ''
/api/v1/contacts/{contact_id}/notes:
get:
description: Returns a list of notes for the specified contact
operationId: list-contacts-contact-notes
summary: List contact notes
tags:
- Contacts
parameters:
- in: query
name: page
schema:
type: integer
- in: query
name: per_page
schema:
type: integer
responses:
'200':
content:
application/json:
schema:
properties:
meta:
properties:
has_more:
type: boolean
page:
type: integer
pages:
type: integer
per_page:
type: integer
total:
type: integer
required:
- per_page
- total
- pages
- page
- has_more
type: object
resources:
items:
$ref: '#/components/schemas/Contacts.ContactNote'
type: array
required:
- meta
- resources
type: object
description: ''
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
description: ''
post:
description: Creates a note attached to the contact specified in the URL.
operationId: post-contact-note-for-contact
summary: Create a contact note
tags:
- Contacts
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Contacts.SingleContactNoteSpec'
required: true
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/Contacts.ContactNote'
description: Note created successfully.
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.NotFoundError'
description: Contact not found.
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
description: Invalid request.
parameters:
- in: path
name: contact_id
required: true
schema:
type: string
/api/v1/activities:
get:
description: Get all activities that match query parameters.
operationId: list-activities
summary: Activities listing
tags:
- Activities
parameters:
- description: |
Indicates a direction of the query. `pending` -- to get future activities, `past` -- to get old activities.
in: query
name: direction
required: true
schema:
enum:
- pending
- past
type: string
- description: Indicates how many activities show per page. Can't be set with untill_tstamp
in: query
name: limit
schema:
type: integer
- description: List of activity types to return. `Default:` return activities of all types
explode: false
in: query
name: types
style: form
schema:
items:
type: string
type: array
- description: List of contacts for which to select activities.
explode: false
in: query
name: contacts
style: form
schema:
items:
type: string
type: array
- description: List of deals for which to select activities.
explode: false
in: query
name: deals
style: form
schema:
items:
type: string
type: array
- description: List of users for which to select activities.
explode: false
in: query
name: users
style: form
schema:
items:
type: string
type: array
- description: True for only completed activities, False for uncompleted.
in: query
name: completed
schema:
type: boolean
- description: List of tags to filter by.
explode: false
in: query
name: tags
style: form
schema:
items:
type: string
type: array
- description: Show activities before or after that timestamp (depending on the `direction`).
in: query
name: next_tstamp
schema:
type: string
- description: Show activities before or after that id (depending on the `direction`).
in: query
name: next_activity_id
schema:
type: string
- description: We will sellect activities until we don't met this date. Can't be set with limit
in: query
name: until_tstamp
schema:
type: string
- description: List of calendar ids to get related events.
explode: false
in: query
name: events__calendar_ids
style: form
schema:
items:
type: string
type: array
- description: status of calls which to select
in: query
name: calls__resolution
schema:
$ref: '#/components/schemas/Calls.CallResolutionSpec'
- description: |
When true, includes `meta.total` — an approximate count of all activities matching
the query filters. Intended for "Select All"
bulk-delete UX. Omit or set to false for regular listing to avoid extra DB queries.
in: query
name: include_total
schema:
type: boolean
default: false
- description: |
Filter activities to only those created by steps of the given sequence. Must be a 24-character hexadecimal MongoDB ObjectId identifying the sequence. Can be combined with `contacts`, `deals`, `users`, `completed`, and `tags` filters.
in: query
name: sequence_id
schema:
type: string
format: ObjectId
example: 507f1f77bcf86cd799439011
responses:
'200':
content:
application/json:
schema:
properties:
activities:
description: List of activities that match query parameters.
items:
$ref: '#/components/schemas/Activities.Activity'
type: array
next_page:
description: Url-encode these arguments and add them to the next request to retrieve
the next page.
nullable: true
type: object
meta:
description: Metadata about the result set. `total` is present only when `include_total=true`.
properties:
total:
description: Approximate total count of activities matching the filters. Present
only when `include_total=true` was requested.
type: integer
type: object
required:
- activities
- next_page
- meta
type: object
description: ''
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
description: ''
/api/v1/tasks:
post:
description: Creates a task. Associate contacts through `related.contacts`; `related_to` is a legacy
response field and is not accepted by this endpoint.
operationId: post-task
summary: Create new task
tags:
- Tasks
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Tasks.NewTaskSpecification'
required: true
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/Tasks.Task'
description: Returns task after successful execution.
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.NotFoundError'
description: Raising in case the contact does not exist
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
description: ''
/api/v1/contacts/{contact_id}/tags:
parameters:
- in: path
name: contact_id
required: true
schema:
type: string
put:
description: sets tags for a specified contact to a given set
operationId: put-contact-tags
summary: Assign tags to contact
tags:
- Contacts
requestBody:
content:
application/json:
schema:
properties:
tags:
items:
type: string
type: array
required:
- tags
type: object
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Contacts.ContactView'
description: tags were set successfully
'403':
description: contact is not editable by the privacy setting
'404':
description: contact not found
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
description: ''
/api/v1/contacts/proceedings_providers:
get:
description: Returns a list of user-available, contact proceeding types. Proceeding is a business
activity, for example, a new deal closed, task assigned, or a note added to a contact
operationId: list-contacts-proceeding-providers
summary: List contacts proceeding providers
tags:
- Contacts
responses:
'200':
content:
application/json:
schema:
properties:
providers:
items:
$ref: '#/components/schemas/Proceedings.ProceedingProvider'
type: array
required:
- providers
type: object
description: ''
/api/v1/contacts/{contact_id}/proceedings:
get:
description: Get all proceedings that match query parameters.
operationId: list-contact-proceedings
summary: List contact proceedings
tags:
- Contacts
parameters:
- description: |
Indicates a direction of the query. `pending` -- to get future proceedings, `past` -- to get old proceedings.
in: query
name: direction
required: true
schema:
enum:
- pending
- past
type: string
- description: Indicates how many proceedings show per page
in: query
name: limit
required: true
schema:
type: integer
- description: List of proceedings types to return. `Default:` return proceedings of all types.
You can obtain available types by requesting `Contacts proceeding providers` route
in: query
name: types
schema:
items:
type: string
enum:
- contact_note
- contact_attachment
- message
- webform_response
- task
- call
- event
- deal
- new_deal
type: array
- description: Show proceedings before or after that timestamp (depending on the `direction`).
in: query
name: next_tstamp
schema:
type: string
- description: 'Show proceedings before or after that proceeding id, eg: `new_deal|777f4444444d4fc4ef44ea44`
(depending on the `direction` param).'
in: query
name: next_id
schema:
type: string
- description: Will fetch completed proceedings for true, false for uncompleted, for example completed
deals.
in: query
name: completed
schema:
type: boolean
- description: Search query to filter among contacts notes
in: query
name: notes__search_query
schema:
type: string
responses:
'200':
content:
application/json:
schema:
properties:
next_page:
description: Url-encode these arguments and add them to the next request to retrieve
the next page.
nullable: true
type: object
proceedings:
description: List of proceedings that match query parameters.
items:
$ref: '#/components/schemas/Proceedings.Proceeding'
type: array
required:
- proceedings
- next_page
type: object
description: ''
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.NotFoundError'
description: contact not found
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
description: ''
parameters:
- in: path
name: contact_id
required: true
schema:
type: string
/api/v1/contacts/pipelines:
get:
description: Returns a list pipelines available to view for the requesting user
operationId: list-available-contacts-pipelines
summary: List contacts pipelines
tags:
- Contacts Pipelines
responses:
'200':
content:
application/json:
schema:
properties:
pipelines:
items:
$ref: '#/components/schemas/Contacts.LeadsPipeline'
type: array
required:
- pipelines
type: object
description: ''
/api/v2/leads/{lead_id}/{pipeline_id}/successful:
parameters:
- in: path
name: lead_id
required: true
schema:
type: string
- in: path
name: pipeline_id
required: true
schema:
type: string
post:
description: Exit lead from a pipeline successfully
operationId: mark-lead-exited-successful
summary: Exit lead from pipeline successfully
tags:
- Leads
- Contacts Pipelines
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Contacts.ExitLeadSuccessfullyRequest'
required: true
responses:
'200':
description: updated lead (contact)
content:
application/json:
schema:
$ref: '#/components/schemas/Contacts.ContactView'
'404':
description: lead or pipeline couldn't be found
'406':
description: operation is invalid (e.g., contact isn't editable or transition itself violates
certain rules)
put:
description: Updates the "exit" transition with new notes and/or actual_exit_date
operationId: put-lead-exit-successful
summary: Update the 'successful exit' transition
tags:
- Leads
- Contacts Pipelines
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Contacts.ExitLeadSuccessfullyRequest'
required: true
responses:
'200':
description: updated lead (contact)
content:
application/json:
schema:
$ref: '#/components/schemas/Contacts.ContactView'
'404':
description: lead or pipeline couldn't be found
'406':
description: operation is invalid (e.g., contact isn't editable or transition itself violates
certain rules)
/api/v2/leads/{lead_id}/{pipeline_id}/unsuccessful:
parameters:
- in: path
name: lead_id
required: true
schema:
type: string
- in: path
name: pipeline_id
required: true
schema:
type: string
post:
description: Exit lead from a pipeline unsuccessfully
operationId: mark-lead-exited-unsuccessfully
summary: Exit lead from a pipeline unsuccessfully
tags:
- Leads
- Contacts Pipelines
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Contacts.ExitLeadUnsuccessfullyRequest'
required: true
responses:
'200':
description: updated lead (contact)
content:
application/json:
schema:
$ref: '#/components/schemas/Contacts.ContactView'
'404':
description: lead or pipeline couldn't be found
'406':
description: operation is invalid (e.g., contact isn't editable or transition itself violates
certain rules)
put:
description: Updates the "exit" transition with new notes and/or actual_exit_date and/or lost_reason
operationId: put-lead-exit-unsuccessful
summary: Update the 'unsuccessful exit' transition
tags:
- Leads
- Contacts Pipelines
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Contacts.ExitLeadUnsuccessfullyRequest'
required: true
responses:
'200':
description: updated lead (contact)
content:
application/json:
schema:
$ref: '#/components/schemas/Contacts.ContactView'
'404':
description: lead or pipeline couldn't be found
'406':
description: operation is invalid (e.g., contact isn't editable or transition itself violates
certain rules)
/api/v2/leads/{lead_id}/{pipeline_id}/move:
parameters:
- in: path
name: lead_id
required: true
schema:
type: string
- in: path
name: pipeline_id
required: true
schema:
type: string
post:
description: Move lead to a stage within the pipeline. You can use this operation to enter pipeline
for the first time.
operationId: move-lead
summary: Move lead to a pipeline stage
tags:
- Leads
- Contacts Pipelines
requestBody:
content:
application/json:
schema:
type: object
properties:
stage_id:
type: string
description: the id of a target stage
required: true
responses:
'200':
description: updated lead (contact)
content:
application/json:
schema:
$ref: '#/components/schemas/Contacts.ContactView'
'404':
description: lead or pipeline couldn't be found
'406':
description: operation is invalid (e.g., contact isn't editable or transition itself violates
certain rules)
/api/v2/leads/{lead_id}/{pipeline_id}/undo:
parameters:
- in: path
name: lead_id
required: true
schema:
type: string
- in: path
name: pipeline_id
required: true
schema:
type: string
post:
description: Undo a recent lead transition to won or lost stage
operationId: undo-lead-transition
summary: Undo lead won/lost transition
tags:
- Leads
- Contacts Pipelines
responses:
'200':
description: updated lead (contact)
content:
application/json:
schema:
$ref: '#/components/schemas/Contacts.ContactView'
'404':
description: lead or pipeline couldn't be found
'406':
description: operation is invalid (e.g., contact isn't editable or transition itself violates
certain rules)
/api/v2/leads/{lead_id}/{pipeline_id}:
parameters:
- in: path
name: lead_id
required: true
schema:
type: string
- in: path
name: pipeline_id
required: true
schema:
type: string
delete:
description: Clear all leads transitions in the current pipeline "run"
operationId: delete-lead-transitions
summary: Clear leads transitions
tags:
- Leads
- Contacts Pipelines
responses:
'200':
description: updated lead (contact)
content:
application/json:
schema:
$ref: '#/components/schemas/Contacts.ContactView'
'404':
description: lead or pipeline couldn't be found
'406':
description: operation is invalid (e.g., contact isn't editable or transition itself violates
certain rules)
/api/v2/deals:
get:
description: Retrieves list of all user deals
operationId: list-user-deals
summary: List all user's deals
tags:
- Deals
parameters:
- name: sort
in: query
required: true
schema:
type: string
format: field:order
- name: limit
in: query
schema:
type: integer
responses:
'200':
description: Meta and list of all deals
content:
application/json:
schema:
$ref: '#/components/schemas/Deals.DealsList'
post:
description: Create a new deal_v2
operationId: create-new-deal
summary: Create new deal
tags:
- Deals
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Deals.CreateDealRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Deals.DealView'
description: ''
'409':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
/api/v2/deals/column_catalogue:
get:
description: Returns a list of columns and column groups for the user who making the request
operationId: list-column-catalogue
summary: List column catalogue
tags:
- Deals Fields
responses:
'200':
content:
application/json:
schema:
properties:
items:
oneOf:
- $ref: '#/components/schemas/Columns.ColumnGroup'
- $ref: '#/components/schemas/Deals.DealListingColumn'
type:
type: array
required:
- type
- items
type: object
description: ''
/api/v2/deals/fields:
get:
description: Retrieves list of deal fields for this user (standard) and fields for each pipeline
operationId: list-all-user-deals-fields
summary: List deal standard and pipelines fields
tags:
- Deals Fields
responses:
'200':
description: List of deals fields
content:
application/json:
schema:
$ref: '#/components/schemas/Deals.DealFieldsMetadata'
/api/v2/deals/tags:
get:
description: Returns a list of deals tags
operationId: list-deals-tags
summary: List deals tags
tags:
- Deals
parameters:
- description: Find tags that start with
in: query
name: starts_with
schema:
type: string
- description: A number of tags to return
in: query
name: limit
schema:
type: integer
responses:
'200':
content:
application/json:
schema:
properties:
tags:
items:
$ref: '#/components/schemas/Commons.Tag'
type: array
required:
- tags
type: object
description: ''
post:
description: Assign tags to deals
operationId: post-deals-tags
summary: Add tags to deals
tags:
- Deals
requestBody:
content:
application/json:
schema:
properties:
preflight_checks:
default: false
description: check query's deals are editable
type: boolean
query:
description: query for deals advanced search
type: object
tags:
description: list of tags to assign
items:
type: string
type: array
required:
- tags
- query
type: object
required: true
responses:
'200':
content:
application/json:
schema:
properties:
push_data:
$ref: '#/components/schemas/Contacts.AssigmentProgress'
required:
- push_data
type: object
description: tags successfully assigned
'406':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.PreflightCheckFailures'
description: ''
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
description: ''
/api/2/deals/tags/{tag_name}:
parameters:
- description: name of tag
in: path
name: tag_name
required: true
schema:
type: string
put:
description: update deals tag by name
operationId: put-deals-tag
summary: Update deals' tag by name
tags:
- Deals
requestBody:
content:
application/json:
schema:
properties:
new_tag:
type: string
required:
- new_tag
type: object
required: true
responses:
'200':
description: Tag successfully updated
'406':
description: tag with tag_name already exist
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.NotAcceptableError'
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
description: ''
delete:
description: delete deals tag by name
operationId: delete-deals-tag
summary: Delete deals tag by name
tags:
- Deals
requestBody:
content:
application/json:
schema:
properties:
preflight_checks:
default: false
description: check query's deals are editable
type: boolean
type: object
required: true
responses:
'200':
description: Tag successfully deleted/unlinked
'406':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.PreflightCheckFailures'
description: ''
/api/v2/deals/widget/won_last_month:
get:
description: Returns sum of all deals amount won last month
operationId: get-won-last-month-deals-sum
summary: Get sum of all deals amount won last month
tags:
- Deals
responses:
'200':
description: Sum of all deals amount from all pipelines won for last month
content:
application/json:
schema:
properties:
last_month_won_amount:
type: number
format: decimal
last_month_won_count:
type: integer
/api/v2/deals/{deal_id}:
get:
description: Get deal by id
operationId: get-deal
summary: Get deal by id
tags:
- Deals
responses:
'200':
description: Retrieved deal
content:
application/json:
schema:
$ref: '#/components/schemas/Deals.DealView'
'404':
description: Deal not found
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.NotFoundError'
delete:
description: Delete deal by id
operationId: delete-deal
summary: Delete deal by id
tags:
- Deals
responses:
'200':
description: ''
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ForbiddenError'
description: ''
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.NotFoundError'
put:
description: Edit deal by id
operationId: put-deal
summary: Update deal by id
tags:
- Deals
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Deals.EditDealRequest'
responses:
'200':
description: Updated deal
content:
application/json:
schema:
$ref: '#/components/schemas/Deals.DealView'
'409':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
parameters:
- description: id of a deal to operate on
in: path
name: deal_id
required: true
schema:
type: string
/api/v2/deals/{deal_id}/files:
post:
description: "Store a new deal file.\nWe can store two categories of files:\n\n1. Files from external\
\ sources (gdrive, dropbox, onedrive). In this scenario files are being select in the respective\n\
file picker, and the client should pass file details to this API call so the file gets stored\
\ for the deal\n\n2. Files uploaded from a computer using Azure SDK.\na) To perform the upload\
\ itself, the client must first use /api/files/azure/upload (this API is the same as one \nfor\
\ uploading Contact Files – we just moved it to a separate endpoint since it's independent \n\
from contact/deals/etc)\nb) after the upload was completed, the client has so-called `data_id`\
\ (the ID of this file in Azure Blob Storage)\nc) pass the `data_id` to this API so the file gets\
\ stored to the deal\n"
operationId: store-deal-file
summary: Store deal file
tags:
- Deals
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Deals.StoreFileRequest'
responses:
'201':
description: File was successfully added
parameters:
- description: id of deal to which the file should be stored
in: path
name: deal_id
required: true
schema:
type: string
/api/v2/deals/{deal_id}/files/{file_id}:
put:
description: |
Updates a file with new name. Note: only files uploaded using Azure SDK can be renamed
operationId: put-deal-file
summary: Update deal file
tags:
- Deals
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Deals.UpdateDealFileRequest'
responses:
'200':
description: Empty response, file was successfully updated
delete:
description: Deletes file
operationId: delete-deal-file
summary: Delete deal file
tags:
- Deals
responses:
'200':
description: ''
parameters:
- in: path
name: deal_id
required: true
schema:
type: string
- description: id of a file to operate with
in: path
name: file_id
required: true
schema:
type: string
/api/v2/deals/{deal_id}/files/{file_id}/url:
get:
description: Returns download link for selected deal file
operationId: get-deal-file-download-url
summary: Get deal file download url
tags:
- Deals
responses:
'200':
description: Retrieved URL
content:
application/json:
schema:
type: object
properties:
url:
type: string
description: Download URL
format: URL
'404':
description: File not found
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.NotFoundError'
parameters:
- in: path
name: deal_id
required: true
schema:
type: string
- description: id of a file to get link for
in: path
name: file_id
required: true
schema:
type: string
/api/v2/deals/{deal_id}/notes:
post:
description: Create note to the deal
operationId: create-deal-note
summary: Create note to the deal
tags:
- Deals
requestBody:
content:
application/json:
schema:
properties:
title:
type: string
description: Title of the note.
minLength: 1
maxLength: 256
body:
type: string
description: Text of the note.
required:
- title
responses:
'201':
description: Created note
content:
application/json:
schema:
$ref: '#/components/schemas/Deals.DealNote'
'409':
description: ValidationError
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
parameters:
- description: id of deal to which note should be attached
in: path
name: deal_id
required: true
schema:
type: string
/api/v2/deals/{deal_id}/notes/{note_id}:
put:
description: Update note
operationId: put-deal-note
summary: Update deal note by id
tags:
- Deals
requestBody:
content:
application/json:
schema:
properties:
title:
type: string
description: Title of the note.
minLength: 1
maxLength: 256
body:
type: string
description: Text of the note.
nullable: true
responses:
'200':
description: Updated note
content:
application/json:
schema:
$ref: '#/components/schemas/Deals.DealNote'
'404':
description: Note not found
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.NotFoundError'
'409':
description: ValidationError
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
delete:
description: Delete note
operationId: delete-deal-note
summary: Delete deal note by id
tags:
- Deals
responses:
'200':
description: ''
parameters:
- description: id of deal to which note should be attached
in: path
name: deal_id
required: true
schema:
type: string
- description: id of note to operate with
in: path
name: note_id
required: true
schema:
type: string
/api/v2/deals/{deal_id}/overdue:
get:
description: |
Returns a feed of overdue activities for a given deals. Sorting order is time since overdue, descending
operationId: list-deals-overdue-activities
summary: List deals' overdue activities
tags:
- Deals
parameters:
- description: Indicates how many activities show per page.
in: query
name: limit
schema:
type: integer
- description: List of overdue activity types to return. If not present, we'll return activities
by all types.
in: query
name: types
schema:
items:
type: string
type: array
responses:
'200':
content:
application/json:
schema:
properties:
activities:
description: List of activities that match query parameters.
items:
$ref: '#/components/schemas/Activities.Activity'
type: array
required:
- activities
type: object
description: ''
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
description: ''
parameters:
- in: path
name: deal_id
required: true
schema:
type: string
/api/v2/deals/pipelines:
get:
description: Get user pipelines
operationId: list-deals-pipelines
summary: List deals pipelines
tags:
- Deals Pipelines
responses:
'200':
content:
application/json:
schema:
type: object
properties:
pipelines:
type: array
items:
$ref: '#/components/schemas/Pipeline.DealsPipeline'
description: Success executing of retrieving all user pipelines
post:
description: Create new pipeline
operationId: post-deals-pipelines
summary: Create new deals pipeline
tags:
- Deals Pipelines
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Pipeline.CreateDealsPipelineRequest'
responses:
'201':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/Pipeline.DealsPipeline'
'409':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
/api/v2/deals/pipelines/{pipeline_id}:
get:
description: Get pipeline by id
operationId: get-deals-pipeline
summary: Get deals' pipeline by id
tags:
- Deals Pipelines
responses:
'200':
description: Received pipeline
content:
application/json:
schema:
$ref: '#/components/schemas/Pipeline.DealsPipeline'
'404':
description: Pipeline not found
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.NotFoundError'
put:
description: Update pipeline by id
operationId: put-deals-pipeline
summary: Update deals' pipeline by id
tags:
- Deals Pipelines
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Pipeline.EditDealsPipelineRequest'
responses:
'200':
description: Updated pipeline
content:
application/json:
schema:
$ref: '#/components/schemas/Pipeline.DealsPipeline'
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ForbiddenError'
description: User has no permission to manage the pipeline
'404':
description: Pipeline not found
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.NotFoundError'
'409':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
delete:
description: Delete the pipeline by its id. All deals in this pipelines will also be deleted!
operationId: delete-deals-pipeline
summary: Delete deals' pipeline by id
tags:
- Deals Pipelines
responses:
'200':
description: OK
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ForbiddenError'
description: User has no permission to manage the pipeline
parameters:
- description: Id of pipeline to operate with
in: path
name: pipeline_id
required: true
schema:
type: string
format: ObjectId
/api/v2/deals/pipelines/{pipeline_id}/deals:
get:
description: Get deals in pipeline listing separated by stages
operationId: list-pipeline-deals-by-stages
summary: List pipeline's deals separated by stages
tags:
- Deals Pipelines
responses:
'200':
description: Retrieved listing
content:
application/json:
schema:
properties:
stages:
type: array
items:
$ref: '#/components/schemas/Deals.DealsStageGroup'
parameters:
- name: pipeline_id
description: id of pipeline to get listing for
schema:
type: string
format: ObjectId
in: path
required: true
- name: sort
description: parameter to sort by
schema:
type: string
format: field:order
example: name:asc
in: query
required: true
- name: limit
description: limit of deals per page
schema:
type: integer
example: 30
default: 10
in: query
- name: query
description: unparsed NSE search query
schema:
type: string
in: query
- name: stage_id
description: id of stage to get info about
schema:
type: string
format: ObjectId
in: query
- name: stuck
description: |
Filter deals by whether they are stuck in the current stage.
Stages with `expected_days=0` are treated the same as stages without `expected_days`.
For stages with `expected_days`, `true` returns deals older than the configured number of days and
`false` returns deals up to that threshold.
For stages without `expected_days` and for stages with `expected_days=0`, `true` returns no deals and
`false` does not add any extra restriction.
schema:
type: boolean
in: query
/api/v2/deals/pipelines/{pipeline_id}/owners:
get:
description: Get deals in pipeline listing separated by owners
operationId: list-pipeline-deals-by-owner
summary: List pipeline's deals separated by owners
tags:
- Deals Pipelines
responses:
'200':
description: Retrieved listing
content:
application/json:
schema:
properties:
groups:
type: array
items:
$ref: '#/components/schemas/Deals.DealsByOwnerGroup'
parameters:
- name: pipeline_id
description: id of pipeline to get listing for
schema:
type: string
format: ObjectId
in: path
required: true
- name: sort
description: parameter to sort by
schema:
type: string
format: field:order
example: name:asc
in: query
required: true
- name: limit
description: limit of deals per page
schema:
type: integer
example: 30
default: 10
in: query
- name: query
description: unparsed NSE search query
schema:
type: string
in: query
/api/v2/deals/pipelines/{pipeline_id}/archive:
post:
description: Archive the pipeline
operationId: mark-deals-pipeline-archived
summary: Archive deals pipeline
tags:
- Deals Pipelines
responses:
'200':
description: empty response
parameters:
- description: Id of pipeline to operate with
in: path
name: pipeline_id
required: true
schema:
type: string
format: ObjectId
/api/v2/deals/pipelines/{pipeline_id}/unarchive:
post:
description: Un-archive the pipeline
operationId: mark-deals-pipeline-unarchived
summary: Un-archive deals' pipeline
tags:
- Deals Pipelines
responses:
'200':
description: empty response
parameters:
- description: Id of pipeline to operate with
in: path
name: pipeline_id
required: true
schema:
type: string
format: ObjectId
/api/v2/deals/pipelines/{pipeline_id}/lost_reasons:
post:
description: Add lost reason to pipeline
operationId: post-deals-pipeline-lost-reason
summary: Add new lost reason to deals pipeline
tags:
- Deals Pipelines
requestBody:
content:
application/json:
schema:
type: object
properties:
reason:
type: string
description: Reason description
required:
- reason
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/Pipeline.DealsPipeline'
description: Success
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ForbiddenError'
description: User has no permission to manage the pipeline
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.NotFoundError'
description: A pipeline with requested id doesn't exist
'406':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ActionCanNotBeCompleted'
description: 'If pipeline is already archived or if there is already a reason with such a name '
parameters:
- description: id of pipeline where reason is
in: path
name: pipeline_id
required: true
schema:
type: string
format: ObjectId
/api/v2/deals/pipelines/{pipeline_id}/stages:
post:
description: Create deal stage
operationId: post-deals-pipeline-stage
summary: Create new deals pipeline stage
tags:
- Deals Pipelines
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Pipeline.CreateDealStageRequest'
responses:
'201':
description: Updated Pipeline
content:
application/json:
schema:
$ref: '#/components/schemas/Pipeline.DealsPipeline'
'403':
description: User has no permission to update pipeline
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ForbiddenError'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.NotFoundError'
'409':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
parameters:
- name: pipeline_id
description: id of pipeline to manipulate with
in: path
required: true
schema:
type: string
format: ObjectId
/api/v2/deals/pipelines/{pipeline_id}/stages/{stage_id}:
put:
description: Update stage
operationId: put-deals-pipeline-stage
summary: Update deals pipeline stage
tags:
- Deals Pipelines
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Pipeline.EditDealStageRequest'
responses:
'200':
description: Updated Pipeline
content:
application/json:
schema:
$ref: '#/components/schemas/Pipeline.DealsPipeline'
'403':
description: User has no permission to update pipeline
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ForbiddenError'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.NotFoundError'
'409':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
delete:
description: Archives stage
operationId: mark-deals-pipeline-stage-archived
summary: Archive deals pipeline stage
tags:
- Deals Pipelines
responses:
'200':
description: Archived
parameters:
- name: pipeline_id
description: id of pipeline to manipulate with
in: path
required: true
schema:
type: string
format: ObjectId
- name: stage_id
description: id of stage to manipulate with
in: path
required: true
schema:
type: string
format: ObjectId
/api/v2/deals/pipelines/{pipeline_id}/fields:
post:
description: Creates custom field in pipeline
operationId: post-deals-pipeline-field
summary: Add new custom field to deals pipeline
tags:
- Deals Pipelines Fields
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Pipeline.CreateDealsPipelineFieldRequest'
responses:
'201':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/Deals.DealFieldsMetadata'
'406':
description: Field not acceptable
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.NotAcceptableError'
'409':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
parameters:
- description: id of a pipeline to operate on
in: path
name: pipeline_id
required: true
schema:
type: string
/api/v2/deals/pipelines/{pipeline_id}/fields/{field_id}:
put:
description: Updates custom field in pipeline
operationId: put-deals-pipeline-field
summary: Update custom field in deals pipeline
tags:
- Deals Pipelines Fields
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Pipeline.UpdateDealsPipelineFieldRequest'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/Deals.DealFieldsMetadata'
'404':
description: Field not found
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.NotFoundError'
'406':
description: Field not acceptable
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.NotAcceptableError'
'409':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
delete:
description: Deletes custom field from pipeline
operationId: delete-deals-pipeline-field
summary: Delete custom field from deals pipeline
tags:
- Deals Pipelines Fields
requestBody:
content:
application/json:
schema:
type: object
properties:
preflight_checks:
type: boolean
description: |
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
responses:
'200':
description: Deleted
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ForbiddenError'
description: Access forbidden
'404':
description: Field not found
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.NotFoundError'
parameters:
- description: id of a pipeline to operate on
in: path
name: pipeline_id
required: true
schema:
type: string
- description: id of custom field in pipeline to operate on
in: path
name: field_id
required: true
schema:
type: string
/api/v2/deals/pipelines/{pipeline_id}/fields/{field_id}/choices:
post:
description: Creates choice in specified pipeline field
operationId: post-deals-pipeline-field-choice
summary: Create choice in deals pipeline field
tags:
- Deals Pipelines Fields
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Pipeline.CreateDealsPipelineFieldChoiceRequest'
responses:
'201':
description: Created
content:
application/json:
schema:
$ref: '#/components/schemas/Deals.DealFieldsMetadata'
'404':
description: Pipeline/Field not found
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.NotFoundError'
'409':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
parameters:
- description: id of a pipeline where custom field is
in: path
name: pipeline_id
required: true
schema:
type: string
- description: id of custom field where choice will be created
in: path
name: field_id
required: true
schema:
type: string
/api/v2/deals/pipelines/{pipeline_id}/fields/{field_id}/choices/{choice_id}:
put:
description: Updates choice in custom field in pipeline
operationId: put-deals-pipeline-field-choice
summary: Update choice in custom deals pipeline field
tags:
- Deals Pipelines Fields
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Pipeline.UpdateDealsPipelineFieldChoiceRequest'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/Deals.DealFieldsMetadata'
'404':
description: Pipeline/Field/Choice not found
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.NotFoundError'
'406':
description: Choice is not acceptable
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.NotAcceptableError'
'409':
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
delete:
description: Deletes choice from custom field
operationId: delete-deals-pipeline-field-choice
summary: Delete choice from deals pipeline custom field
tags:
- Deals Pipelines Fields
requestBody:
content:
application/json:
schema:
type: object
properties:
preflight_checks:
type: boolean
description: |
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
responses:
'200':
description: Deleted
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ForbiddenError'
description: Access forbidden
'404':
description: Pipeline/Field/Choice not found
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.NotFoundError'
parameters:
- description: id of a pipeline where custom field is
in: path
name: pipeline_id
required: true
schema:
type: string
- description: id of custom field where choice is
in: path
name: field_id
required: true
schema:
type: string
- description: id of choice to operate on
in: path
name: choice_id
required: true
schema:
type: string
/api/v2/deals/pipelines/{pipeline_id}/groups:
post:
description: Create pipeline deal group
operationId: post-deals-pipeline-group
summary: Create deals pipeline fields group
tags:
- Deals Pipelines Fields
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Pipeline.CreateDealsPipelineGroupRequest'
responses:
'201':
description: Group created
content:
application/json:
schema:
$ref: '#/components/schemas/Deals.DealFieldsMetadata'
'403':
description: User has no permission to update pipeline
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ForbiddenError'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.NotFoundError'
'409':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
parameters:
- name: pipeline_id
description: id of pipeline to manipulate with
in: path
required: true
schema:
type: string
format: ObjectId
/api/v2/deals/pipelines/{pipeline_id}/groups/{group_id}:
put:
description: Update pipeline deal group
operationId: put-deals-pipeline-fields-group
summary: Update deals pipeline fields group
parameters:
- in: path
name: pipeline_id
description: id of group to manipulate with
schema:
type: string
required: true
- in: path
name: group_id
description: id of group to update
schema:
type: string
required: true
tags:
- Deals Pipelines Fields
requestBody:
content:
application/json:
schema:
properties:
group_name:
type: string
logo_id:
type: string
insert_after:
description: move group after another group or field with specified id
type: string
responses:
'200':
description: Group updated
content:
application/json:
schema:
$ref: '#/components/schemas/Deals.DealFieldsMetadata'
'403':
description: User has no permission to update pipeline
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ForbiddenError'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.NotFoundError'
'409':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ValidationError'
delete:
description: Delete pipeline deal group
operationId: delete-deals-pipeline-fields-group
summary: Delete deals pipeline fields group
tags:
- Deals Pipelines Fields
responses:
'200':
description: Group deleted
'403':
description: User has no permission to update pipeline
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.ForbiddenError'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Errors.NotFoundError'
parameters:
- in: path
name: pipeline_id
description: id of pipeline to delete group from
schema:
type: string
required: true
- in: path
name: group_id
description: id of group to delete
schema:
type: string
required: true
/api/v1/messages/drafts:
get:
description: List draft messages
operationId: list-messages-drafts
summary: List messages drafts
tags:
- Messages
parameters:
- description: coma-separated recipient to filter drafts for
in: query
name: recipients
required: false
schema:
type: string
- description: filter scheduled messages by a sender account
in: query
name: sender
required: false
schema:
type: string
- description: pagination parameter (starts from zero)
in: query
name: page
required: false
schema:
type: number
- description: pagination parameter
in: query
name: per_page
required: false
schema:
type: number
responses:
'200':
content:
application/json:
schema:
properties:
drafts:
type: array
items:
$ref: '#/components/schemas/Messages.DraftMessageWithParticipants'
meta:
type: object
properties:
total:
type: number
pages:
type: number
page:
type: number
per_page:
type: number
type: object
description: response with draft messages and a pagination meta
post:
description: Create a draft message
operationId: post-message-draft
summary: Create a draft message
tags:
- Messages
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/Messages.IncompleteMessageSpecification'
responses:
'200':
description: updated draft message
content:
application/json:
schema:
$ref: '#/components/schemas/Messages.DraftMessageWithParticipants'