Peerbound Activities API

openapi: 3.2.0
info:
  title: Peerbound Public Activities API
  description: 'The Peerbound Public API provides read-only access to your organization''s data for integration

    with external systems such as data warehouses and business intelligence tools.


    ## Authentication


    All requests require an API key passed via the `X-API-Key` header.


    **To obtain an API key:**

    1. Navigate to Settings > API Keys in the Peerbound web app

    2. Generate a new key

    3. Copy the key immediately—it will only be shown once


    **Note:** Only organization admins can access the API Keys settings page. API access is not

    enabled by default and must be enabled by the Peerbound team for your organization.


    ## Incremental Sync


    This API is designed for executing incremental data syncs. All list endpoints:

    - Return results ordered by `updated_at` ascending (oldest updates first)

    - Support an `updated_since` filter to fetch only records modified after a given timestamp

    - Use cursor-based pagination for efficient iteration through large datasets

    - Include deleted records (with `is_deleted: true`) so you can sync deletions


    **Recommended sync pattern:**

    1. On first sync, fetch all records without `updated_since`

    2. Store the `updated_at` timestamp of the most recent record

    3. On subsequent syncs, pass that timestamp as `updated_since` to fetch only changes


    *Warning:* If a record is updated while you are paginating through results, the same record may appear

    again in a later page. Your sync logic should handle this by prioritizing the version of the

    record returned in the later page.


    ## Rate Limiting


    To protect infrastructure and ensure fair usage, the API enforces rate limits:


    - **1,000 requests per hour** (hourly limit)

    - **5 requests per second** (burst limit)


    Rate limits are applied **per organization**, not per API key. Multiple API keys for the same

    organization share the same limit.


    The hourly limit uses a fixed window that resets at the top of each hour (e.g., 10:00, 11:00).

    When you exceed the limit, you''ll receive a `429 Too Many Requests` response with a `Retry-After`

    header indicating how long to wait.


    All responses include rate limit headers:


    | Header | Description |

    |--------|-------------|

    | `RateLimit-Limit` | Maximum requests allowed per hour |

    | `RateLimit-Remaining` | Requests remaining in the current window |

    | `RateLimit-Reset` | Seconds until the rate limit resets |


    ## Support


    If you encounter unexpected issues, please contact **support@peerbound.com**. To help us

    investigate, include:


    - The request payload that caused the issue

    - The `X-Request-ID` header value from the response


    Every API response includes an `X-Request-ID` header with a unique identifier for that request.'
  version: v1
servers:
- url: /api/public/v1
tags:
- name: Activities
paths:
  /activities:
    get:
      tags:
      - Activities
      summary: List activities
      description: Retrieve a paginated list of activities for your organization.
      operationId: list_activities_activities_get
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 200
          minimum: 1
          description: Maximum number of activities to return
          default: 100
          title: Limit
        description: Maximum number of activities to return
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Pagination cursor from previous response
          title: Cursor
        description: Pagination cursor from previous response
      - name: updated_since
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          description: Filter records updated at or after this timestamp (ISO 8601)
          title: Updated Since
        description: Filter records updated at or after this timestamp (ISO 8601)
      - name: x-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListResponse_Activity_'
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: API access not enabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /activities/{activity_id}:
    get:
      tags:
      - Activities
      summary: Get an activity
      description: Retrieve a single activity by its ID.
      operationId: get_activity_activities__activity_id__get
      parameters:
      - name: activity_id
        in: path
        required: true
        schema:
          type: string
          title: Activity Id
      - name: x-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Activity'
        '401':
          description: Authentication failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: API access not enabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Activity not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    Activity:
      properties:
        id:
          type: string
          title: Id
          description: Unique Peerbound identifier for the activity
        notes:
          anyOf:
          - type: string
          - type: 'null'
          title: Notes
          description: Notes/description of the activity
        activity_type:
          type: string
          title: Activity Type
          description: Type/category of the activity
        date:
          type: string
          title: Date
          description: Date the activity occurred (ISO 8601 date)
        source_link_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Source Link Url
          description: External URL reference for the activity
        account:
          anyOf:
          - $ref: '#/components/schemas/LinkedAccount'
          - type: 'null'
          description: Associated account (customer)
        contact:
          anyOf:
          - $ref: '#/components/schemas/LinkedContact'
          - type: 'null'
          description: Associated contact (person)
        is_deleted:
          type: boolean
          title: Is Deleted
          description: Whether the activity has been deleted
        created_at:
          type: string
          title: Created At
          description: Timestamp when the activity was created (ISO 8601)
        updated_at:
          type: string
          title: Updated At
          description: Timestamp when the activity or its type was last updated (ISO 8601)
      type: object
      required:
      - id
      - activity_type
      - date
      - is_deleted
      - created_at
      - updated_at
      title: Activity
      description: 'An activity associated with an account and a contact.


        Activities include the type name normalized as a string. The updated_at

        reflects changes to both the activity and its associated activity type.'
    PaginationInfo:
      properties:
        next_cursor:
          anyOf:
          - type: string
          - type: 'null'
          title: Next Cursor
          description: Opaque cursor to fetch the next page. Null if no more results.
        has_more:
          type: boolean
          title: Has More
          description: Whether there are more results available
        limit:
          type: integer
          title: Limit
          description: Maximum number of results requested
      type: object
      required:
      - has_more
      - limit
      title: PaginationInfo
      description: 'Pagination metadata for list responses.


        All list endpoints use cursor-based pagination with consistent metadata.'
    ListResponse_Activity_:
      properties:
        data:
          items:
            $ref: '#/components/schemas/Activity'
          type: array
          title: Data
          description: List of resources
        pagination:
          $ref: '#/components/schemas/PaginationInfo'
          description: Pagination information
      type: object
      required:
      - data
      - pagination
      title: ListResponse[Activity]
    LinkedAccount:
      properties:
        id:
          type: string
          title: Id
          description: Unique Peerbound identifier for the account
        name:
          type: string
          title: Name
          description: Name of the account
        salesforce_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Salesforce Id
          description: Salesforce Account ID if synced
        hubspot_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Hubspot Id
          description: HubSpot Company ID if synced
      type: object
      required:
      - id
      - name
      title: LinkedAccount
      description: 'Account (customer company) linked to a resource.


        Used for stories, reviews, and moments to reference the associated account.'
    ErrorResponse:
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetail'
          description: Error details
      type: object
      required:
      - error
      title: ErrorResponse
      description: Standard error response format for all API errors.
    ErrorDetail:
      properties:
        code:
          type: string
          title: Code
          description: Machine-readable error code
        message:
          type: string
          title: Message
          description: Human-readable error message
      type: object
      required:
      - code
      - message
      title: ErrorDetail
      description: Details of an API error.
    LinkedContact:
      properties:
        id:
          type: string
          title: Id
          description: Unique Peerbound identifier for the contact
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
          description: Full name of the contact
        email:
          anyOf:
          - type: string
          - type: 'null'
          title: Email
          description: Email address of the contact
        salesforce_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Salesforce Id
          description: Salesforce Contact ID if synced
        hubspot_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Hubspot Id
          description: HubSpot Contact ID if synced
      type: object
      required:
      - id
      title: LinkedContact
      description: 'Contact (person) linked to a resource.


        Used for reviews and moments to reference the associated contact.'