Nimble Tasks API
Task creation against contacts. 1 operation(s).
OpenAPI Specification
openapi: 3.0.0
info:
title: Nimble Tasks API
description: Nimble CRM Tasks operations. Split by tag from the OpenAPI Nimble publishes at https://www.nimble.com/developers/docs/
(embedded Redoc spec). Base host https://app.nimble.com.
version: v1
servers:
- url: https://app.nimble.com
tags:
- name: Tasks
description: Tasks management
paths:
/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: ''
security:
- ApiKey: []
components:
schemas:
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.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
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 <span style='color:red'>SHOULD NOT USE</span>
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
Contacts.ContactType:
enum:
- person
- company
type: string
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
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
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
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
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
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
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
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
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
securitySchemes:
ApiKey:
type: apiKey
in: header
name: X-Nimble-Token