Close Events API

openapi: 3.2.0
info:
  description: Close CRM REST API
  title: Close Events API
  version: 1.0.0
servers:
- url: https://api.close.com/api/v1
security:
- ApiKeyAuth: []
- OAuth2: []
tags:
- name: events
  externalDocs:
    url: https://developer.close.com/api/resources/events
paths:
  /event/:
    get:
      operationId: events_list
      tags:
      - events
      summary: Retrieve a list of events
      description: 'The list of available object types and actions is available [here](https://developer.close.com/api/resources/events/list-of-event-types). The event log can be filtered by the following parameters:


        - `date_updated`: The date/time of when the event was last updated, in ISO format. Can be filtered by range (`date_updated__gte=X&date_updated__lte=Y`). Note: For pagination, it is recommended to use cursors instead of this filter (see below).

        - `object_type`: If specified, only events for objects of a given type are returned. Example: `object_type=lead`

        - `object_id`: If specified, only events for the given object are returned. No related object events are returned. Example: `object_id=lead_123`

        - `action`: Only events of specified actions are returned. Example: `action=deleted`

        - `lead_id`: If specified, events for the given lead, including any of its related objects (contacts, activities, opportunities, tasks) are returned.

        - `user_id`: Only return events of the given user.

        - `request_id`: Only events emitted while processing this specific API request.


        Only certain combinations of filters are supported. `date_updated` can be optionally used with any allowed filter combination. Supported combinations are:


        - `object_type` and `object_id`

        - `object_type` and `action`

        - `object_id` and `action`

        - `lead_id` and `object_type`

        - `lead_id`, `object_type` and `action`

        - `lead_id`, `user_id` and `object_type`

        - `lead_id`, `user_id`, `object_type` and `action`

        - `lead_id` and `user_id`

        - `user_id` and `object_id`

        - `user_id`, `object_id` and `action`

        - `user_id` and `object_type`

        - `user_id`, `object_type` and `action`

        - Just `lead_id`

        - Just `user_id`

        - Just `request_id`


        The response is a dictionary with the following fields:


        - `data`: A list of events (dictionaries), using the format outlined in “Event format”.

        - `cursor_next`: Cursor string to retrieve the next page of events, i.e. events before the given ID (earlier date), or `null` if no more objects are available.

        - `cursor_previous`: Cursor string to retrieve the previous page of events, i.e. events after the given ID (later date), or `null` if no more objects are available.


        Events are always ordered by date (latest first), i.e. the `date_updated` field. Note that even though `date_created` and `date_updated` may only have millisecond-precision, two or more events for the same object are guaranteed to be returned in the proper order.


        The endpoint supports the following parameters for pagination, and does *not* support `_skip`:


        - `_cursor`: Pagination using a cursor string (`cursor_next` or `cursor_previous` from a previous response). Note that you still need to supply any other filters (except for `date_updated`) that were used in the previous query.

        - `_limit`: Maximum number of events to return (capped at and defaulting to 50).


        Cursors are a reliable way to go to the next or previous page of events (unlike filtering by `date_updated`, where you may need to account for and filter out multiple events happening in the same millisecond). However, cursors are not designed to stream new events: Events may be visible through the API in a different order than they were triggered (but the ordering returned by the API is correct). Also, event consolidation of multiple recent events to the same object may occur. To avoid missing recent events when paginating, we recommend to scan the latest five minutes of events.


        In the example response, to retrieve the next older batch of events, specify `_cursor=cursor2`.'
      parameters:
      - $ref: '#/components/parameters/LimitParam'
      - $ref: '#/components/parameters/SkipParam'
      - in: query
        name: object_type
        required: false
        schema:
          title: Object Type
          default: null
          anyOf:
          - type: string
          - type: 'null'
      - in: query
        name: object_id
        required: false
        schema:
          title: Object ID
          default: null
          anyOf:
          - type: string
          - type: 'null'
      - in: query
        name: lead_id
        required: false
        schema:
          title: Lead ID
          default: null
          anyOf:
          - type: string
          - type: 'null'
      - in: query
        name: action
        required: false
        schema:
          title: Action
          default: null
          anyOf:
          - type: string
          - type: 'null'
      - in: query
        name: user_id
        required: false
        schema:
          title: User ID
          default: null
          anyOf:
          - type: string
          - type: 'null'
      - in: query
        name: date_updated__gt
        required: false
        schema:
          title: Date Updated (>)
          default: null
          anyOf:
          - type: string
          - type: 'null'
      - in: query
        name: date_updated__gte
        required: false
        schema:
          title: Date Updated (>=)
          default: null
          anyOf:
          - type: string
          - type: 'null'
      - in: query
        name: date_updated__lt
        required: false
        schema:
          title: Date Updated (<)
          default: null
          anyOf:
          - type: string
          - type: 'null'
      - in: query
        name: date_updated__lte
        required: false
        schema:
          title: Date Updated (<=)
          default: null
          anyOf:
          - type: string
          - type: 'null'
      responses:
        '200':
          content:
            application/json:
              example:
                cursor_next: cursor2
                cursor_previous: cursor1
                data: []
          description: Successful response
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Not found
  /event/{id}/:
    get:
      operationId: events_get
      tags:
      - events
      summary: Retrieve a single event by ID
      description: The response contains a dictionary with a single event, using the format outlined in “Event format”.
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              example:
                action: created
                changed_fields: []
                data:
                  _type: Note
                  contact_id: null
                  created_by: user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA
                  created_by_name: Gob Bluth
                  date_created: '2016-10-19T12:22:10.433000+00:00'
                  date_updated: '2016-10-19T12:22:10.433000+00:00'
                  id: acti_4LNDQk2uhg7t8fGUWPyHX7cpCVH9PJtCyCssXFcao3e
                  lead_id: lead_sHR5sxie4dKOBkODA2flGciHen2c91YEpvTPt8x1NU0
                  note: My note.
                  organization_id: orga_RbREgmiiwcr1w2b4cOnCMQaQPSIFxMqAD2Dh243uxcH
                  updated_by: user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA
                  updated_by_name: Gob Bluth
                  user_id: user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA
                  user_name: Gob Bluth
                  users: []
                date_created: '2016-10-19T12:22:10.434000'
                date_updated: '2016-10-19T12:22:10.434000'
                id: ev_17VaZdcdnsMNyWY9ZJnjph
                lead_id: lead_sHR5sxie4dKOBkODA2flGciHen2c91YEpvTPt8x1NU0
                meta:
                  request_method: POST
                  request_path: /api/v1/activity/note/
                object_id: acti_4LNDQk2uhg7t8fGUWPyHX7cpCVH9PJtCyCssXFcao3e
                object_type: note
                organization_id: orga_RbREgmiiwcr1w2b4cOnCMQaQPSIFxMqAD2Dh243uxcH
                previous_data: {}
                request_id: req_2skaL7v81TflDfovw8A1CC
                user_id: user_N6KhMpzHRCYQHdn4gRNIFNN5JExnsrprKA6ekxM63XA
          description: Successful response
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: Not found
components:
  parameters:
    LimitParam:
      description: Number of results to return.
      in: query
      name: _limit
      required: false
      schema:
        default: 100
        type: integer
    SkipParam:
      description: Number of results to skip before returning, for pagination.
      in: query
      name: _skip
      required: false
      schema:
        default: 0
        type: integer
  securitySchemes:
    ApiKeyAuth:
      description: Use your API key as the username and leave the password empty.
      scheme: basic
      type: http
    OAuth2:
      flows:
        authorizationCode:
          authorizationUrl: https://app.close.com/oauth2/authorize/
          scopes:
            all.full_access: Full access to all resources
            offline_access: Request a refresh token
          tokenUrl: https://api.close.com/oauth2/token/
      type: oauth2