Rocket Lawyer Subscription Management API

openapi: 3.2.0
info:
  title: Events Subscription Management API
  version: '1'
  description: 'This API documentation describes the server-side contract by which Rocket Lawyer Events can be subscribed to and events can be pulled using the Partner Events API.


    Steps to pull events -

    1. Use POST /subscriptions API to create a subscription

    2. Use POST /subscriptions/{subscriptionId}/eventPulls API to pull events

    3. Use POST /subscriptions/{subscriptionId}/eventAcknowledgements to acknowledge the pulled events'
servers:
- url: https://api-sandbox.rocketlawyer.com/events/v1
  description: Sandbox
- url: https://api.rocketlawyer.com/events/v1
  description: Production
security:
- bearerAuth: []
tags:
- name: Subscription Management
paths:
  /subscriptions:
    post:
      tags:
      - Subscription Management
      operationId: createSubscription
      description: 'Create a subscription.


        Note: If your application already has a subscription it will be returned instead of creating a new one.


        Subscription Expiration: If there is no interaction with the subscription over the period of 31 days,

        it will be automatically deleted.


        Authorization\: Requires a general access token.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionPost'
      responses:
        201:
          description: The subscription was created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        403:
          description: You do not have sufficient permission to create a subscription
      summary: Create subscription
      x-summary-source: derived
  /subscriptions/{subscriptionId}:
    parameters:
    - name: subscriptionId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/SubscriptionId'
    get:
      tags:
      - Subscription Management
      operationId: getSubscription
      description: 'Get a subscription. This can be used to confirm that a subscription exists.


        Subscription Expiration: If there is no interaction with the subscription over the period of 31 days,

        it will be automatically deleted.


        Authorization\: Requires a general access or scoped access token.'
      responses:
        200:
          description: The subscription exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        204:
          description: The subscription does not exist
        403:
          description: You do not have sufficient permission to access this subscription
      summary: Get subscription
      x-summary-source: derived
    delete:
      tags:
      - Subscription Management
      operationId: deleteSubscription
      description: 'Delete a subscription. This will cause the acknowledgement state of all events to be

        forgotten. If you wish to "undo" a deletion, you may create a new subscription and

        perform a seek request to just before the time of deletion, though you must be

        prepared to handle a few duplicate events.


        Authorization\: Requires a general access or scoped access token.'
      responses:
        204:
          description: The subscription is deleted
        403:
          description: You do not have sufficient permission to delete this subscription
        404:
          description: The subscription does not exist
      summary: Delete subscription
      x-summary-source: derived
  /subscriptions/{subscriptionId}/seekRequests:
    parameters:
    - name: subscriptionId
      in: path
      description: ''
      required: true
      schema:
        $ref: '#/components/schemas/SubscriptionId'
    post:
      tags:
      - Subscription Management
      operationId: createSubscriptionSeekRequest
      description: 'Move a subscription to a specified time. If the specified time is in the past and within

        the event retention timeframe (7 days), already-acknowledged events may be replayed. It is also

        possible to use this operation to "skip" events by seeking to a time that is _after_ some number of

        non-acknowledged events.


        Authorization\: Requires a general access or scoped access token.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SeekRequestPost'
      responses:
        200:
          description: 'The seek request has been fulfilled. Events from roughly the specified time will be replayed for

            this subscription.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SeekRequest'
        403:
          description: You do not have sufficient permission to request seeks for this subscription
        404:
          description: The subscription does not exist
        409:
          description: 'The request could not be performed, as the timestamp is outside of the event retention period.

            This is returned on a best-effort basis, so it is possible that a "success" response will be

            returned but a few events will be missed.

            '
      summary: Create subscription seek request
      x-summary-source: derived
components:
  schemas:
    SubscriptionCreatedAtTimestamp:
      description: Time when this subscription was created
      type: string
      format: date-time
      example: '2021-04-12T04:20:50Z'
    SubscriptionUpdatedAtTimestamp:
      description: Time when this subscription was last updated
      type: string
      format: date-time
      example: '2021-05-11T23:10:51Z'
    Subscription:
      description: A specific subscription
      type: object
      properties:
        subscriptionId:
          $ref: '#/components/schemas/SubscriptionId'
        createdAt:
          $ref: '#/components/schemas/SubscriptionCreatedAtTimestamp'
        updatedAt:
          $ref: '#/components/schemas/SubscriptionUpdatedAtTimestamp'
      required:
      - subscriptionId
      - createdAt
      - updatedAt
    SeekRequest:
      description: 'Result of a specific seek request. Currently just includes a unique ID

        that may be used as reference with Rocket Lawyer

        '
      type: object
      properties:
        seekRequestId:
          $ref: '#/components/schemas/SeekRequestId'
        seekTo:
          $ref: '#/components/schemas/SeekToTimestamp'
      required:
      - seekRequestId
      - seekTo
    SubscriptionId:
      description: The ID for a specific subscription.
      type: string
      format: uuid
      example: f3443a23-301d-4b6b-a178-3840d8cb9e5f
    SubscriptionPost:
      description: The spec for a subscription
      type: object
    SeekRequestId:
      description: 'An ID which may be used to reference a specific seek request in communication with Rocket Lawyer. If an seek request ID is not provided,

        one will be generated automatically. If an ID _is_ provided, it should have a unique value for each each seek request.

        '
      type: string
      format: uuid
      example: 2acbdced-121d-4896-a02c-5b77528f8b77
    SeekToTimestamp:
      description: 'Time to seek the subscription to. This is expected to generally be a

        time in the past to initiate event replay, but it may be any timestamp.

        '
      type: string
      format: date-time
      example: '2021-10-01T10:22:02Z'
    SeekRequestPost:
      description: 'A spec for a request to seek a subscription to a different timestamp

        '
      type: object
      properties:
        seekTo:
          $ref: '#/components/schemas/SeekToTimestamp'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT