openapi: 3.1.0
info:
  title: CallRail v3 API
  version: "3.0.0"
  description: |
    REST/JSON API for CallRail, a call tracking and conversation intelligence
    platform. Exposes accounts, calls, and related summary/timeseries reporting.
  contact:
    name: CallRail API Support
    url: https://apidocs.callrail.com/
servers:
  - url: https://api.callrail.com/v3
    description: Production
security:
  - TokenAuth: []
tags:
  - name: Accounts
  - name: Calls
paths:
  /a.json:
    get:
      tags: [Accounts]
      summary: List accounts
      description: List all accounts accessible to the API key.
      operationId: listAccounts
      parameters:
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PerPage'
      responses:
        '200':
          description: A paginated list of accounts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountList'
        '401': { $ref: '#/components/responses/Unauthorized' }
        '429': { $ref: '#/components/responses/RateLimited' }
  /a/{account_id}.json:
    get:
      tags: [Accounts]
      summary: Retrieve account
      operationId: getAccount
      parameters:
        - $ref: '#/components/parameters/AccountId'
      responses:
        '200':
          description: Account details.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Account' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
  /a/{account_id}/calls.json:
    get:
      tags: [Calls]
      summary: List calls
      description: List calls for an account. Supports offset or relative pagination.
      operationId: listCalls
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - $ref: '#/components/parameters/Page'
        - $ref: '#/components/parameters/PerPage'
        - name: relative_pagination
          in: query
          schema: { type: boolean }
        - name: start_date
          in: query
          schema: { type: string, format: date }
        - name: end_date
          in: query
          schema: { type: string, format: date }
        - name: direction
          in: query
          schema: { type: string, enum: [inbound, outbound] }
        - name: answered
          in: query
          schema: { type: boolean }
        - name: company_id
          in: query
          schema: { type: string }
        - name: tracker_id
          in: query
          schema: { type: string }
        - name: tags
          in: query
          schema: { type: string }
        - name: fields
          in: query
          description: Comma-separated list of additional fields to include.
          schema: { type: string }
        - name: sorting
          in: query
          schema: { type: string }
        - name: order
          in: query
          schema: { type: string, enum: [asc, desc] }
      responses:
        '200':
          description: A paginated list of calls.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/CallList' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '429': { $ref: '#/components/responses/RateLimited' }
    post:
      tags: [Calls]
      summary: Create outbound call
      operationId: createCall
      parameters:
        - $ref: '#/components/parameters/AccountId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [caller_id, customer_phone_number, business_phone_number]
              properties:
                caller_id: { type: string }
                customer_phone_number: { type: string }
                business_phone_number: { type: string }
                recording_enabled: { type: boolean }
      responses:
        '201':
          description: Call created.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Call' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
  /a/{account_id}/calls/{call_id}.json:
    get:
      tags: [Calls]
      summary: Retrieve call
      operationId: getCall
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - $ref: '#/components/parameters/CallId'
        - name: fields
          in: query
          schema: { type: string }
      responses:
        '200':
          description: Call details.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Call' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
    put:
      tags: [Calls]
      summary: Update call
      description: Update notes, tags, lead status, customer name, or spam flag.
      operationId: updateCall
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - $ref: '#/components/parameters/CallId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                note: { type: string }
                tags:
                  type: array
                  items: { type: string }
                lead_status: { type: string }
                customer_name: { type: string }
                spam: { type: boolean }
      responses:
        '200':
          description: Call updated.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Call' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
  /a/{account_id}/calls/summary.json:
    get:
      tags: [Calls]
      summary: Call summary
      description: Summarized call data grouped by source, keyword, campaign, etc.
      operationId: getCallSummary
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - name: group_by
          in: query
          schema:
            type: string
            enum: [source, keywords, campaign, medium, landing_page, referrer]
        - name: start_date
          in: query
          schema: { type: string, format: date }
        - name: end_date
          in: query
          schema: { type: string, format: date }
      responses:
        '200':
          description: Summary results.
          content:
            application/json:
              schema:
                type: object
                properties:
                  summary:
                    type: array
                    items: { type: object, additionalProperties: true }
  /a/{account_id}/calls/timeseries.json:
    get:
      tags: [Calls]
      summary: Call timeseries
      description: Call data grouped by time intervals.
      operationId: getCallTimeseries
      parameters:
        - $ref: '#/components/parameters/AccountId'
        - name: time_zone
          in: query
          schema: { type: string }
        - name: time_range
          in: query
          schema:
            type: string
            enum: [hour, day, week, month, year]
        - name: start_date
          in: query
          schema: { type: string, format: date }
        - name: end_date
          in: query
          schema: { type: string, format: date }
      responses:
        '200':
          description: Timeseries results.
          content:
            application/json:
              schema:
                type: object
                properties:
                  timeseries:
                    type: array
                    items: { type: object, additionalProperties: true }
components:
  securitySchemes:
    TokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: |
        Send as `Authorization: Token token="YOUR_API_KEY"`.
  parameters:
    AccountId:
      name: account_id
      in: path
      required: true
      schema: { type: string }
    CallId:
      name: call_id
      in: path
      required: true
      schema: { type: string }
    Page:
      name: page
      in: query
      schema: { type: integer, minimum: 1, default: 1 }
    PerPage:
      name: per_page
      in: query
      schema: { type: integer, minimum: 1, maximum: 250, default: 100 }
  responses:
    BadRequest:
      description: Bad request.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    Unauthorized:
      description: Missing or invalid credentials.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    RateLimited:
      description: Rate limit exceeded (1,000/hour or 10,000/day).
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
  schemas:
    Error:
      type: object
      properties:
        error: { type: string }
    Pagination:
      type: object
      properties:
        page: { type: integer }
        per_page: { type: integer }
        total_pages: { type: integer }
        total_records: { type: integer }
    Account:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
        outbound_recording_enabled: { type: boolean }
        hipaa_account: { type: boolean }
        numeric_id: { type: integer }
    AccountList:
      allOf:
        - $ref: '#/components/schemas/Pagination'
        - type: object
          properties:
            accounts:
              type: array
              items: { $ref: '#/components/schemas/Account' }
    Call:
      type: object
      properties:
        id: { type: string }
        answered: { type: boolean }
        business_phone_number: { type: string }
        customer_city: { type: string }
        customer_country: { type: string }
        customer_name: { type: string }
        customer_phone_number: { type: string }
        customer_state: { type: string }
        direction: { type: string, enum: [inbound, outbound] }
        duration: { type: integer }
        recording: { type: string, format: uri }
        recording_duration: { type: integer }
        start_time: { type: string, format: date-time }
        tracking_phone_number: { type: string }
        voicemail: { type: boolean }
        agent_email: { type: string }
        lead_status: { type: string }
        note: { type: string }
        tags:
          type: array
          items: { type: string }
        source: { type: string }
        campaign: { type: string }
        medium: { type: string }
        keywords: { type: string }
        landing_page_url: { type: string }
        referrer_domain: { type: string }
        company_id: { type: string }
        company_name: { type: string }
        tracker_id: { type: string }
    CallList:
      allOf:
        - $ref: '#/components/schemas/Pagination'
        - type: object
          properties:
            calls:
              type: array
              items: { $ref: '#/components/schemas/Call' }