openapi: 3.1.0
info:
  title: Nimble CRM API
  description: |
    The Nimble REST API lets developers manage contacts, deals,
    pipelines, notes, custom fields, and messages within a Nimble
    account. Requests are authenticated with an OAuth 2.0 bearer
    token, either via the Authorization header or an access_token
    query parameter.
  version: "v1"
servers:
  - url: https://app.nimble.com/api/v1
    description: Nimble production API base
security:
  - bearerAuth: []
paths:
  /myself:
    get:
      summary: Retrieve information about the authenticated user
      operationId: getMyself
      tags: [Users]
      responses:
        "200":
          description: Authenticated user record
  /contacts:
    get:
      summary: List contacts
      operationId: listContacts
      tags: [Contacts]
      parameters:
        - in: query
          name: query
          schema:
            type: string
        - in: query
          name: page
          schema:
            type: integer
        - in: query
          name: per_page
          schema:
            type: integer
      responses:
        "200":
          description: Contacts collection
    delete:
      summary: Delete multiple contacts by query
      operationId: deleteContactsByQuery
      tags: [Contacts]
      responses:
        "204":
          description: Contacts deleted
  /contacts/ids:
    get:
      summary: List contact IDs only
      operationId: listContactIds
      tags: [Contacts]
      responses:
        "200":
          description: Contact IDs
  /contact:
    get:
      summary: Retrieve specific contacts by IDs
      operationId: getContactsByIds
      tags: [Contacts]
      parameters:
        - in: query
          name: ids
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Requested contacts
    post:
      summary: Create a new contact
      operationId: createContact
      tags: [Contacts]
      responses:
        "201":
          description: Contact created
  /contact/{contact_id}:
    get:
      summary: Get an individual contact
      operationId: getContact
      tags: [Contacts]
      parameters:
        - in: path
          name: contact_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Contact details
    put:
      summary: Update a contact
      operationId: updateContact
      tags: [Contacts]
      parameters:
        - in: path
          name: contact_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Contact updated
    delete:
      summary: Delete a contact
      operationId: deleteContact
      tags: [Contacts]
      parameters:
        - in: path
          name: contact_id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Contact deleted
  /contact/{contact_id}/note:
    post:
      summary: Create a contact note
      operationId: createContactNote
      tags: [Notes]
      parameters:
        - in: path
          name: contact_id
          required: true
          schema:
            type: string
      responses:
        "201":
          description: Note created
  /contact/{contact_id}/notes:
    get:
      summary: List contact notes
      operationId: listContactNotes
      tags: [Notes]
      parameters:
        - in: path
          name: contact_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Notes collection
  /contact/{contact_id}/note/{note_id}:
    get:
      summary: Get a specific contact note
      operationId: getContactNote
      tags: [Notes]
      parameters:
        - in: path
          name: contact_id
          required: true
          schema:
            type: string
        - in: path
          name: note_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Note details
    put:
      summary: Update a contact note
      operationId: updateContactNote
      tags: [Notes]
      parameters:
        - in: path
          name: contact_id
          required: true
          schema:
            type: string
        - in: path
          name: note_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Note updated
    delete:
      summary: Delete a contact note
      operationId: deleteContactNote
      tags: [Notes]
      parameters:
        - in: path
          name: contact_id
          required: true
          schema:
            type: string
        - in: path
          name: note_id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Note deleted
  /contact/fields/metadata:
    get:
      summary: List contact field metadata
      operationId: listContactFieldsMetadata
      tags: [Fields]
      responses:
        "200":
          description: Field metadata
  /contact/field:
    post:
      summary: Create a custom contact field
      operationId: createContactField
      tags: [Fields]
      responses:
        "201":
          description: Field created
  /contact/field/{field_id}:
    put:
      summary: Update a contact field
      operationId: updateContactField
      tags: [Fields]
      parameters:
        - in: path
          name: field_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Field updated
    delete:
      summary: Delete a contact field
      operationId: deleteContactField
      tags: [Fields]
      parameters:
        - in: path
          name: field_id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Field deleted
  /deals:
    get:
      summary: List deals
      operationId: listDeals
      tags: [Deals]
      responses:
        "200":
          description: Deals collection
  /deal:
    post:
      summary: Create a deal
      operationId: createDeal
      tags: [Deals]
      responses:
        "201":
          description: Deal created
  /deal/{deal_id}:
    get:
      summary: Get a deal
      operationId: getDeal
      tags: [Deals]
      parameters:
        - in: path
          name: deal_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Deal details
    put:
      summary: Update a deal
      operationId: updateDeal
      tags: [Deals]
      parameters:
        - in: path
          name: deal_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Deal updated
    delete:
      summary: Delete a deal
      operationId: deleteDeal
      tags: [Deals]
      parameters:
        - in: path
          name: deal_id
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Deal deleted
  /pipelines:
    get:
      summary: List deal pipelines
      operationId: listPipelines
      tags: [Pipelines]
      responses:
        "200":
          description: Pipelines collection
  /pipeline:
    post:
      summary: Create a pipeline
      operationId: createPipeline
      tags: [Pipelines]
      responses:
        "201":
          description: Pipeline created
  /pipeline/{pipeline_id}:
    put:
      summary: Update a pipeline
      operationId: updatePipeline
      tags: [Pipelines]
      parameters:
        - in: path
          name: pipeline_id
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Pipeline updated
  /messages/drafts:
    get:
      summary: List draft messages
      operationId: listMessageDrafts
      tags: [Messages]
      responses:
        "200":
          description: Drafts collection
  /message/draft:
    post:
      summary: Create a draft message
      operationId: createMessageDraft
      tags: [Messages]
      responses:
        "201":
          description: Draft created
components:
  securitySchemes:
    bearerAuth:
      type: oauth2
      description: |
        OAuth 2.0 bearer token. Provide the token via either the
        `Authorization: Bearer <token>` header or the
        `access_token=<token>` query parameter.
      flows:
        authorizationCode:
          authorizationUrl: https://app.nimble.com/oauth/authorize
          tokenUrl: https://app.nimble.com/oauth/token
          scopes: {}
tags:
  - name: Users
  - name: Contacts
  - name: Notes
  - name: Fields
  - name: Deals
  - name: Pipelines
  - name: Messages